OpenTelemetry 链路追踪入门

用统一标准串联前端、网关、服务和数据库调用。

图：自动插桩覆盖协议调用，手工 Span 只补关键业务阶段；点击查看原图。

核心思路

先确定服务命名与资源属性，再接入自动埋点。为关键业务补充 span 属性与事件，但不要记录密码、令牌和完整个人信息。

落地步骤

采样策略要兼顾成本和问题捕获：正常流量低比例采样，错误与慢请求提高保留概率。通过 trace ID 关联日志能显著缩短定位时间。

验证清单

实施后不要只确认“能运行”，还应检查错误率、延迟、资源占用和异常路径。把验证命令、预期结果和回滚方式写进变更记录，后续维护会轻松很多。

小结

好的工程实践不是堆叠工具，而是用清晰边界、可观察结果和可逆变更降低长期成本。先解决最重要的问题，再逐步自动化。

可执行实践

统一 service.name、environment 和 version；自动埋点覆盖入口与常见客户端，关键业务再补手工 Span、事件和错误状态。

验证与退出条件

验证上下文能跨 HTTP、消息队列和异步任务传播。采样后仍应保留错误与慢请求，属性禁止记录令牌、密码和完整个人信息。

实践场景

以“为一次跨服务请求建立完整 Trace”为例。实施前先保存当前版本、配置和关键指标基线，写明成功条件与停止条件；涉及生产数据或外部写入时，先在隔离环境验证。

分步实施

入口创建根 Span 并传播标准上下文；数据库、消息和外部调用使用子 Span，记录状态码与版本但不记录敏感正文。每完成一步都记录可观察结果，不把命令返回零等同于业务正确。

故障演练

模拟异步消息、超时重试和上下文丢失，确认父子关系、错误状态与采样结果正确。演练应使用可清理的测试数据，并验证告警、日志和恢复路径，而不只是确认系统最终又能访问。

观测与回滚

观察 Trace 完整率、孤儿 Span 和导出丢弃数；采集成本异常时降低采样并回退新埋点。变更单中应写清负责人、观察窗口、阈值和回滚触发器，避免故障发生后再临时争论。

完成后把使用的版本、关键命令、观测窗口和结果写入变更记录。没有验证证据的“已完成”不能作为上线结论。

第二轮实践复核

可复用交付物： 语义约定、采样方案和 Trace 完整率报告。复用时先固定软件版本、依赖锁文件、测试数据规模和运行环境；文章中的命令包含占位符，必须替换成自己的非生产目标后再执行。

最低验证： 向测试 Collector 发送一条跨服务请求，按 trace_id 核对根 Span、子 Span 与状态

执行记录要保存命令、退出码、关键输出、观察窗口和回滚结果。若验证会产生写入，先使用隔离环境或 dry-run；任何失败都不能通过扩大权限、关闭校验或跳过测试来“解决”。

完整实战：追踪一次下单请求

从网关到订单、库存、支付服务，先统一资源属性（服务名、版本、部署环境），再定义少量稳定的业务 span。自动插桩负责 HTTP、数据库和消息中间件，手工 span 只补业务阶段，避免给每个函数都建 span。

POST /orders                         820 ms
├─ order.validate                     8 ms
├─ inventory.reserve                115 ms
├─ payment.authorize                640 ms  ERROR gateway_timeout
└─ order.release_reservation         31 ms

错误 span 应记录规范化状态和可诊断属性，但不能把卡号、令牌、完整 SQL 或请求正文塞进属性。user.id、order.id 等高基数字段是否记录，要经过数据治理；即使进入 Trace，也不要拿它们做无界指标标签。

上下文传播与采样

入口校验传播头，建立或继续 trace；不要盲目信任外部传入的任意 baggage。
异步消息把 trace context 放入消息属性，消费端建立 consumer span，而不是伪装成同步调用。
头部采样成本可控但看不到最终结果；尾部采样能保留慢请求和错误，但需要集中缓冲与容量预算。
无论采样策略如何，基于指标的错误率和延迟监控不能依赖 Trace 样本完整性。

验收项	注入方式	通过证据
跨服务传播	发起一笔测试订单	所有服务共享 trace_id，父子关系正确
超时	支付模拟延迟	deadline 传播，取消后无幽灵工作
异步消费	发布订单事件	producer/consumer 语义与链接清楚
脱敏	输入敏感字段	导出数据中不出现原文
出口故障	停止 collector	业务继续，遥测有界丢弃且告警

Collector 使用队列、批处理、内存限制和重试，出口故障不能反压到业务请求。上线先估算每秒 span 数、平均大小和保留成本，再灰度调采样。观察完整率、孤儿 span、导出失败、队列丢弃和 collector 内存；回滚时先降低采样与关闭新增属性，而不是删除全部可观测性。

一手资料

资料与版本边界复核日期：2026-08-22。工具行为可能演进，实施前以锁定版本对应的官方文档为准。