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

建立端到端验证基线

建立端到端验证基线

本节用一条固定 OTLP Trace 请求,把“请求已发送、Trace 已进入 Collector、Collector 已成功导出”串成可重复验证链路,并把 Trace ID 与 Collector 自遥测一起记录,作为后续改配置、换 Exporter 或做故障实验时的对照基线。

学习目标

  • 构造一条输入结构与 Trace ID 都固定的最小 Trace 请求
  • 用 Collector 日志和自遥测指标同时确认接收与导出链路
  • 把一次“看起来成功”固化成可重复执行、可比较的验收步骤

基线要固定什么

可重复验证至少要固定三件事:刺激输入、关联标识和验收证据。只固定请求而不记录 Trace ID,出现多条相似 Trace 时很难确认目标;只看 Trace 而不看 Collector 自遥测,又无法判断问题发生在接收、处理还是导出阶段。

本节直接向 Collector 的 OTLP/HTTP 端点发送一个固定 Span。这样无需依赖业务框架或自动埋点,就能先证明 Collector 通路本身可用。真实业务接入时可继续沿用同一验收方法,但业务 Trace ID 通常由 SDK 每次重新生成,应记录本次实际值,而不是要求多次请求得到相同 ID。

固定请求、Trace ID 与 Collector 自遥测组成的端到端验证基线

搭建最小可验证通路

下面的主示例使用 Collector 核心镜像。先把 <VERSION> 替换为团队锁定并验证过的 Collector 版本;固定版本比长期使用 latest 更适合作为回归基线。配置显式开放 OTLP/HTTP 4318,并把 Collector 自遥测 Prometheus 端点开放到 8888。

bash
set -euo pipefail
export OTELCOL_VERSION="<VERSION>"

cat > otelcol-baseline.yaml <<'YAML'
receivers:
  otlp:
    protocols:
      http:
        endpoint: 0.0.0.0:4318

exporters:
  debug:
    verbosity: detailed

service:
  telemetry:
    metrics:
      level: normal
      readers:
        - pull:
            exporter:
              prometheus:
                host: 0.0.0.0
                port: 8888
  pipelines:
    traces:
      receivers: [otlp]
      exporters: [debug]
YAML

cat > trace-baseline.json <<'JSON'
{
  "resourceSpans": [{
    "resource": {
      "attributes": [{
        "key": "service.name",
        "value": {"stringValue": "baseline-client"}
      }]
    },
    "scopeSpans": [{
      "scope": {"name": "baseline.manual"},
      "spans": [{
        "traceId": "11111111111111111111111111111111",
        "spanId": "2222222222222222",
        "name": "baseline.request",
        "kind": 2,
        "startTimeUnixNano": "1700000000000000000",
        "endTimeUnixNano": "1700000000050000000",
        "status": {"code": 1}
      }]
    }]
  }]
}
JSON

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

for _ in {1..30}; do
  if curl -fsS http://localhost:8888/metrics >/dev/null; then
    break
  fi
  sleep 1
done
curl -fsS http://localhost:8888/metrics >/dev/null

curl -sS -o /tmp/otel-response.json -w 'HTTP %{http_code}\n' -H 'Content-Type: application/json' --data-binary @trace-baseline.json http://localhost:4318/v1/traces
docker logs otelcol-baseline 2>&1 | grep '11111111111111111111111111111111'
curl -sS http://localhost:8888/metrics | grep -E 'otelcol_(receiver_accepted_spans|exporter_sent_spans)'

预期输出

text
HTTP 200
<MATCHING_LOG_LINE_WITH_TRACE_ID_11111111111111111111111111111111>
otelcol_receiver_accepted_spans{...} <VALUE>
otelcol_exporter_sent_spans{...} <VALUE>

日志格式、标签集合与计数值可能随 Collector 版本和重复执行次数不同,因此只要求三件事稳定成立:HTTP 返回成功状态、日志能匹配固定 Trace ID、接收与导出 Span 的计数都大于 0。<VALUE> 可能大于 1,不应把绝对值写死成验收条件。

示例中的时间戳故意固定,适合验证 Collector 接收与处理通路;如果把同一请求改发到有数据保留窗口的真实后端,应换成当前时间戳,同时继续固定请求结构、Trace ID 记录方式和验收判据。

把验收变成四步闭环

每次修改 Collector 配置、Processor 或 Exporter 后,都重复同一顺序:先发送固定请求,再保存本次 Trace ID,然后确认目标 Trace 能在导出侧出现,最后检查 Collector 自遥测是否与数据流方向一致。这样能把“后端没看到 Trace”拆成可定位的问题,而不是直接猜网络、采样或后端故障。

若固定请求返回成功但日志没有目标 Trace,优先检查 traces pipeline 是否仍连接了正确 Receiver 与 Exporter;若日志能看到 Trace 而自遥测的导出计数没有变化,则继续核对当前 Collector 版本的指标暴露配置和实际抓取实例。基线的价值不在某个具体数字,而在于每次实验都使用同一输入和同一组判据。

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

目录与阅读设置

阅读设置

17

记录一个想法

建立端到端验证基线

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

登录哪都通