用 OpenTelemetry 把 Java 服务接入 OBSERVE：从埋点到排障

前置条件

需要 Java 8 及以上（推荐 11/17）、一个正在运行的 Java 服务，以及 OBSERVE 的接入地址和 token。本文以 Spring Boot 为例，其他 Java 框架流程一致。先到 OBSERVE 控制台的「接入向导」里创建一个 Java 应用，记下 endpoint 和 token。

接入 Agent（零代码）

OpenTelemetry 提供了 Java Agent，通过 -javaagent 参数注入，不需要改任何业务代码。下载 agent jar 后，在启动命令里加上：

java -javaagent:/opt/otel/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://ob.jjhub.cn:4317   -Dotel.exporter.otlp.headers=Authorization=Bearer <token>   -jar order-service.jar

如果服务跑在 Docker 里，把 agent 打进镜像或挂载进去，再通过环境变量传参即可。Agent 会自动捕获 HTTP、数据库、消息队列等常见组件的调用，生成 trace 和 span，无需手动埋点。

打通日志与链路

单独有 trace 还不够，排障时最关键的是「从一条 trace 跳到对应的日志」。做法是让日志带上 trace_id 和 span_id。Spring Boot 用 Logback 时，在 logback-spring.xml 的 pattern 里加上 MDC 字段：

<pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{36}
  [trace_id=%X{trace_id},span_id=%X{span_id}] - %msg%n</pattern>

Agent 会自动把 trace_id、span_id 写入 MDC，日志打印时就能带上。日志用 OTLP 或文件采集上报到 OBSERVE 后，控制台里点开一个 trace，右侧即可看到关联日志。

常见问题排查

trace 看不到：先确认 exporter 是 otlp、endpoint 端口写对了（4317 是 gRPC，4318 是 HTTP，Agent 默认走 gRPC），再看服务是否有出网访问权限。

日志没有 trace_id：检查 pattern 里 MDC 字段是否加了，以及日志是否经过 agent 的日志桥接。老项目用 log4j1 的话需要额外配置。

采样率：高流量服务建议设置 -Dotel.traces.sampler=parentbased_traceidratio 配合 -Dotel.traces.sampler.arg=0.1，保留 10% 采样控制成本；排查具体问题时再临时调高。

接入完成后，打开 OBSERVE 的「应用拓扑」能看到服务间调用关系；点进任意一条链路，trace、metric、log 三者已经串在一起。