通过 OpenTelemetry 进行数据摄取

所有数据都会通过一个 OpenTelemetry (OTel) collector 实例摄取到 ClickStack，该实例是日志、指标、链路追踪和会话数据的主要入口。我们建议此实例使用官方提供的 collector ClickStack 发行版。

此外还提供托管版 ClickStack — 请参阅 Managed ClickStack。

用户可以通过语言 SDK将数据发送到此 collector，也可以通过采集基础设施指标和日志的数据采集 agent 发送 (例如以 agent 角色运行的 OTel collector，或其他技术，例如 Fluentd 或 Vector) 。对于希望使用托管 OpenTelemetry 管道的团队，Bindplane 提供了一种 OpenTelemetry 原生解决方案，并内置原生 ClickStack 目标端，可简化遥测数据的收集、处理和路由。

发送 OpenTelemetry 数据

托管 ClickStack
开源 ClickStack

安装 ClickStack OpenTelemetry collector

要将数据发送到托管 ClickStack，应以网关角色部署一个 OTel collector。与 OTel 兼容的插桩会通过基于 HTTP 或 gRPC 的 OTLP 将事件发送到该 collector。

我们建议使用 ClickStack OpenTelemetry collector这样您就可以受益于标准化摄取、强制执行的 schema，以及与 ClickStack UI (HyperDX) 的开箱即用兼容性。使用默认 schema 可启用自动 source 检测和预配置的列映射。

更多详情，请参阅”部署 collector”。

向 collector 发送数据

要将数据发送到托管 ClickStack，请将您的 OpenTelemetry 插桩指向 OpenTelemetry collector 提供的以下端点：

HTTP (OTLP): http://localhost:4318
gRPC (OTLP): localhost:4317

对于支持 OpenTelemetry 的语言 SDK和遥测库，您只需在应用程序中设置 OTEL_EXPORTER_OTLP_ENDPOINT 环境变量：

export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318

如果以 agent 角色部署 OTel collector 的 contrib 发行版，则可使用 OTLP exporter 将数据发送到 ClickStack collector。下面展示了一个 agent 配置示例，它会读取这个结构化日志文件。

# clickhouse-agent-config.yaml
receivers:
  filelog:
    include:
      - /opt/data/logs/access-structured.log
    start_at: beginning
    operators:
      - type: json_parser
        timestamp:
          parse_from: attributes.time_local
          layout: '%Y-%m-%d %H:%M:%S'
exporters:
  # HTTP 配置
  otlphttp/hdx:
    endpoint: 'http://localhost:4318'
    compression: gzip
 
  # gRPC 配置（备选）
  otlp/hdx:
    endpoint: 'localhost:4317'
    compression: gzip
processors:
  batch:
    timeout: 5s
    send_batch_size: 10000
service:
  telemetry:
    metrics:
      address: 0.0.0.0:9888 # 已修改，因为同一主机上运行着 2 个 collector
  pipelines:
    logs:
      receivers: [filelog]
      processors: [batch]
      exporters: [otlphttp/hdx]

大多数 ClickStack 发行版都包含 ClickStack OpenTelemetry collector，包括：

安装 ClickStack OpenTelemetry collector

ClickStack OTel collector 也可以独立部署，不依赖于栈中的其他组件。如果你使用的是 HyperDX-only 发行版，则需要自行负责将数据发送到 ClickHouse。可通过以下方式实现：

运行你自己的 OpenTelemetry collector，并将其指向 ClickHouse——见下文。
使用其他工具直接发送到 ClickHouse，例如 Vector、Fluentd 等，甚至默认的 OTel contrib collector 发行版。

我们建议使用 ClickStack OpenTelemetry collector这样你可以受益于标准化摄取、强制 schema 约束，以及与 HyperDX UI 的开箱即用兼容性。使用默认 schema 可启用自动 source 检测和预配置的列映射。

更多详情，请参阅“部署 collector”。

将数据发送到 collector

要将数据发送到 ClickStack，请将你的 OpenTelemetry instrumentation 指向 OpenTelemetry collector 提供的以下端点：

HTTP (OTLP): http://localhost:4318
gRPC (OTLP): localhost:4317

对于支持 OpenTelemetry 的语言 SDK和 telemetry 库，你只需在应用程序中设置 OTEL_EXPORTER_OTLP_ENDPOINT 环境变量：

export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318

此外，还需要提供一个包含 API 摄取密钥的授权请求头。你可以在 HyperDX 应用中的 Team Settings → API Keys 下找到该密钥。对于语言 SDK，这既可以通过 init 函数设置，也可以通过 OTEL_EXPORTER_OTLP_HEADERS 环境变量设置，例如：

OTEL_EXPORTER_OTLP_HEADERS='authorization=<YOUR_INGESTION_API_KEY>'

agent 同样应在所有 OTLP 通信中包含此授权请求头。例如，如果以 agent 角色部署 OTel collector 的 contrib 发行版，则可以使用 OTLP exporter。下面展示了一个读取此结构化日志文件的 agent 配置示例。请注意，需要指定授权密钥，参见 <YOUR_API_INGESTION_KEY>。

# clickhouse-agent-config.yaml
receivers:
  filelog:
    include:
      - /opt/data/logs/access-structured.log
    start_at: beginning
    operators:
      - type: json_parser
        timestamp:
          parse_from: attributes.time_local
          layout: '%Y-%m-%d %H:%M:%S'
exporters:
  # HTTP 配置
  otlphttp/hdx:
    endpoint: 'http://localhost:4318'
    headers:
      authorization: <YOUR_API_INGESTION_KEY>
    compression: gzip
 
  # gRPC 配置（备选方案）
  otlp/hdx:
    endpoint: 'localhost:4317'
    headers:
      authorization: <YOUR_API_INGESTION_KEY>
    compression: gzip
processors:
  batch:
    timeout: 5s
    send_batch_size: 10000
service:
  telemetry:
    metrics:
      address: 0.0.0.0:9888 # 已修改，因为同一主机上运行了 2 个 collector
  pipelines:
    logs:
      receivers: [filelog]
      processors: [batch]
      exporters: [otlphttp/hdx]

Features

Guides

发送 OpenTelemetry 数据

安装 ClickStack OpenTelemetry collector

向 collector 发送数据

安装 ClickStack OpenTelemetry collector

将数据发送到 collector

​发送 OpenTelemetry 数据

​安装 ClickStack OpenTelemetry collector

​向 collector 发送数据

​安装 ClickStack OpenTelemetry collector

​将数据发送到 collector

发送 OpenTelemetry 数据

安装 ClickStack OpenTelemetry collector

向 collector 发送数据

安装 ClickStack OpenTelemetry collector

将数据发送到 collector