如何调试OpenTelemetry Java Agent扩展埋点？排查无指标输出

基础配置校验 #

• 核对Instrumentation注解：检查@Instrumentation的name、instrumentationName是否合规，@TypeInstrumentation的typeMatcher是否精准命中目标类（比如全限定类名有没有写错，Matcher类型是否用对，比如NamedTypeMatcher）。
• 检查扩展包结构：确认jar包内存在META-INF/services/io.opentelemetry.javaagent.extension.instrumentation.InstrumentationModule文件，且文件内容是你自定义InstrumentationModule的完整类名（别加多余空格或换行）。
• 开启Agent调试日志：启动时添加-Dotel.javaagent.debug=true参数，查看控制台日志里有没有扩展加载的相关信息——比如“Loaded instrumentation module xxx”说明加载成功，要是有报错信息直接定位问题。同时确认-Dotel.javaagent.extensions的路径是绝对路径，jar文件权限正常。

代码逻辑调试 #

• 替换标准输出为日志框架：别用System.out.println，换成SLF4J这类日志工具输出调试信息，Agent的类加载环境可能会拦截标准输出。配置日志级别为DEBUG，看关键代码段（比如方法拦截的onEnter、指标创建处）是否有日志打印。
• 验证指标创建流程：确保Meter实例是通过OpenTelemetry.get().getMeterProvider().get("你的埋点名称")正确获取的，指标类型（计数器/直方图等）配置无误，且确实调用了add或record方法写入数据。
• Dump处理后的类文件：添加-Dotel.javaagent.classes.dump.dir=/tmp/otel-classes参数，把Agent修改后的类文件导出到指定目录，打开目标类看是否插入了你的埋点代码——要是没修改，说明拦截规则没匹配上。

运行环境排查 #

• 对齐Agent版本：确保扩展代码依赖的OpenTelemetry API版本和实际使用的Agent版本完全一致（比如都是1.28.0），版本不兼容会直接导致扩展失效。
• 检查指标导出配置：确认otel.metrics.exporter设置了有效导出器（比如otlp、prometheus或logging），otel.metrics.export.interval配置合理（默认1分钟，可能需要等一会儿才出指标）；用logging导出器的话，直接看日志里有没有click指标。
• 核对方法拦截规则：如果是方法级埋点，检查@MethodInstrumentation的methodMatcher是否匹配目标方法的参数、修饰符、返回值——比如目标方法是public的，Matcher里有没有指定，方法名、参数类型是否完全对应。

内容的提问来源于stack exchange，提问作者David Tam