Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

使用 Vector 摄取数据

View as MarkdownEdit this pageReport an issueSet up docs MCP

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 为止。

创建数据库和表

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)

在 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 配置选项：

创建数据源

创建一个日志数据源。如果当前还没有数据源，首次登录时系统会提示你创建一个。否则，请前往 Team Settings，添加一个新的数据源。

创建数据源 - vector

上述配置假定采用 Nginx 风格的 schema，并将 time_local 列用作时间戳。应尽可能使用在主键中声明的时间戳列。此列为必填项。

我们还建议更新 Default SELECT，明确指定日志视图中返回哪些列。如果还有其他可用字段，例如服务名称、日志级别或 body 列，也可以一并配置。如果时间戳显示列与表主键中使用且在上方配置的列不同，也可以单独覆盖。

在上面的示例中，数据里并不存在 Body 列。相反，它是通过一个 SQL 表达式定义的，用于根据现有字段重建一条 Nginx 日志行。

有关其他可选项，请参阅配置参考。

探查数据

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

ClickStack 中的 Nginx 日志

使用 Vector 的示例数据集

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

以下指南假设您已创建托管 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

创建数据库和表

在开始摄取数据之前，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)

复制 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>"

启动 Vector

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

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

创建数据源

创建一个日志数据源。如果还没有任何数据源，首次登录时系统会提示你创建一个。否则，请前往 Team Settings 并添加新的数据源。

创建数据源 - vector

该配置假定使用 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。

HyperDX UI
Navigation