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

接入追踪后端并验证数据

接入追踪后端并验证数据

本课把 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 端口只用于查询界面。

应用经 Collector 转发 Trace 到 Jaeger 并在查询界面验证的链路

把下面配置保存为 otel-collector.yaml:

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 网络访问它。

bash
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

预期输出

text
<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 的关键维度。

bash
# 使用当前时间,确保 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

预期输出

text
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 能看到服务但找不到刚发送的数据,再确认查询时间范围包含当前时间。这样的分层验证能把“接收失败”和“转发或查询失败”快速区分开。

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

目录与阅读设置

阅读设置

17

记录一个想法

接入追踪后端并验证数据

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

登录哪都通