使用 OpenTelemetry 进行数据摄取

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

用户可以通过 language SDKs 将数据发送到该 collector，或者通过采集基础设施指标和日志的数据采集代理发送数据（例如以 agent 角色运行的 OTel collector，或其他技术，如 Fluentd 或 Vector）。

安装 ClickStack OpenTelemetry 收集器

ClickStack OpenTelemetry 收集器包含在大多数 ClickStack 发行版中，包括：

• 一体化部署（All-in-One）
• Docker Compose
• Helm

独立部署

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

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

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

我们推荐使用 ClickStack OpenTelemetry collector

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

更多详情请参阅《部署 collector》。

发送 OpenTelemetry 数据

要将数据发送到 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=<您的摄取_API_密钥>'

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

# clickhouse-agent-config.yaml \{#clickhouse-agent-configyaml}
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: 1000
service:
  telemetry:
    metrics:
      address: 0.0.0.0:9888 # 已修改，因为同一主机上运行 2 个采集器
  pipelines:
    logs:
      receivers: [filelog]
      processors: [batch]
      exporters: [otlphttp/hdx]