追踪上下文传播：W3C tracecontext、Baggage 与采样

链路：浏览器 → 网关 → 服务A → 服务B → DB/消息队列 → 服务C
每跳必须传递：trace_id（统一 ID）、parent_span_id（谁生了我）、
  sampling（采不采）；任一跳断掉 → 碎片化、查不到全链路

早期乱象：B3（Zipkin）、uber-trace-id（Jaeger）、Datadog 各自定义
  服务A 用 Jaeger、服务B 用 OTel → 头互相不认
W3C 解法：traceparent（统一 trace-id/span-id/flags）+
  tracestate（厂商扩展区）→ 一套标准头谁都能解析

traceparent = version-trace-id-parent-id-flags，用 "-" 分隔
示例：00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
  version 2位hex（"00"）；trace-id 32位hex（128 位全局唯一）
  parent-id 16位hex（当前 span id）；flags 2位hex（bit0=sampled）

trace-id 全 0 非法（128 位随机即可）；parent-id 全 0 非法，新 span 替换
flags bit0=sampled（01 记录、00 仅透传 ID）
校验：不合法（长度不对/全 0）→ 丢弃重建，绝不传播坏头

from opentelemetry import trace
from opentelemetry.propagators import extract

ctx = extract(carrier)  # carrier = headers 字典
span = tracer.start_span("handle_request",
    context=ctx, kind=trace.SpanKind.SERVER)

W3C tracecontext 是 OTel 默认传播器：无需配置即可注入/提取

tracestate 是 traceparent 的"扩展区"：厂商放采样决策/延迟预算，
  多个厂商用逗号分隔、键值用 "=" 连接
格式：vendor1=opaqueValue1,vendor2=opaqueValue2
示例：dd=t.ds:1234;t.s:1,congo=t61rcWkgMzE
约束：键/值各 1~256；值内不含 "=" "," ";"（需转义）

处理原则：陌生键一律原样透传（丢了就断某厂商的链）
只允许：追加自己的键、删除/编辑自己管理的键
风险：老实现把整个 tracestate 重写 → 破坏互操作

tracestate 可能被恶意塞满：限制解析长度、超限截断并告警
键值里不要放敏感数据（会随每条请求传播）

注入（出站）：发出前写 traceparent；提取（入站）：解析后
  生成新 span，parent = 上游 span
边界：只信受信上游；不传/坏头 → 生成新根 trace（不 panic）

gRPC 用 metadata 传递，OTel 拦截器自动注入/提取
注意：metadata 大小写不敏感、两端一致；
  streaming 场景上下文在首帧 metadata

消息队列最容易断链：跨进程不同时
传播：Kafka/RabbitMQ 消息头塞 traceparent，投递注入、消费提取
断链场景：中间件重发/重排丢头；消费者把 trace_id 存死内存
正确：消费者提取 → 作为该处理链的根上下文，保持父子链

Baggage 是随链路传递的业务键值对（user_id/tenant_id/campaign）
  存进 "baggage" 请求头，让下游拿到"这笔请求是谁"
格式：baggage: key1=value1;metadata1,key2=value2
示例：user_id=10086,tenant=shop-a,campaign=double11

用途：业务维度贯穿链路（日志/指标带 user_id/tenant 分组分析）；
  采样决策输入（尾部采样可按 VIP 用户必留）
获取：ctx 里 Baggage API 读/写，SDK 自动注入出站请求

红线一：不放敏感数据（随每个出站请求明文传播，
  token/密码进 baggage = 全网广播）
红线二：键数/长度设上限；红线三：公网进来的键值白名单校验
  别让攻击者塞 baggage 影响路由逻辑

头部采样（Head）：源头决定，flags bit0=sampled，
  后续服务 parentbased 跟随 → 一条 trace 要么全采要么全不采
尾部采样（Tail）：Collector 收齐后按错误/延迟/随机决定去留

processors:
  tail_sampling:
    decision_wait: 15s
    policies:
      - name: errors
        type: status_code
        status_code: { status_codes: [ERROR] }
      - name: slow
        type: latency
        latency: { threshold_ms: 800 }
      - name: random
        type: probabilistic
        probabilistic: { sampling_percentage: 20 }

要点：Head 决定 flag 保一致性（否则同 trace 采一半拼不完整）；
  Tail 按结局补关键；头部随机率别太低（留足候选）

一致性：父子采样决策必须一致 → parentbased
口诀：高流量 Head 10% 起 + Tail 保错误/慢；关键业务 Head 100%
监控采样偏差（采样率 vs 实际吞吐），防误配置采没

□ 统一用 W3C tracecontext 传播器
□ traceparent 严格校验（长度/全0/版本），非法即重建
□ tracestate 陌生键透传，只管理自己的键
□ HTTP/gRPC/metadata/消息头都注入提取，异步以消息头为根
□ Baggage 只传业务键值，禁 token/PII，设上限
□ 公网入口校验外部头，防伪造与膨胀
□ 采样 parentbased 保一致性，Head 降量 + Tail 保关键
□ 监控采样偏差与头长度，定期审计传播字段

上下文传播 = W3C 标准头逐跳传递 + Baggage 业务透传 +
一致性采样 + 安全校验，让每条 trace 从头到尾不断链。