可观测性与稳定性 / 系统课时
建立端到端验证基线
建立端到端验证基线
本节用一条固定 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。

搭建最小可验证通路
下面的主示例使用 Collector 核心镜像。先把 <VERSION> 替换为团队锁定并验证过的 Collector 版本;固定版本比长期使用 latest 更适合作为回归基线。配置显式开放 OTLP/HTTP 4318,并把 Collector 自遥测 Prometheus 端点开放到 8888。
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)'预期输出
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 版本的指标暴露配置和实际抓取实例。基线的价值不在某个具体数字,而在于每次实验都使用同一输入和同一组判据。