五分钟接入 OpenTelemetry：从埋点到链路追踪

OpenTelemetry（OTel）已经成为链路追踪的事实标准，各家厂商 SDK 的兼容层都收敛到它。用 OTel 埋点意味着代码不绑定任何一家后端，换供应商时只改 Exporter 配置，业务代码一行不动。炬鲸 OBSERVE 原生兼容 OTLP 协议，接进来几乎零改动。

安装 SDK 并埋点

以 Java 为例，引入依赖：

<dependency>
  <groupId>io.opentelemetry</groupId>
  <artifactId>opentelemetry-api</artifactId>
  <version>1.40.0</version>
</dependency>

Go 项目则用：

go get go.opentelemetry.io/otel

最省事的做法是自动埋点 Agent。Java 挂一个 JVM 参数即可覆盖 HTTP、数据库、消息队列等主流框架，无需改代码：

java -javaagent:opentelemetry-javaagent.jar -jar app.jar

需要更细粒度时，再在关键业务方法里手动 startSpan，并给 span 挂上订单号、用户 ID 等属性。

配置 Exporter 指向 OBSERVE

Agent 模式下通过环境变量配置：

export OTEL_EXPORTER_OTLP_ENDPOINT=https://ob.jjhub.cn/otlp
export OTEL_SERVICE_NAME=order-service
export OTEL_TRACES_SAMPLER=parentbased_traceidratio
export OTEL_TRACES_SAMPLER_ARG=0.1

其中 OTEL_SERVICE_NAME 是服务名，会作为链路归属的依据；采样比例先设 0.1，等流量稳定后再调。配置完成后启动服务，用 curl 打几个请求，回到 OBSERVE 的"链路追踪"页面就能看到完整调用链。

采样策略与常见坑

• 采样率：生产流量大时全量采样既贵又慢，1%～10% 通常足够发现问题；关键接口可以单独提升采样率。
• Span 命名：默认 span 名是 HTTP GET /user/12345，路径里的 ID 会爆炸式分裂基数，记得归一化成 /user/{id} 这类模板。
• 跨服务传 trace_id：确保网关和中间件透传 traceparent 头，否则链路在网关处就断了。
• 日志关联：把 trace_id 写进日志，排查时日志和链路能互相跳转。

验证第一条链路

服务起来后打几个请求，打开链路详情页核对三件事：该有的每一跳（网关、服务、数据库）都在、耗时加起来大致合理、服务名符合预期。少了某一跳，十有八九是代理或中间件把 traceparent 头丢掉了，先查透传再查采样。