可观测性与稳定性 / 系统课时
接入追踪后端并验证数据
接入追踪后端并验证数据
本课把 Collector 从“只在日志里看到 Span”推进到可查询的追踪系统:启动 Jaeger,配置 Collector 通过 OTLP/gRPC 转发 Trace,再发送一条包含父子 Span 的测试数据。最终要在 Jaeger 中看到 checkout-api 服务、同一个 Trace,以及两个具有父子关系的 Span。
学习目标
- 配置 Collector 的 OTLP Exporter,把 Trace 转发到 Jaeger。
- 发送带
service.name和父子关系的测试 Trace,确认 Collector 接收成功。 - 在 Jaeger 中按服务检索 Trace,并核对 Trace 与 Span 的层级关系。
连接 Collector 与追踪后端
为了让环境可复现,Collector 与 Jaeger 放在同一个 Docker 网络中。应用仍把 OTLP 数据发到本机 4317/4318,Collector 再通过容器名 jaeger:4317 把 Trace 转给后端;Jaeger 的 16686 端口只用于查询界面。

把下面配置保存为 otel-collector.yaml:
receivers:
otlp:
protocols:
grpc:
endpoint: 0.0.0.0:4317
http:
endpoint: 0.0.0.0:4318
processors:
batch: {}
exporters:
debug:
verbosity: detailed
otlp/jaeger:
endpoint: jaeger:4317
tls:
insecure: true
service:
pipelines:
traces:
receivers: [otlp]
processors: [batch]
exporters: [debug, otlp/jaeger]otlp/jaeger 是同一个 Collector 中 OTLP Exporter 的命名实例。这里的 insecure: true 只适用于本机 Docker 网络里的无 TLS 演示链路;生产环境应改成受信任的 TLS 连接。batch 会在导出前批量处理 Span,配置是否生效可通过后续发送 Trace 并在 Jaeger 查询来验证。
启动 Jaeger 与 Collector
先清理同名测试容器,再创建共享网络。Jaeger 不需要把 OTLP 端口暴露给宿主机,因为只有 Collector 会通过 Docker 网络访问它。
docker rm -f otel-collector jaeger >/dev/null 2>&1 || true
docker network rm otel-demo >/dev/null 2>&1 || true
docker network create otel-demo
docker run -d \
--name jaeger \
--network otel-demo \
-p 127.0.0.1:16686:16686 \
cr.jaegertracing.io/jaegertracing/jaeger:2.20.0
docker run -d \
--name otel-collector \
--network otel-demo \
-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}}' jaeger
docker inspect -f '{{.State.Status}}' otel-collector预期输出
<ID>
<ID>
<ID>
running
running三个 <ID> 分别对应 Docker 网络、Jaeger 容器和 Collector 容器,实际值会不同。若 Collector 没有保持 running,优先查看 docker logs otel-collector;其中出现无法连接 jaeger:4317 时,再检查两个容器是否都加入 otel-demo。
发送带父子 Span 的测试 Trace
下面构造一条 Trace:根 Span 是 POST /checkout,子 Span 是 reserve-stock,二者共享同一个 Trace ID,子 Span 的 parentSpanId 指向根 Span。资源属性中的 service.name=checkout-api 会成为后端按服务查询 Trace 的关键维度。
# 使用当前时间,确保 Jaeger 默认的最近时间范围能够命中。
START=$(( $(date +%s) * 1000000000 ))
CHILD_START=$(( START + 50000000 ))
CHILD_END=$(( START + 180000000 ))
END=$(( START + 250000000 ))
# 构造同一 Trace 下的根 Span 与子 Span。
cat > trace.json <<EOF
{
"resourceSpans": [{
"resource": {
"attributes": [{
"key": "service.name",
"value": {"stringValue": "checkout-api"}
}]
},
"scopeSpans": [{
"scope": {"name": "anystack.backend-check"},
"spans": [
{
"traceId": "5b8efff798038103d269b633813fc60c",
"spanId": "a1b2c3d4e5f60718",
"name": "POST /checkout",
"kind": 2,
"startTimeUnixNano": "$START",
"endTimeUnixNano": "$END"
},
{
"traceId": "5b8efff798038103d269b633813fc60c",
"spanId": "b1c2d3e4f5061728",
"parentSpanId": "a1b2c3d4e5f60718",
"name": "reserve-stock",
"kind": 3,
"startTimeUnixNano": "$CHILD_START",
"endTimeUnixNano": "$CHILD_END"
}
]
}]
}]
}
EOF
# 先发送给 Collector,而不是直接绕过 Collector 写入 Jaeger。
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
{}HTTP 200 证明 Collector 接受了 OTLP 请求,但还不能单独证明后端已经可查询。保留 debug Exporter 的价值就在这里:若后端没有 Trace,可以先用 Collector 日志判断故障发生在“应用到 Collector”还是“Collector 到 Jaeger”。
在 Jaeger 中完成验收
浏览器打开 http://127.0.0.1:16686。在服务筛选中选择 checkout-api,查询最近时间范围内的 Trace;应能找到操作名为 POST /checkout 的记录。打开这条 Trace 后,根 Span 下应显示子 Span reserve-stock,并且两者属于同一个 Trace ID。
验收时不要只看“页面里有数据”。service.name 缺失时,后端可能把数据归到默认或未知服务;两个 Span 的 Trace ID 不一致时,它们会成为两条不同 Trace;parentSpanId 错误时,子 Span 也不会挂到正确父节点下。把服务名、Trace ID 和父子层级都核对通过,才算 Collector 到追踪后端的链路完整。
如果 Collector 日志能看到 Span、Jaeger 却查不到,先检查 otlp/jaeger 的 endpoint、Docker 网络和 Collector 日志中的导出错误;如果 Jaeger 能看到服务但找不到刚发送的数据,再确认查询时间范围包含当前时间。这样的分层验证能把“接收失败”和“转发或查询失败”快速区分开。