OpenTelemetry Java Agent 十分钟接入：日志、链路、指标一次上报

为什么用 Java Agent 而不是手写埋点

手写埋点意味着在每个方法里加 span 的 start/end、手动传递 context，侵入性强、容易漏，改起来还得重新发版。OpenTelemetry 的 Java Agent 通过字节码增强自动拦截主流框架（Spring MVC、HTTP 客户端、JDBC、消息队列等），不改一行业务代码就能拿到完整的链路和指标。

对想快速接入可观测平台的团队，Agent 是性价比最高的起点：先自动采集，发现关键路径后再对个别方法做手工埋点补充。判断标准很简单——能自动化的先自动化，把精力留给真正需要精细埋点的核心链路。

第一步：下载 Agent 并配置启动参数

从 OpenTelemetry 官方发布页下载 opentelemetry-javaagent.jar，放到应用服务器固定目录，然后在启动命令里加上 JVM 参数：

java -javaagent:/opt/otel/opentelemetry-javaagent.jar   -Dotel.service.name=order-service   -Dotel.exporter.otlp.endpoint=https://ob.example.com/otlp   -Dotel.exporter.otlp.headers=Authorization=Bearer <你的接入Token>   -Dotel.metrics.exporter=otlp   -Dotel.traces.sampler=parentbased_always_on   -jar app.jar

关键参数说明：service.name 是服务名；exporter.otlp.endpoint 是炬鲸 OBSERVE 的 OTLP 采集地址；metrics.exporter=otlp 同时开启指标上报。Token 走请求头传递，不用改代码。traces.sampler 这行可选，接入验证阶段建议全采样，确认无误后再换成按比例采样。

如果跑在容器里，把这几行放进 JAVA_TOOL_OPTIONS 环境变量即可，镜像不用重打，Agent 版本也和应用发布解耦，升级只需改环境变量再重启。

第二步：把日志和 Trace 关联起来

Agent 会自动往日志的 MDC 里注入 trace_id 和 span_id，你在 logback / log4j2 的 pattern 里把它们打出来：

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

这样每条日志都带 trace_id。在炬鲸 OBSERVE 里，日志详情页就能直接跳转到对应链路，链路里的每个 span 也能反查关联日志。这是排查慢调用和报错最省事的一步，务必配置——很多团队接入后说「链路是有了，但查问题还是慢」，十有八九是漏了这步。另外注意：如果日志是结构化 JSON，trace_id 要作为顶层字段输出，而不是埋在 message 文本里，否则平台没法把它当成一等字段索引。

第三步：验证与常见问题

启动应用后触发几次请求，回到控制台确认三件事：

1. 「链路追踪」里能看到 order-service 的调用链
2. 「日志检索」里日志带上了 trace_id
3. 「监控」里能看到 QPS、延迟、错误率指标

常见问题：

• 链路看不到：检查 endpoint 是否可达、Token 是否带对，注意 headers 里 Authorization 的格式是 Bearer <token>
• 日志没有 trace_id：确认 pattern 里写了 %X{trace_id}，且日志在 Agent 初始化之后输出
• 指标为空：确认 metrics.exporter=otlp，且采集地址支持 OTLP/HTTP 指标协议

跑通之后，把这几行启动参数沉淀成团队的标准模板，后续新服务照抄即可。