聊到 Java 应用的监控很多团队第一反应是 Prometheus Grafana 这套组合再搭个 Micrometer 暴露指标或者用 Zipkin / SkyWalking 做链路追踪。这套方案本身没什么问题但落到实际运维和生产排障时你会发现一个很别扭的现状指标是一套体系链路是一套体系日志又是另一套体系。三个工具互相不通出了问题仍然要点进多个控制台来回比对Trace ID 和 Metric 对不上是家常便饭。这正是我最近在给团队推进 OpenTelemetry后文简称 OTel时最想解决的问题。这篇文章我就结合实际落地经验聊聊怎么用 OpenTelemetry 把 Java 应用的指标、链路、日志统一管起来包含 Agent 接入、SDK 手动埋点、Collector 部署、数据关联这几块最后附上我在生产环境踩过的坑和排查思路。这套监控方案目前在社区很主流对 Java 生态的支持也是最完整的无论你用的是 Spring Boot 单体还是 Dubbo / gRPC 微服务都能以较低成本接入。如果你正在做技术选型或者已经被“指标归指标、Trace 归 Trace”的现状折磨过这篇文章应该能给你一个完整的落地方案。1. 为什么我最终选定了 OpenTelemetry监控 Java 应用的思路拆解1.1 从埋点到可观测性Java 监控的演进逻辑Java 监控这件事从我接触过的项目看大致经历了三个阶段。最早期的监控就是看日志应用出问题了靠人工翻 log顶多在关键业务方法里自己打点计时非常原始。后来 Spring Boot Actuator 普及了配合 Micrometer 暴露 JVM 指标、Tomcat 线程池指标到 PrometheusGrafana 一画看板这个阶段基本解决了“系统健康状态可视化”的问题但只知道系统“怎么了”不知道“为什么会这样”跨服务调用一笔糊涂账。再后来微服务架构铺开SkyWalking、Zipkin、Jaeger 这些 APM 工具开始流行链路追踪成了标配。这时候问题来了工具越来越多数据孤岛越来越严重。Micrometer 只管 metricsSkyWalking 只管 traces日志系统又是独立一套。当线上出现一个请求变慢你得先查 APM 找到慢的节点再切到日志平台搜 Trace ID还得回 Prometheus 看那个时间点的 CPU / 内存曲线——排障效率全消耗在上下文切换上了。OpenTelemetry 的核心思路就是把这三种数据统一到一套 API、一套 SDK、一套协议下。它在 CNCF 里的定位是“可观测性领域的标准化基础设施”所有语言、所有框架、所有后端Prometheus、Jaeger、Zipkin、云厂商 APM 都能对接都往这个标准上靠。对于 Java 应用来说OTel 既能做自动埋点又能做手动埋点能把 traces 和 metrics 关联起来还能通过 Trace ID 把日志串进去这才是真正意义上的“可观测性”而不只是“监控”。1.2 OTel 的数据模型和 Java 应用接入的核心价值OTel 的数据模型说起来不复杂就三大类Trace链路、Metric指标、Log日志。但它的设计巧妙之处在于通过一个统一的 Resource 概念来标记数据来源。Resource 里包含服务名、服务实例 ID、版本、部署环境等元信息三类数据都挂在这套元信息下这样在后端做关联查询就有据可依。接入 Java 应用时OTel 提供了两种方式价值取向完全不同。第一种是Java Agent 自动注入也就是 javaagent 方式通过字节码增强技术在类加载时改写字节码把埋点逻辑织入到 HTTP 框架、数据库客户端、消息队列客户端这些常用组件中。你基本不用改业务代码配置好 Agent 启动参数就能自动拿到 HTTP 请求的链路、JDBC 调用的耗时、Redis 操作等数据。第二种是OpenTelemetry SDK 手动埋点需要在代码里显式创建 Tracer / Meter适合对业务自定义指标、关键业务逻辑耗时做精细化埋点。我在实际项目里是把两种方式混着用的Agent 兜底全覆盖SDK 用于关键链路补充。这个组合比较符合 Java 后端团队的实际情况——既想要快速落地又不想彻底牺牲自定义能力。2. Java 应用接入 OpenTelemetry 的完整配置2.1 5分钟快速接入Java Agent 方式的配置细节Java Agent 方式最大的优势就是“快”。从官方 GitHub 下载opentelemetry-javaagent.jar当前稳定版本对应 OTel SDK 1.x 主线然后在 JVM 启动参数里加一行java -javaagent:/path/to/opentelemetry-javaagent.jar \ -DOTEL_SERVICE_NAMEorder-service \ -DOTEL_EXPORTER_OTLP_ENDPOINThttp://otel-collector:4317 \ -jar myapp.jar这里有几个参数值得单独解释一下。OTEL_SERVICE_NAME是服务名所有 Metrics、Traces、Logs 都会以这个维度聚合必须全局唯一不然后端查数据全糊在一起。OTEL_EXPORTER_OTLP_ENDPOINT是 OTLP 协议的接收端地址4317 是 gRPC 端口如果 Collector 配的是 HTTP 接收器就用 4318。默认情况下 Agent 会捕获很多框架的埋点但为了控制数据量我在生产环境通常会关掉部分不需要的埋点-DOTEL_INSTRUMENTATION_MONGODB_ENABLEDfalse -DOTEL_INSTRUMENTATION_APACHE_HTTP_ASYNC_CLIENT_ENABLEDfalseAgent 方式在 Spring Boot 项目上表现特别稳因为它自动支持 Spring Web MVC、Spring WebFlux、RestTemplate、WebClient、JDBC、HikariCP 等常用组件基本开箱即用。不过有一个容易忽略的问题Agent 需要和 JDK 版本匹配JDK 8 有些低版本 Agent 可能不支持 TLS 1.3 相关特性踩坑后我建议始终使用最新稳定版。2.2 SDK 手动埋点自定义业务指标和链路的正确姿势Agent 适合通用接入但业务侧的定制需求还是得靠 SDK。比如我要监控“用户下单耗时”和“订单创建失败次数”这些业务语义 Agent 是感知不到的就需要手动埋点。使用 SDK 前先在 Maven 里引入依赖dependency groupIdio.opentelemetry/groupId artifactIdopentelemetry-api/artifactId version1.40.0/version /dependency dependency groupIdio.opentelemetry.instrumentation/groupId artifactIdopentelemetry-instrumentation-annotations/artifactId version1.40.0/version /dependency如果是 Spring Boot 项目官方提供了 Spring Boot Starter用起来更顺手。我项目里封了一个简单的组件类通过WithSpan注解给关键方法自动生成 SpanService public class OrderService { private static final Tracer tracer GlobalOpenTelemetry.getTracer(order-service); WithSpan(create-order) public Order createOrder(OrderRequest request) { Span span Span.current(); span.setAttribute(user.id, request.getUserId()); span.setAttribute(order.amount, request.getAmount()); // 业务逻辑... return order; } }对于业务指标用 Meter 来记录Meter meter GlobalOpenTelemetry.getMeter(order-service); LongCounter orderFailureCounter meter.counterBuilder(order.create.failures) .setDescription(订单创建失败次数) .setUnit(1) .build(); // 业务异常时 orderFailureCounter.add(1, Attributes.builder() .put(error.type, STOCK_NOT_ENOUGH) .build());这套代码在不同服务间复制粘贴成本很低我习惯把全局 Tracer / Meter 的初始化抽到一个公共模块各服务直接依赖然后通过配置otel.traces.exporter和otel.metrics.exporter决定是否启用。手动埋点另一个关键点是要保证 Span 上下文能跨线程传递后面细说。3. 指标、链路与日志三类数据在 Java 场景下的采集细节3.1 指标采集JVM 监控和自定义指标导出到 PrometheusJava 应用的指标监控里JVM 指标是基础中的基础。这部分 OTel Java Agent 内置了jvm埋点包括堆内存使用量、GC 次数和耗时、活跃线程数、类加载数量等。Agent 默认使用 OTLP 协议导出如果后端已经有 Prometheus需要在 Collector 里把 OTLP 转成 Prometheus Remote Write或者让 Agent 直接暴露/metrics端点用 Prometheus 抓取。直接暴露 Prometheus 协议的配置是-DOTEL_METRICS_EXPORTERprometheus -DOTEL_EXPORTER_PROMETHEUS_PORT9464启动后 Prometheus 直接抓http://app-host:9464/metrics即可。这里有一个值得注意的点OTel 的指标模型和 Prometheus 不完全一致OTel 使用Resource和Scope两层标签转成 Prometheus 时会拼接成target_info这种元信息指标刚开始用 Grafana 查数据时容易找不到原来的服务名标签需要习惯一下。自定义指标方面如果团队已经从 Micrometer 迁移过来我的建议是逐步替换。Micrometer 的 MeterRegistry 和 OTel 的 Meter 本质上都是做计量聚合但 OTel 的 API 更统一还能把业务指标和 Trace 关联起来。3.2 链路追踪跨服务传递和异步线程的上下文传播链路追踪要真正跑通有一个前提是上下文必须正确传递。OTel 遵循 W3C TraceContext 标准HTTP 请求在客户端注入traceparent请求头服务端解析该头并恢复上下文。这个能力对 RestTemplate、WebClient、Apache HttpClient 都是自动的所以同步调用场景基本无感。麻烦的是异步场景。Java 并发编程里线程池极其普遍而上下文默认是存在 ThreadLocal 里的线程一变上下文就丢了。我之前排查过一个线上问题用Async线程池执行了后续的库存扣减逻辑结果那个子线程里trace_id是空的链路直接从异步边界断开。解决方案是在提交任务时做上下文注入推荐使用Context.taskWrapping()ExecutorService executor Executors.newFixedThreadPool(8); Context context Context.current(); executor.submit(context.wrap(() - { // 异步任务逻辑 inventoryService.deduct(); }));Instrumentation 库也提供了Executors相关的自动埋点比如io.opentelemetry.instrumentation:opentelemetry-instrumentation-annotations配合WithSpan可以处理部分场景但最保险的还是手动 wrap。还有一个开箱即用的技巧使用 Spring Boot 的TaskDecorator统一包装线程池Bean public Executor asyncExecutor() { ThreadPoolTaskExecutor executor new ThreadPoolTaskExecutor(); executor.setTaskDecorator(runnable - { Context context Context.current(); return () - context.makeCurrent().run(runnable); }); return executor; }这样所有Async线程池的任务都能自动携带前一个线程的 TraceContext排查异步链路断链问题会省大量时间。3.3 日志与 Trace 关联MDC 自动注入的实践日志和链路关联起来才能在一次请求出错时直接用 Trace ID 过滤出所有相关日志。实现的思路是把当前 Span 的 Trace ID 和 Span ID 注入到日志框架的 MDC 中然后在日志 pattern 里输出这两个字段。使用 OTel Java Agent 时这个功能是自动的。Agent 会自动在 SLF4J 的 MDC 里设置trace_id和span_id两个键。对应的 logback pattern 可以这样配置pattern%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{36} - [%X{trace_id},%X{span_id}] - %msg%n/pattern如果是手动接入 SDK没有用 Agent就需要自己写一个SpanProcessor或者用MDCScopeDecorator。我建议小团队如果不想折腾直接用 Agent 是最省事的因为它内置了日志关联不需要在代码里做任何处理。有了日志关联之后再配合 OTel Collector 的日志接收能力可以把 Java 应用直接通过 OTLP 协议把日志发给 Collector三条数据同一套传输链路全部打通。这个能力在生产上非常实用排查问题时在 Grafana 里点一下 Trace就能看到关联日志。4. 搭建一套可用的监控后端从 OTLP Collector 到 Grafana4.1 后端选型OTLP Collector 是数据流转的中枢如果你只是小规模测试可以直接把 Agent 的 OTLP 数据发给 Jaeger 或 Tempo。但生产环境我强烈建议在应用和后端之间引入OpenTelemetry Collector。它的作用和 Kafka 在消息队列中的地位类似——是个数据管道负责接收、处理、导出遥测数据好处是解耦。应用不需要关心后端是 Prometheus 还是 Jaeger只要往 Collector 发 OTLP 就行。Collector 可以通过 processor 做批处理、过滤、采样、属性修改再按需导出到多个后端。这样即使以后监控后端替换了应用配置完全不用改。一个最小可用的 Collector 配置如下otel-collector-config.yamlreceivers: otlp: protocols: grpc: endpoint: 0.0.0.0:4317 http: endpoint: 0.0.0.0:4318 processors: batch: timeout: 5s send_batch_size: 1024 exporters: debug: verbosity: normal otlp/prometheus: endpoint: prometheus:9090 tls: insecure: true otlp/tempo: endpoint: tempo:4317 tls: insecure: true service: pipelines: traces: receivers: [otlp] processors: [batch] exporters: [debug, otlp/tempo] metrics: receivers: [otlp] processors: [batch] exporters: [debug, otlp/prometheus]这个配置做了三件事通过 OTLP 协议接收应用数据使用 Batch processor 提高导出效率将 Trace 发给 Tempo将 Metric 转发给 Prometheus。Collector 部署方式我习惯用 Docker Compose应用通过内网 DNS 访问otel-collector:4317。4.2 可视化方案Grafana 和 Tempo 的组合拳指标和链路后端选型上我的推荐是Prometheus Grafana Tempo或 Jaeger。Prometheus 负责指标存储和告警Tempo 负责 Trace 存储Grafana 负责统一界面展示。Tempo 的优势在于它兼容 OTLP且能直接对接 Grafana 的 Trace 视图点一条 Trace 能看到完整瀑布图。Grafana 配置数据源时Prometheus 和 Tempo 都要加上。更关键的一步是在 Grafana 里配置“Trace 到日志”的联动点击一个 Span可以直接跳转到 Loki 里对应 Trace ID 的日志或者跳转到 Tempo 详情页。这个联动的基础就是前面提到的日志 MDC 注入没有这步联动了也查不到数据。看板模板方面社区已经有现成的 JVM 监控看板可以导入。我用了grafana.com/dashboards/12444之类的 JVM 看板但让它正常工作有个前提指标名必须符合那个看板使用的命名规则。OTel 的 JVM 指标名是jvm.memory.used、jvm.gc.pause这种带点的格式和 Micrometer 暴露的jvm_memory_used_bytes下划线格式不同导入模板后需要手动调整 PromQL改起来不麻烦但要知道这个差异。5. 常见问题与排查技巧实录5.1 Agent 注入失败和类冲突Java Agent 注入失败的表现是应用启动时报ClassNotFoundException或NoSuchMethodError或者干脆没有任何监控数据。最常见的原因有两个一是 Agent 版本和 JDK 版本不兼容JDK 8 升级到了高版本或反过来低版本 Agent 支持不了新 JDK 的内部 API二是应用本身用了大量字节码增强框架比如 SkyWalking Agent 同时存在多个 Agent 叠加导致类转换异常。我的排查步骤是先用-Dotel.javaagent.debugtrue启动看 Agent 初始化日志是不是正常加载了 instrumentation再确认有没有同时挂了多个 Agent生产环境不要多个 Agent 混用。另外 Spring Boot Fat Jar 场景下有些依赖会 shade 掉io.opentelemetry包导致类冲突排查方法就是看启动日志里的 ClassLoader 加载了哪个 Jar。5.2 Export 到后端的数据丢失数据丢失包含两种情况一种是应用侧日志显示有 Span / Metric 产生但没有导出另一种是 Collector 收到了但后端没查到。应用侧排查时先看 Agent 日志里 exporter 是否报错最常见是 OTLP 连接失败、超时或认证失败。我配置了 debug exporter 后先在本地把端到端跑通再上生产。Collector 侧数据丢失大概率出在 batch processor 和内存限制上。如果并发量大batch 尚未刷出且进程 OOM数据就丢了。建议把send_batch_size和timeout调大一点服务端和 Collector 之间如果是公网需要确认网络是稳定的。Prometheus 端查不到指标另一个原因是标签基数过高被 Prometheus 的storage.tsdb.retention或其他限制丢弃。OTel 的指标如果带过多唯一标签比如 URL 全路径Prometheus 采集压力巨大。建议在 Collector 里做memory_limiter和标签过滤把明显高基数的属性删掉。5.3 上下文传递中的线程池和异步问题这是 Java 开发者最容易踩的坑我也是排查了很久才总结出发病规律。症状很典型A 服务调 B 服务B 服务响应正常但 A 服务链路上 B 的 Span 是断开的B 服务日志里有 trace_id 但 A 服务日志没有。原因基本可以锁定在异步边界HTTP 请求进入 A 服务后如果 A 用线程池执行了 Feign / RestTemplate 调用而提交任务时没有把当前 Context 传进去下游就接收不到 traceparent。前面给出过的TaskDecorator方案是最通用的一招。还有一个隐蔽场景是 Kafka Consumer 消费消息时如果手动提交了偏移量又起了子线程处理子线程也要做 Context 包装。排查是否真的断了可以在入口 Filter 里打印 trace_id在业务代码里再打印 trace_id两处对不上就是边界断了。定位到具体类后再针对性修复而不是盲目全链路加拦截器。5.4 常见问题速查表问题现象可能原因解决思路启动报类冲突或 NoSuchMethodErrorAgent 与其他字节码增强工具冲突只用一套 Agent检查依赖版本链路数据为空但服务启动正常OTLP 地址配置错误或防火墙拦截 4317 端口检查 endpoint 连调改用 debug exporter 验证指标数据缺失部分服务服务名重复导致数据覆盖OTEL_SERVICE_NAME全局唯一异步线程 Trace 断开ThreadLocal 上下文未跨线程传递使用 TaskDecorator 或 Context.wrap日志中无 trace_id未启用 Agent 的日志关联MDC 键未配置检查 logback pattern 里的%X{trace_id}Trace 能查到但 Grafana 不显示指标命名格式不匹配按 OTel 指标命名调整看板 PromQLCollector 内存飙高高基数标签、批量过大配置 memory_limiter过滤高基数属性无法从 Trace 跳转日志Tempo / Loki 数据源未配置联动在 Grafana 配置 trace to logs 关联6. 一些实战经验总结在服务数量和调用链路还不算太复杂的阶段用 OTel 这套方案替换掉以前的“多套系统各管一摊”模式我觉得是值得的。它最大的价值不在于某一个指标采集得多精确而在于数据模型统一之后排障链条是完整的——有一个 Trace ID就能把一次请求经过的所有服务、每个服务的指标变化、所有相关日志串起来这种体验用传统的监控组合拳很难达到。从我个人的实践看落地 OTel 最需要注意的不是技术本身而是节奏。第一次接入不要追求把所有数据一网打尽先把 Java Agent 的默认埋点接好把 traces 和 logs 关联跑通让团队在日常排障中真实地用到 Trace ID 这个入口再逐步加自定义业务指标再上采样策略和告警。如果一开始就把所有框架埋点全部打开、所有自定义指标全加上数据量会非常可观Collector 和存储端的压力都会上来反而容易把项目做黄。另外一个很实用的建议把 opentelemetry-javaagent 的版本升级纳入常规依赖升级节奏。社区迭代速度很快新版本不只是修 bug还会适配新框架、新 JDK 版本长时间不升级容易在中间碰上一堆兼容性问题。升的时候先在一个低流量服务上验证确认 JVM 和框架兼容没问题再铺开。最后再分享一个小技巧。排查 Java 应用监控问题时尽量自己在本地把整套链路跑一遍再上生产代码里起一个最小的 Spring Boot 应用配上 Agent 和 Collector本地用 Docker 把 Prometheus、Tempo、Grafana 拉起来链路通了再放生产。这套东西本地验证的成本很低但能帮你避开绝大多数配置层面的低级错误省下的时间远超投入。