使用 Vector 摄取数据 - ClickHouse Documentation

Vector 是一个高性能、厂商中立的可观测性数据管道。它通常用于从各种来源收集、转换和路由日志与指标，并因其灵活性高、资源占用低而被广泛采用，尤其常用于日志摄取。将 Vector 与 ClickStack 结合使用时，用户需要自行定义 schema。这些 schema 可以遵循 OpenTelemetry 约定，也可以完全自定义，用来表示用户定义的事件结构。在实际使用中，Vector 摄取最常见的用途是处理日志，因为用户希望在数据写入 ClickHouse 之前，能够完全掌控解析和富集过程。本指南重点介绍如何使用 Vector 将数据导入 ClickStack，适用于 ClickStack Open Source 和托管 ClickStack。为便于说明，本文不会深入展开介绍 Vector source 或管道配置，而是重点说明如何配置将数据写入 ClickHouse 的 sink，并确保最终生成的 schema 与 ClickStack 兼容。对于 ClickStack，无论使用开源部署还是托管部署，唯一的硬性要求是数据中必须包含一个timestamp 列 (或等效的时间字段) ；该列可在 ClickStack UI 中配置数据源时声明。

通过 Vector 发送数据

托管 ClickStack
开源 ClickStack

以下指南假设您已创建托管 ClickStack 服务并记录了相应的服务凭据。如果尚未完成，请先参阅托管 ClickStack 的 Getting Started 指南，按步骤操作至提示配置 Vector 为止。

创建数据库和表

Vector 要求在摄取数据之前预先定义好表和 schema。首先创建一个数据库。可以通过 ClickHouse Cloud 控制台完成。在下面的示例中，我们使用 logs：

CREATE DATABASE IF NOT EXISTS logs

为您的数据创建一个表。该表应与数据的输出 schema 相匹配。下面的示例假设采用经典的 Nginx 结构。请根据您的数据相应调整，并遵循 schema 最佳实践。我们强烈建议您先熟悉主键的概念，并根据此处所述指南选择主键。

CREATE TABLE logs.nginx_logs
(
    `time_local` DateTime,
    `remote_addr` IPv4,
    `remote_user` LowCardinality(String),
    `request` String,
    `status` UInt16,
    `body_bytes_sent` UInt64,
    `http_referer` String,
    `http_user_agent` String,
    `http_x_forwarded_for` LowCardinality(String),
    `request_time` Float32,
    `upstream_response_time` Float32,
    `http_host` String
)
ENGINE = MergeTree
ORDER BY (toStartOfMinute(time_local), status, remote_addr)

Nginx 主键上述主键是基于 ClickStack UI 中 Nginx 日志的常见访问模式设定的，但在生产环境中可能需要根据你的工作负载进行调整。

在 Vector 配置中添加 ClickHouse sink

修改 Vector 配置，加入 ClickHouse sink，并更新 inputs 字段，使其从现有管道接收事件。此配置假定你的上游 Vector 管道已经将数据处理为符合目标 ClickHouse schema 的格式，也就是说，各字段都已完成解析、正确命名，并设置为适合插入的类型。有关如何将原始日志行解析并规范化为适用于 ClickStack 的 schema 的完整示例，请参见下方的 Nginx 示例。

sinks:
  clickhouse:
    type: clickhouse
    inputs:
      - your_input
    endpoint: "<CLICKHOUSE_ENDPOINT>"
    database: logs
    format: json_each_row
    table: nginx_logs
    skip_unknown_fields: true
    auth:
      strategy: "basic"
      user: "default"
      password: "<CLICKHOUSE_PASSWORD>"

默认情况下，我们建议使用 json_each_row 格式，它会将每个事件编码为每行一个 JSON 对象。这是 ClickStack 摄取 JSON 数据时默认且推荐使用的格式，应优先于其他替代格式，例如将 JSON 对象编码为字符串的格式。ClickHouse sink 也支持 Arrow stream encoding (目前处于 Beta 阶段) 。这种方式可以提供更高的吞吐量，但也有一些重要约束：数据库和表必须是静态的，因为 schema 只会在启动时拉取一次，并且不支持动态路由。因此，Arrow 编码最适合固定且定义明确的摄取管道。我们建议查阅 Vector documentation 中可用的 sink 配置选项：

上面的示例使用的是托管 ClickStack 的默认用户。对于生产部署，我们建议创建专用的摄取用户，并为其分配适当的权限和限制。

前往 ClickStack UI

前往你的托管 ClickStack 服务，并从左侧菜单中选择 “ClickStack”。如果你已经完成引导流程，这将在新标签页中打开 ClickStack UI，并自动完成身份验证。如果尚未完成，你可以继续完成引导流程，并在选择 Vector 作为输入源后点击“Launch ClickStack”。

创建数据源

创建一个日志数据源。如果当前还没有数据源，首次登录时系统会提示你创建一个。否则，请前往 Team Settings，添加一个新的数据源。上述配置假定采用 Nginx 风格的 schema，并将 time_local 列用作时间戳。应尽可能使用在主键中声明的时间戳列。此列为必填项。我们还建议更新 Default SELECT，明确指定日志视图中返回哪些列。如果还有其他可用字段，例如服务名称、日志级别或 body 列，也可以一并配置。如果时间戳显示列与表主键中使用且在上方配置的列不同，也可以单独覆盖。在上面的示例中，数据里并不存在 Body 列。相反，它是通过一个 SQL 表达式定义的，用于根据现有字段重建一条 Nginx 日志行。有关其他可选项，请参阅配置参考。

探查数据

前往日志视图探查数据，并开始使用 ClickStack。

创建数据库和表

Vector 要求在摄取数据之前预先定义好表和 schema。首先创建一个数据库。可通过 ClickHouse Web 用户界面访问 http://localhost:8123/play 来完成。使用默认用户名和密码 api:api。在下面的示例中，我们使用 logs：

CREATE DATABASE IF NOT EXISTS logs

CREATE TABLE logs.nginx_logs
(
    `time_local` DateTime,
    `remote_addr` IPv4,
    `remote_user` LowCardinality(String),
    `request` String,
    `status` UInt16,
    `body_bytes_sent` UInt64,
    `http_referer` String,
    `http_user_agent` String,
    `http_x_forwarded_for` LowCardinality(String),
    `request_time` Float32,
    `upstream_response_time` Float32,
    `http_host` String
)
ENGINE = MergeTree
ORDER BY (toStartOfMinute(time_local), status, remote_addr)

Nginx 主键上述主键是基于 ClickStack UI 中 Nginx 日志的常见访问模式设定的，但在生产环境中可能需要根据你的工作负载进行调整。

在 Vector 配置中添加 ClickHouse sink

对于 Vector，向 ClickStack 摄取数据时应直接发送到 ClickHouse，绕过 collector 暴露的 OTLP 端点。修改 Vector 配置以加入 ClickHouse sink，并更新 inputs 字段，使其从现有管道接收事件。此配置假定你的上游 Vector 管道已经将数据处理为与目标 ClickHouse schema 匹配，也就是说，各个字段都已完成解析、命名正确，并设置了适合插入的类型。有关如何将原始日志行解析并规范化为适用于 ClickStack 的 schema，请参见下面的 Nginx 示例。

sinks:
  clickhouse:
    type: clickhouse
    inputs:
      - your_input
    endpoint: "http://localhost:8123"
    database: logs
    format: json_each_row
    table: nginx_logs
    skip_unknown_fields: true
    auth:
      strategy: "basic"
      user: "api"
      password: "api"

默认情况下，我们建议使用 json_each_row 格式，它会将每个事件编码为每行一个 JSON object。这是 ClickStack 在摄取 JSON 数据时默认且推荐使用的格式，应优先于其他替代格式，例如将 JSON objects 编码为字符串的方式。ClickHouse sink 还支持 Arrow stream encoding (目前处于 Beta 阶段) 。这种方式可以提供更高的吞吐量，但也有一些重要约束：数据库和表必须是静态的，因为 schema 只会在启动时拉取一次，并且不支持动态路由。因此，Arrow encoding 最适合固定且定义明确的摄取管道。我们建议在 Vector documentation 中查看可用的 sink 配置选项：

上面的示例在 ClickStack Open Source 中使用的是 api 用户。对于生产部署，我们建议创建专用的摄取用户，并为其设置适当的权限和限制。上述配置还假设 Vector 与 ClickStack 运行在同一台主机上。在生产部署中，通常并非如此。我们建议通过安全的 HTTPS 端口 8443 发送数据。

前往 ClickStack UI

访问 http://localhost:8080 打开 ClickStack UI。如果你尚未完成引导设置，请先创建一个用户。

创建数据源

前往 Team Settings，然后添加一个新的数据源。上述配置假定使用 Nginx 风格的 schema，并将 time_local 列用作 timestamp。在可能的情况下，这一列应当是在主键中声明的 timestamp 列。此列为必填项。我们还建议更新 Default SELECT，明确指定日志视图中返回哪些列。如果还有其他可用字段，例如 service name、日志级别或 body 列，也可以一并配置。如果 timestamp 显示列不同于表主键中使用且在上方配置的列，也可以单独覆盖。在上面的示例中，数据中不存在 Body 列。相反，它是通过一个 SQL expression 定义的，用于根据现有字段重建一条 Nginx 日志行。如需了解其他可用选项，请参阅配置参考。

探查数据

前往日志视图探查数据，并开始使用 ClickStack。

使用 Vector 的示例数据集

下面我们使用一个 Nginx 日志文件 作为更完整的示例。

托管 ClickStack
开源 ClickStack

以下指南假设您已创建托管 ClickStack 服务并记录了相应的服务凭据。如果尚未完成，请先参阅托管 ClickStack 的 Getting Started 指南，按步骤操作直至出现配置 Vector 的提示。

安装 Vector

继续之前，请确保在计划运行摄取管道的系统上已安装 Vector。请按照 Vector 官方安装指南安装适合您环境的预构建二进制文件或软件包：安装完成后，在继续执行下面的配置步骤之前，请确认 vector 可执行文件已在您的路径中。它也可以安装在与 ClickStack OTel collector 相同的实例上。在将 Vector 部署到生产环境时，请遵循架构和安全方面的最佳实践。

下载示例数据

如果你想用示例数据集进行试验，请下载下面的 nginx 示例。

curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/access.log

这些数据采集自一个 Nginx 实例；该实例已配置为以 JSON 格式输出日志，以便于解析。有关这些日志的 Nginx 配置，请参阅”使用 ClickStack 监控 Nginx 日志”。

创建数据库和表

在开始摄取数据之前，Vector 需要预先定义好表和 schema。首先创建一个数据库。可以通过 ClickHouse Cloud 控制台完成。创建一个名为 logs 的数据库：

CREATE DATABASE IF NOT EXISTS logs

创建一个用于存储数据的表。

CREATE TABLE logs.nginx_logs
(
    `time_local` DateTime,
    `remote_addr` IPv4,
    `remote_user` LowCardinality(String),
    `request` String,
    `status` UInt16,
    `body_bytes_sent` UInt64,
    `http_referer` String,
    `http_user_agent` String,
    `http_x_forwarded_for` LowCardinality(String),
    `request_time` Float32,
    `upstream_response_time` Float32,
    `http_host` String
)
ENGINE = MergeTree
ORDER BY (toStartOfMinute(time_local), status, remote_addr)

Nginx 主键上述主键是根据 ClickStack UI 中 Nginx 日志的常见访问模式设定的，但在生产环境中可能需要根据实际工作负载进行调整。

复制 Vector 配置

复制 Vector 配置，并创建一个 nginx.yaml 文件，设置 CLICKHOUSE_ENDPOINT 和 CLICKHOUSE_PASSWORD。

data_dir: ./.vector-data
sources:
  nginx_logs:
    type: file
    include:
      - access.log
    read_from: beginning

transforms:
  decode_json:
    type: remap
    inputs:
      - nginx_logs
    source: |
      . = parse_json!(to_string!(.message))
      ts = parse_timestamp!(.time_local, format: "%d/%b/%Y:%H:%M:%S %z")
      # ClickHouse-friendly DateTime format
      .time_local = format_timestamp!(ts, format: "%F %T")

sinks:
  clickhouse:
    type: clickhouse
    inputs:
      - decode_json
    endpoint: "<CLICKHOUSE_ENDPOINT>"
    database: logs
    format: json_each_row
    table: nginx_logs
    skip_unknown_fields: true
    auth:
      strategy: "basic"
      user: "default"
      password: "<CLICKHOUSE_PASSWORD>"

上述示例使用了托管 ClickStack 的默认用户。对于生产环境中的部署，我们建议创建专用的摄取用户，并为其设置适当的权限和限制。

启动 Vector

使用以下命令启动 Vector，并先创建数据目录，用于记录文件偏移量。

mkdir ./.vector-data
vector --config nginx.yaml

前往 ClickStack UI

前往你的托管 ClickStack 服务，并在左侧菜单中选择 “ClickStack”。如果你已经完成引导流程，系统会在新标签页中打开 ClickStack UI，并自动完成身份验证。如果还没有，请继续完成引导流程，并在选择 Vector 作为输入源后，选择“启动 ClickStack”。

创建数据源

创建一个日志数据源。如果还没有任何数据源，首次登录时系统会提示你创建一个。否则，请前往 Team Settings 并添加新的数据源。该配置假定使用 Nginx schema，并将 time_local 列作为 timestamp。这是在主键中声明的 timestamp 列。此列是必填项。我们还将默认 select 指定为 time_local, remote_addr, status, request，用于定义日志视图中会返回哪些列。在上面的示例中，数据中并不存在 Body 列。相反，它被定义为以下 SQL expression：

concat(
  remote_addr, ' ',
  remote_user, ' ',
  '[', formatDateTime(time_local, '%d/%b/%Y:%H:%M:%S %z'), '] ',
  '"', request, '" ',
  toString(status), ' ',
  toString(body_bytes_sent), ' ',
  '"', http_referer, '" ',
  '"', http_user_agent, '" ',
  '"', http_x_forwarded_for, '" ',
  toString(request_time), ' ',
  toString(upstream_response_time), ' ',
  '"', http_host, '"'
)

这会根据结构化字段还原日志行。有关其他可用选项，请参阅配置参考。

浏览数据

前往 2025 年 10 月 20 日 的搜索视图，查看数据并开始使用 ClickStack。

以下指南假设您已参照入门指南完成了 ClickStack 开源版的部署。

安装 Vector

下载示例数据

如果你想用示例数据集进行试验，请下载下面的 nginx 示例。

curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/access.log

创建数据库和表

Vector 要求在摄取数据之前预先定义好表和 schema。首先创建一个数据库。可通过 ClickHouse Web 用户界面在 http://localhost:8123/play 中完成。使用默认用户名和密码 api:api。创建数据库 logs：

CREATE DATABASE IF NOT EXISTS logs

创建一个用于存储数据的表。

CREATE TABLE logs.nginx_logs
(
    `time_local` DateTime,
    `remote_addr` IPv4,
    `remote_user` LowCardinality(String),
    `request` String,
    `status` UInt16,
    `body_bytes_sent` UInt64,
    `http_referer` String,
    `http_user_agent` String,
    `http_x_forwarded_for` LowCardinality(String),
    `request_time` Float32,
    `upstream_response_time` Float32,
    `http_host` String
)
ENGINE = MergeTree
ORDER BY (toStartOfMinute(time_local), status, remote_addr)

Nginx 主键上述主键是根据 ClickStack UI 中 Nginx 日志的常见访问模式设定的，但在生产环境中可能需要根据实际工作负载进行调整。

复制 Vector 配置

对于 Vector，向 ClickStack 的摄取应直接写入 ClickHouse，绕过 collector 暴露的 OTLP 端点。复制 Vector 配置并创建文件 nginx.yaml。

data_dir: ./.vector-data
sources:
  nginx_logs:
    type: file
    include:
      - access.log
    read_from: beginning

transforms:
  decode_json:
    type: remap
    inputs:
      - nginx_logs
    source: |
      . = parse_json!(to_string!(.message))
      ts = parse_timestamp!(.time_local, format: "%d/%b/%Y:%H:%M:%S %z")
      # ClickHouse-friendly DateTime format
      .time_local = format_timestamp!(ts, format: "%F %T")

sinks:
  clickhouse:
    type: clickhouse
    inputs:
      - decode_json
    endpoint: "http://localhost:8123"
    database: logs
    format: json_each_row
    table: nginx_logs
    skip_unknown_fields: true
    auth:
      strategy: "basic"
      user: "api"
      password: "api"

上面的示例在 ClickStack Open Source 中使用的是 api 用户。对于生产环境部署，我们建议创建专用的摄取用户，并为其设置适当的权限和限制。上述配置还假定 Vector 与 ClickStack 运行在同一台主机上，但在生产环境中通常并非如此。我们建议通过安全的 HTTPS 8443 端口发送数据。

启动 Vector

运行以下命令启动 Vector。

mkdir ./.vector-data
vector --config nginx-local.yaml

创建数据源

通过 Team -> Sources 创建一个日志数据源该配置假定使用 Nginx schema，并将 time_local 列作为 timestamp 使用。这是主键中声明的 timestamp 列。该列是必填项。我们还将默认选择字段指定为 time_local, remote_addr, status, request，用于定义日志视图中返回哪些列。在上面的示例中，数据中并不存在 Body 列。相反，它被定义为以下 SQL 表达式：

concat(
  remote_addr, ' ',
  remote_user, ' ',
  '[', formatDateTime(time_local, '%d/%b/%Y:%H:%M:%S %z'), '] ',
  '"', request, '" ',
  toString(status), ' ',
  toString(body_bytes_sent), ' ',
  '"', http_referer, '" ',
  '"', http_user_agent, '" ',
  '"', http_x_forwarded_for, '" ',
  toString(request_time), ' ',
  toString(upstream_response_time), ' ',
  '"', http_host, '"'
)

这会根据结构化字段还原日志行。有关其他可用选项，请参阅配置参考。

前往 ClickStack UI

访问 http://localhost:8080 上的 ClickStack UI。如果你尚未完成引导配置，请先创建用户。

浏览数据

前往 2025 年 10 月 20 日 的搜索视图，查看数据并开始使用 ClickStack。

​通过 Vector 发送数据

​使用 Vector 的示例数据集

通过 Vector 发送数据

使用 Vector 的示例数据集