跳转到主要内容
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 的 Getting Started 指南，按步骤操作至提示配置 Vector 为止。
1

​
创建数据库和表

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 日志的常见访问模式设定的，但在生产环境中可能需要根据你的工作负载进行调整。
2

​
在 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 的默认用户。对于生产部署，我们建议创建专用的摄取用户，并为其分配适当的权限和限制。
3

​
前往 ClickStack UI

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

​
创建数据源

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

​
探查数据

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

​
使用 Vector 的示例数据集

下面我们使用一个 Nginx 日志文件 作为更完整的示例。
以下指南假设您已创建托管 ClickStack 服务并记录了相应的服务凭据。如果尚未完成，请先参阅托管 ClickStack 的 Getting Started 指南，按步骤操作直至出现配置 Vector 的提示。
1

​
安装 Vector

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

​
下载示例数据

如果你想用示例数据集进行试验，请下载下面的 nginx 示例。
curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/access.log
这些数据采集自一个 Nginx 实例；该实例已配置为以 JSON 格式输出日志，以便于解析。有关这些日志的 Nginx 配置，请参阅”使用 ClickStack 监控 Nginx 日志”。
3

​
创建数据库和表

在开始摄取数据之前，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 日志的常见访问模式设定的，但在生产环境中可能需要根据实际工作负载进行调整。
4

​
复制 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 兼容的 DateTime 格式
      .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 的默认用户。对于生产环境中的部署，我们建议创建专用的摄取用户，并为其设置适当的权限和限制。
5

​
启动 Vector

使用以下命令启动 Vector，并先创建数据目录，用于记录文件偏移量。
mkdir ./.vector-data
vector --config nginx.yaml
6

​
前往 ClickStack UI

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

​
创建数据源

创建一个日志数据源。如果还没有任何数据源，首次登录时系统会提示你创建一个。否则，请前往 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, '"'
)
这会根据结构化字段还原日志行。有关其他可用选项，请参阅配置参考。
8

​
查看数据

前往 2025 年 10 月 20 日 的搜索视图，查看数据并开始使用 ClickStack。
最后修改于 2026年6月10日