用 OpenTelemetry 接入链路追踪：三步打通一张完整调用图

为什么用 OpenTelemetry

OpenTelemetry（OTel）是 CNCF 托管的可观测数据标准，一套 SDK 同时产出 trace、metric、log。选它最大的好处是数据格式和采集方式标准化：将来换后端不用改业务代码，只换 exporter 配置。OBSERVE 原生支持 OTLP 协议，接入就是配一个 endpoint 的事。

三步接入

以 Java 服务为例。

第一步，引入 SDK 和自动埋点 agent。在 pom.xml 里加 opentelemetry-api、opentelemetry-sdk，启动时挂 javaagent：

java -javaagent:opentelemetry-javaagent.jar \
  -Dotel.exporter.otlp.endpoint=https://ob.jjhub.cn/otlp \
  -Dotel.service.name=order-service \
  -Dotel.traces.exporter=otlp \
  -jar app.jar

第二步，配置 exporter。把 endpoint 指到 OBSERVE 的 OTLP 接收地址，设置 service.name。这个值是链路里区分服务的唯一标识，团队要先定命名规范，比如 {部门}-{系统}-{模块}，别让每个人各起一套。

第三步，验证数据。发起一次真实请求，到 OBSERVE 的链路页面按服务名搜索，能看到完整的 span 层级就说明通了。看不到就先查 agent 日志里的 otel 报错，十有八九是 endpoint 或鉴权配置问题。

三个容易踩的坑

• 采样率：默认采样可能漏掉低频错误。生产建议 otel.traces.sampler=parentbased_traceidratio，比例按流量调，别全采也别默认全丢。关键接口可以单独配 always_on。
• resource 属性：deployment.environment、service.version 要在启动时统一注入，方便按环境、按版本过滤和回滚排查。这些属性一旦上线就很难补齐。
• 传播丢失：跨服务要在入口透传 traceparent 头，异步线程和消息队列里要手动传递 context，否则链路会断成几截，看着像「丢了」。

落地建议

先从一个核心服务试点，把 trace 和现有日志用 trace_id 打通，再逐步铺开。告警里带上 trace 链接，收到告警点一下就能跳到对应 span，排障时间能从半小时压到几分钟。埋点策略上，优先用自动埋点覆盖框架调用，只有业务关键路径再手写 span，别一开始就追求全手工埋点。