OpenTelemetry 埋点升级验收工作流

留下可复现的迁移样本

这个流程面向准备升级 OpenTelemetry 语义约定的服务负责人，不是把所有排障工具堆在一起的事故页面。先收集脱敏的旧日志、当前埋点或 Collector 配置、至少经过两个服务的代表性请求，以及源版本和目标版本。用 structured-log-analyzer 看清日志中实际存在的字段。若日志是 logfmt，再用 logfmt-to-json-structured-log-bridge 处理引号、类型转换和重复键；原本就是结构化 JSON 的样本无需多做一步。分享前先清除个人信息和密钥；完整的泄露风险检查属于 pii-log-redaction 工作流。

把可改名字段与设计变更分开

在代码、Collector 配置或仪表板 JSON 的副本上运行 otel-semantic-convention-migration-tool，记录源和目标版本、建议的重命名、被移除的属性及未映射的旧字段。工具给出的是迁移草稿，不会替你更新线上配置。比如 http.target 需要按语义考虑拆成路径和查询，不能只做字符串替换。由服务负责人审查这些分支，再走正常发布流水线。只看“改了多少字段”也不够，仪表板查询或 Collector 转换规则可能仍引用旧名。

用头部和实际导出共同证明连续性

把代表性的 W3C traceparent、tracestate、baggage 与 OTLP 导出头部交给 opentelemetry-w3c-traceparent-tracestate-baggage-and-otlp-protobuf-headers-propagation-validator，核对下游是否保留同一个 trace-id，同时换成新的非零 span-id。头部有效并不代表应用真的上报了 span，所以还应使用 distributed-trace-decoder-waterfall-visualizer 打开升级后的链路 JSON。比对预期服务、父子关系、错误 span 和耗时；缺失的服务要记录，不能凭头部推测它存在。

形成有门槛的发布结论

若发布要求包含延迟目标，再用 api-latency-budget-planner 将观察到的阶段耗时与事先约定的预算并列。单条 trace 只能提示时间花在哪儿，不能统计出可信的 P99。验收记录应包含样本版本、属性差异、头部校验、真实链路证据、仍未映射的字段和预算例外。若主要任务变成线上事故排查或 API 载荷重放，应分别转到 observability-debugging 或 api-request-replay-and-debugging。