使用 OpenTelemetry 进行数据摄取

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

用户可以通过 language SDKs 将数据发送到该 collector，或者通过采集基础设施指标和日志的数据采集代理发送数据（例如以 agent 角色运行的 OTel collector，或其他技术，如 Fluentd 或 Vector）。对于希望使用托管 OpenTelemetry 管道的团队，Bindplane提供一个原生支持 OpenTelemetry 的解决方案，内置 ClickStack 目标端，从而简化遥测数据的采集、处理和路由。

发送 OpenTelemetry 数据

托管版 ClickStack

安装 ClickStack OpenTelemetry collector

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

我们推荐使用 ClickStack OpenTelemetry collector

这使您能够受益于标准化的摄取、统一的 schema 约束，以及与 ClickStack UI（HyperDX）的开箱即用兼容性。使用默认 schema 可启用自动来源识别和预配置的列映射。

更多详情请参阅《部署 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 setup
  otlphttp/hdx:
    endpoint: 'http://localhost:4318'
    compression: gzip
 
  # gRPC setup (alternative)
  otlp/hdx:
    endpoint: 'localhost:4317'
    compression: gzip
processors:
  batch:
    timeout: 5s
    send_batch_size: 1000
service:
  telemetry:
    metrics:
      address: 0.0.0.0:9888 # Modified as 2 collectors running on same host
  pipelines:
    logs:
      receivers: [filelog]
      processors: [batch]
      exporters: [otlphttp/hdx]

开源 ClickStack

ClickStack OpenTelemetry collector 已包含在大多数 ClickStack 发行版中，包括：

• All-in-One
• Docker Compose
• Helm

安装 ClickStack OpenTelemetry collector

ClickStack OTel collector 也可以以独立方式部署，而无需依赖整个技术栈中的其他组件。

如果您使用的是 HyperDX-only 发行版，则需要自行负责将数据写入 ClickHouse。可以通过以下方式实现：

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

我们推荐使用 ClickStack OpenTelemetry collector

这使您能够受益于标准化的摄取、统一的 schema 约束，以及与 HyperDX UI 的开箱即用兼容性。使用默认 schema 可启用自动来源识别和预配置的列映射。

更多详情请参阅《部署 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

此外，请在请求中添加包含 API 摄取密钥的 Authorization 头。您可以在 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>，用于数据摄取的 API 密钥）。

# 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 setup
  otlphttp/hdx:
    endpoint: 'http://localhost:4318'
    headers:
      authorization: <YOUR_API_INGESTION_KEY>
    compression: gzip
 
  # gRPC setup (alternative)
  otlp/hdx:
    endpoint: 'localhost:4317'
    headers:
      authorization: <YOUR_API_INGESTION_KEY>
    compression: gzip
processors:
  batch:
    timeout: 5s
    send_batch_size: 1000
service:
  telemetry:
    metrics:
      address: 0.0.0.0:9888 # Modified as 2 collectors running on same host
  pipelines:
    logs:
      receivers: [filelog]
      processors: [batch]
      exporters: [otlphttp/hdx]