可观测性与稳定性 / 系统课时
启动 OpenTelemetry Collector
启动 OpenTelemetry Collector
本课用一个最小配置把 OpenTelemetry Collector 跑起来:同时开放 OTLP/gRPC 与 OTLP/HTTP,只处理 Trace,并把收到的 Span 交给 debug exporter 打到容器日志。完成后,你能用一条 OTLP/HTTP 请求确认“端口可达、管道生效、数据确实进入 Collector”。
学习目标
- 写出包含 OTLP Receiver、Trace Pipeline 与
debugExporter 的最小配置。 - 用 Docker 启动 Collector,并确认 4317、4318 两个接收端口可用。
- 发送一条最小 OTLP Trace,从调试日志核对
service.name、Trace ID 与 Span 名称。
写出最小接收管道
Collector 的配置不是“声明了组件就会自动工作”。Receiver 和 Exporter 必须被引用到 service.pipelines 中,数据才会沿着管道流动。本课只验证 Trace,因此无需先引入指标、日志或复杂 Processor。

把下面内容保存为当前目录的 otel-collector.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 镜像版本启动容器,并只把接收端口绑定到本机回环地址,避免局域网中的其他主机直接访问测试端点。
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预期输出
<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 都被解析。
# 使用当前时间,便于检查接收端看到的真实时间范围。
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预期输出
HTTP 200
{}再检查 Collector 的详细日志:
docker logs otel-collector 2>&1 \
| grep -E 'service.name|Trace ID|Name' \
| tail -n 6预期输出
-> 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 当长期存储,它只用于验证与排障,后续应把数据转发到真正的追踪后端。