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

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

text

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 只记录诊断需要且可治理的数据。

HTTP 可使用 W3C traceparent/tracestate；消息要把 context 放入 headers，并在消费端提取。

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

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

采样率要进入指标解释。Trace 被采样不应影响 SLO metrics 的完整统计。

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

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

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

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

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

这样才能回答“错误率是否只在 v42、zone-b、打开新算法的租户上升”。

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