OpenTelemetry 链路追踪接入：5 分钟打通日志、指标、链路

准备工作

接入前先确认两件事：OBSERVE 服务端已部署并拿到 OTLP 端点地址（默认 http://<host>:4318），以及应用能访问该端点。本文以 Java 应用为例，其他语言流程一致，只差 SDK 依赖。在 OBSERVE 控制台左侧"接入向导"里，选择语言后会自动生成一段配置和 endpoint 信息，直接复制即可。

OTLP 协议有两种：http/protobuf（4318 端口）和 grpc（4317 端口）。如果环境有防火墙或代理，优先用 http/protobuf，它是多数 SDK 的默认值，也方便用 curl 排查连通性。

引入依赖并配置

Java 应用通过 OpenTelemetry Java Agent 接入，不需要改业务代码。下载 opentelemetry-javaagent.jar 后，在启动命令加上：

java -javaagent:path/to/opentelemetry-javaagent.jar   -Dotel.service.name=order-service   -Dotel.traces.exporter=otlp   -Dotel.metrics.exporter=otlp   -Dotel.logs.exporter=otlp   -Dotel.exporter.otlp.endpoint=http://<host>:4318   -Dotel.exporter.otlp.protocol=http/protobuf   -jar app.jar

otel.service.name 是服务在链路里的名字，务必全局唯一，否则调用图会串。生产环境建议把这一堆参数写进启动脚本或容器环境变量，避免每次手工拼。Go、Python 应用则通过官方 SDK 手动埋点或使用自动埋点库，把 exporter 指向同一个 OTLP 端点即可。

验证链路是否生效

启动后先打几个请求，然后在 OBSERVE 的"链路追踪"页面看有没有 span。快速自查三件事：

• 服务列表里能看到 order-service；
• 点开任意一条 trace，能看到完整的调用链和每一跳耗时；
• 日志页面里，携带 trace_id 的日志能通过"跳转到链路"一键关联到对应 trace。

如果只有指标没有链路，多半是 exporter 配置没生效或端口不通，先用 curl -v http://<host>:4318/v1/traces 确认端口连通性，再看 agent 启动日志里有没有 OTLP 相关的报错。

关联日志与业务字段

链路上去了，下一步是把日志和链路串起来。Agent 会自动往日志里注入 trace_id 和 span_id，你只需要在日志框架里输出它们：

<pattern>%d %-5level [%X{trace_id:-}] [%X{span_id:-}] %msg%n</pattern>

同时把 user_id、order_id 这类业务字段作为 span attribute 传进去，排障时就能按"哪个用户、哪笔订单"直接过滤链路，不用逐条翻。跨服务调用时，确保上游把 traceparent 头透传给下游，否则链路会在服务边界断开。

采样策略

高并发场景别把采样率开到 100%。OBSERVE 支持按比例采样和按错误采样：日常 10% 采样，出错请求 100% 保留。这样既控制存储成本，又保证问题请求一定有完整链路可查。采样配置在服务端统一下发，客户端不用重复改；被采样掉的链路日志仍然入库，只有 span 数据被丢弃，兜底排查时仍可回到日志检索。