可观测性与稳定性 / 系统课时

启动 OpenTelemetry Collector

启动 OpenTelemetry Collector

本课用一个最小配置把 OpenTelemetry Collector 跑起来:同时开放 OTLP/gRPC 与 OTLP/HTTP,只处理 Trace,并把收到的 Span 交给 debug exporter 打到容器日志。完成后,你能用一条 OTLP/HTTP 请求确认“端口可达、管道生效、数据确实进入 Collector”。

学习目标

  • 写出包含 OTLP Receiver、Trace Pipeline 与 debug Exporter 的最小配置。
  • 用 Docker 启动 Collector,并确认 4317、4318 两个接收端口可用。
  • 发送一条最小 OTLP Trace,从调试日志核对 service.name、Trace ID 与 Span 名称。

写出最小接收管道

Collector 的配置不是“声明了组件就会自动工作”。Receiver 和 Exporter 必须被引用到 service.pipelines 中,数据才会沿着管道流动。本课只验证 Trace,因此无需先引入指标、日志或复杂 Processor。

OTLP 数据进入 Collector 并由 debug exporter 输出的最小链路

把下面内容保存为当前目录的 otel-collector.yaml:

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

exporters:
  debug:
    verbosity: detailed

service:
  pipelines:
    traces:
      receivers: [otlp]
      exporters: [debug]

这里把 Receiver 绑定到容器内的 0.0.0.0,否则宿主机映射到容器端口后可能仍无法访问。debug 的 detailed 模式会展开资源属性和 Span 细节,适合搭环境时确认数据形态;验证方法是启动容器后向 /v1/traces 发送 OTLP/HTTP 数据并查看日志。

启动并确认端口

下面使用固定 Collector 镜像版本启动容器,并只把接收端口绑定到本机回环地址,避免局域网中的其他主机直接访问测试端点。

bash
docker rm -f otel-collector >/dev/null 2>&1 || true
docker run -d \
  --name otel-collector \
  -p 127.0.0.1:4317:4317 \
  -p 127.0.0.1:4318:4318 \
  -v "$PWD/otel-collector.yaml:/etc/otelcol/config.yaml:ro" \
  otel/opentelemetry-collector:0.158.0

docker inspect -f '{{.State.Status}}' otel-collector
docker port otel-collector 4317
docker port otel-collector 4318

预期输出

text
<ID>
running
127.0.0.1:4317
127.0.0.1:4318

<ID> 是容器 ID,实际值会不同。若状态不是 running,先执行 docker logs otel-collector;配置缩进、挂载路径错误或端口被占用都会导致容器退出。

发送 Trace 并读取调试日志

OTLP/HTTP 的 Trace 默认路径是 /v1/traces。下面生成一个带当前时间戳的最小 Span,并明确设置资源属性 service.name=demo-api,这样可以直接从 debug exporter 的输出确认资源与 Span 都被解析。

bash
# 使用当前时间,便于检查接收端看到的真实时间范围。
START=$(( $(date +%s) * 1000000000 ))
END=$(( START + 50000000 ))

# 构造一个最小 OTLP/JSON Trace。
cat > trace.json <<EOF
{
  "resourceSpans": [{
    "resource": {
      "attributes": [{
        "key": "service.name",
        "value": {"stringValue": "demo-api"}
      }]
    },
    "scopeSpans": [{
      "scope": {"name": "anystack.collector-check"},
      "spans": [{
        "traceId": "5b8efff798038103d269b633813fc60c",
        "spanId": "a1b2c3d4e5f60718",
        "name": "GET /health",
        "kind": 2,
        "startTimeUnixNano": "$START",
        "endTimeUnixNano": "$END"
      }]
    }]
  }]
}
EOF

# 通过 OTLP/HTTP 发送到 Collector。
curl -sS \
  -o /tmp/otlp-response.json \
  -w 'HTTP %{http_code}\n' \
  -H 'Content-Type: application/json' \
  --data-binary @trace.json \
  http://127.0.0.1:4318/v1/traces
cat /tmp/otlp-response.json

预期输出

text
HTTP 200
{}

再检查 Collector 的详细日志:

bash
docker logs otel-collector 2>&1 \
  | grep -E 'service.name|Trace ID|Name' \
  | tail -n 6

预期输出

text
-> service.name: Str(demo-api)
Trace ID       : 5b8efff798038103d269b633813fc60c
Name           : GET /health

只看到 HTTP 200 代表 Collector 接受了请求;同时看到资源属性、Trace ID 和 Span 名称,才说明 Receiver、Trace Pipeline 与 debug Exporter 三段都已连通。

处理最常见的启动失败

端口占用时,Docker 会在启动阶段报告 4317 或 4318 无法绑定,应先停止占用端口的进程或改宿主机映射。容器立即退出时,优先读 docker logs otel-collector,YAML 缩进和错误的挂载路径最常见。

如果请求返回连接失败而容器仍在运行,检查 docker port otel-collector 与请求地址是否一致;如果请求成功却没有 Span 详情,则确认 debug 已被写进 service.pipelines.traces.exporters。生产环境不应把 debug 当长期存储,它只用于验证与排障,后续应把数据转发到真正的追踪后端。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

启动 OpenTelemetry Collector

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通