OpenTelemetry

使用 Docker Compose 运行 OpenTelemetry Collector

从挂载的配置文件启动 Collector,向它发送测试数据,并在 debug exporter 中查看。

10 min 初级

本指南从一个 YAML 文件在本地运行 Collector,向它发送一条追踪和一个指标,并打印它收到的内容。没有任何东西是在 UI 中配置的:Collector 没有 UI,一切都在一个文件里。你需要安装了 Compose 插件的 Docker 和 curl。

选择镜像

项目发布了几种 Collector 发行版。核心镜像(otel/opentelemetry-collector)拥有一小组组件。contrib 镜像(otel/opentelemetry-collector-contrib)包含庞大的社区组件集合,而面向 Kubernetes 的镜像(otel/opentelemetry-collector-k8s)包含监控集群所需的组件。本系列后面用到的许多组件,比如 filelog 或 tail_sampling,不在核心镜像中。为了学习,请使用 contrib。在真实使用中请固定一个具体的版本,如这些示例所示,并把版本替换为你想要的发布版本。

项目布局

otel-demo/
├── compose.yaml
└── otel-collector-config.yaml

Collector 配置

otel-collector-config.yaml:

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318

processors:
  batch:

exporters:
  debug:
    verbosity: detailed

extensions:
  health_check:
    endpoint: 0.0.0.0:13133

service:
  extensions: [health_check]
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [debug]
    metrics:
      receivers: [otlp]
      processors: [batch]
      exporters: [debug]
    logs:
      receivers: [otlp]
      processors: [batch]
      exporters: [debug]

自上而下阅读:

receivers 定义数据如何进入。otlp 在 4317 上监听 gRPC,在 4318 上监听 HTTP。
processors 在传输途中更改数据。batch 将条目分组,使导出更高效。
exporters 将数据发送出去。debug 把它打印到 Collector 自己的日志中,这正是你在学习时想要的。
extensions 在管线旁边添加能力。health_check 提供一个健康端点。
service 把东西打开。定义一个组件本身什么也不做,直到它被列在这里,并且每种信号都有自己的管线。

端点使用 0.0.0.0,使容器可以从外部访问。Collector 的默认值是 localhost,当所有发送方都在本地时这更安全,所以只在你需要的地方才绑定到 0.0.0.0。

compose 文件

compose.yaml:

services:
  otel-collector:
    image: otel/opentelemetry-collector-contrib:0.163.0   # pin a version you have tested
    command: ["--config=/etc/otelcol/config.yaml"]
    volumes:
      - ./otel-collector-config.yaml:/etc/otelcol/config.yaml:ro
    ports:
      - "4317:4317"     # OTLP gRPC
      - "4318:4318"     # OTLP HTTP
      - "13133:13133"   # health_check
      - "8888:8888"     # the Collector's own metrics

配置路径 /etc/otelcol/config.yaml 是官方镜像默认查找的位置。你可能遇到的其他端口有:用于 zpages 扩展的 55679,以及用于 Prometheus exporter 的 8889。

启动之前先验证

Collector 可以在不运行的情况下检查配置:

docker run --rm -v $(pwd)/otel-collector-config.yaml:/etc/otelcol/config.yaml:ro \
  otel/opentelemetry-collector-contrib:0.163.0 validate --config=/etc/otelcol/config.yaml

干净地退出意味着文件能被解析,并且每个被引用的组件都存在于这个发行版中。也请在 CI 中运行它。一个常见的失败是使用了不在你所选镜像中的组件。

启动并检查健康

docker compose up -d
curl -s http://localhost:13133
docker compose logs otel-collector | tail -n 20

健康端点返回一个小的 JSON 状态,日志应当显示 Collector 启动它的管线并在 4317 和 4318 上监听。

发送测试遥测数据

使用纯 curl 通过 HTTP 发送 OTLP。发送一个 span:

curl -s -X POST http://localhost:4318/v1/traces \
  -H 'Content-Type: application/json' \
  -d '{
    "resourceSpans": [{
      "resource": { "attributes": [{ "key": "service.name", "value": { "stringValue": "demo" } }] },
      "scopeSpans": [{
        "spans": [{
          "traceId": "5b8efff798038103d269b633813fc60c",
          "spanId": "eee19b7ec3c1b174",
          "name": "hello",
          "kind": 1,
          "startTimeUnixNano": "1700000000000000000",
          "endTimeUnixNano": "1700000001000000000"
        }]
      }]
    }]
  }'

响应中为空的 JSON 对象表示它已被接受。现在查看 Collector 的日志:

docker compose logs otel-collector | grep -A8 'hello'

debug exporter 会打印该 span、它的资源(service.name: demo)及其耗时。你已经有了一条可用的管线。

修改配置并重新加载

Collector 在启动时读取它的文件。编辑之后:

docker compose restart otel-collector

请把这个文件夹保存在 Git 中。后面的指南会用真实的 exporter 取代 debug,并向同一个文件添加 processor 和 extension。

清理

docker compose down

RackMint