8.2 埋点、上下文传播与 Telemetry Pipeline

可观测管线通常包含应用中的 API/SDK 与自动埋点、上下文传播、Collector 处理，以及一个或多个存储查询后端。

Application SDK / auto-instrumentation
              ↓ OTLP
Agent/Gateway Collector
   ↓ batch/filter/sample/redact
Metrics · Logs · Trace backends

OpenTelemetry 标准化数据生成、资源属性、语义约定和传输，不负责规定唯一存储后端。

自动与手动埋点配合

自动埋点适合 HTTP、数据库和消息客户端等通用边界；手动埋点表达业务步骤、领域结果和队列语义。

Span 名称应低基数，如 POST /orders/{id}/settlements，不能直接使用真实 URL。attributes 只记录诊断需要且可治理的数据。

Context 必须跨同步与异步边界传播

HTTP 可使用 W3C traceparent/tracestate；消息要把 context 放入 headers，并在消费端提取。例如版本 00 的 traceparent 可写为 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01，其中 trace ID 为 32 个十六进制字符、parent ID 为 16 个，均不能全零。这里的 parent ID 是发送端传播的 span 标识，接收端创建自己的新 span；01 的 sampled 标志也不保证后端最终保留完整 trace。

不要盲目信任外部传入 trace headers：要校验格式、限制 baggage，并在信任边界决定是否保留或重建 context。Baggage 会向下游传播，不应放密钥和敏感个人信息。

线程池、future、协程和消息回调可能丢失上下文，需要框架集成或显式 attach/detach。上下文泄漏到下一请求同样危险。

Sampling 的位置改变可见性

• head sampling 在 trace 开始时决定，成本可控但可能丢掉后来发生的错误；
• tail sampling 在等待窗口内按已到达的 spans 决定，可优先保留错误/慢请求，但长 trace 或迟到 span 可能超出窗口，还需要 Collector 缓冲和更多资源；
• probabilistic、rate limiting 和规则采样可以组合。

同一 trace 的 spans 通常要按 trace ID 路由到同一个尾部采样实例，否则每个实例只看到半条链。头部采样已经丢掉的 spans 也无法在尾部补回来，两个策略不能只按各自“保留错误”的说明拼接。

SLO 计数应从覆盖全部相关请求的指标路径产生。若先按错误、延迟做尾部采样，再从剩下的 spans 计算错误率，结果会偏向错误和慢请求，除以一个采样率也不能修正这种选择偏差。独立指标路径本身仍需监控丢失与导出失败。

Collector 是有容量上限的系统

Collector 需要队列、batch、retry、内存限制和持久缓冲策略。后端不可用时，不能让 telemetry 无限占用业务节点磁盘和内存。

持久队列只能保留已经成功入队的数据，也有磁盘容量和重试期限；它不能补回 SDK 里尚未导出的 spans，更不自动提供端到端 exactly-once。内存限制、batch、采样、脱敏等处理顺序也影响实际峰值和数据泄漏窗口，应随配置验证。

应监控 Collector 自身：接收/导出速率、拒绝、丢弃、队列长度、最老数据、重试和 CPU/内存。

Telemetry 必须可降级

埋点或导出失败不能阻塞业务请求。同步日志写远端、每请求强制 flush trace、无界日志缓冲都会把观测系统变成故障源。

为审计而必须可靠保存的记录属于审计业务数据，应使用独立可靠路径，不能与尽力而为的 debug telemetry 混淆。

版本和变更关联

所有信号都应带可控资源属性：服务名、版本、环境、区域/zone、实例和部署标识。发布、配置和 feature flag 变更以事件或 annotation 进入时间线。

这样才能回答“错误率是否只在 v42、zone-b、打开新算法的租户上升”。版本、区域和有限的功能开关状态可以用于聚合；逐租户排查优先依靠受控日志或 traces，不能为了这个问题把所有租户 ID 都塞进长期 metric labels。

第 12 章会深化基数预算、告警、仪表盘、RUM 与合成监控。

参考资料

• W3C, Trace Context

• OpenTelemetry, Sampling

• OpenTelemetry, Scaling the Collector

• OpenTelemetry, Collector resiliency

• OpenTelemetry, Specification Overview

• OpenTelemetry, Context Propagation

• OpenTelemetry Collector, Documentation