凡是搞过 OpenTelemetry Java Instrumentation 本地编译调试的人，多半都体会过那种“环境搞半天，代码没写几行”的憋屈感。这个项目本身就是一套非常庞大的 Gradle 多模块工程，里面塞着 SDK、Agent 壳、上百个埋点模块、ByteBuddy 字节码增强逻辑，再加上对 JDK 工具链版本的苛刻要求，第一次上手的人很容易在编译阶段就被劝退。我最初接手这个项目时，光是把环境跑通、让本地 Java Agent 能成功 attach 到测试应用上，就折腾了整整两天，踩过的坑密密麻麻。这篇就专门聊聊 OpenTelemetry Java Instrumentation 在本地编译调试开发中会遇到哪些坑，以及我实测下来最顺滑的绕坑姿势，希望能帮你把入门成本压缩到半天以内。
这篇文章不是官方文档翻译，而是一份从实际项目里摸爬滚打出来的经验手册。内容会覆盖编译环境准备、Gradle 构建配置、本地 Agent 调试、常见异常排查，以及自定义埋点模块的开发套路。适合三种人：一是想在 OpenTelemetry Java Agent 基础上做二次开发的，二是研究 Java Agent 字节码增强原理的，三是被公司 APM 私有化需求逼着要改埋点逻辑的。基础要求就一条：懂 Java、用过 Gradle，知道什么叫 Spring Boot 就够了，更深的东西我会一步一步拆开讲。
1. 编译环境准备：JDK 版本是第一道大坎
1.1 别用太新的 JDK，也不要想着“我本机肯定行”
我见过的绝大多数编译失败，根源都出在 JDK 版本不匹配上。OpenTelemetry Java Instrumentation 的较新版本已经要求使用 JDK 17 或以上来进行编译，而它生成的 Agent 产物又要兼容运行在 Java 8 及以上的目标应用上。这个“编译用高版本、运行兼容低版本”的特性，让很多人误以为随便装个最新版 JDK 就能搞，结果 Gradle 同步直接报出各种Unsupported class file major version或者 Kotlin DSL 相关错误。
实际编译中我推荐直接用 JDK 17，版本号卡在 17.0.x 的官方发行版即可，比如 Temurin。不要用 JDK 21 和 JDK 23 做主力编译环境，至少在写这篇文章时，我在 JDK 21 上遇到过 gradle daemon 进程行为异常的问题，而在 JDK 17 上所有模块都能顺利编译。如果你本机装了多个 JDK，请务必确认JAVA_HOME环境变量指对了版本，因为 Gradle Wrapper 会优先读取它。最好在 shell 里先跑一句：
echo $JAVA_HOME java -version确认这两条输出一致，再开始执行任何编译命令。我调试时经常遇到命令行下java -version显示 17，但编译器里 Gradle 却用了另一个 JDK 的情况，这种混乱通常源于 IDE 自身配置的 JDK 和终端环境变量不一致，务必两处都检查一遍。
1.2 Gradle Wrapper 与国内镜像加速
项目自带 Gradle Wrapper，所以理论上不需要本地安装 Gradle。但你千万别高估默认网络环境拉取依赖的速度，第一次执行任何 Gradle 任务时，它要下载的依赖少说也有几百 MB，而且很多是从 Maven Central 和 Gradle Plugin Portal 拉的。没有任何加速手段的话，你大概率会在下载依赖阶段就耗尽耐心。
我在本地配置里做了两件事加速。第一件事是在项目的~/.gradle/init.gradle里添加阿里云镜像仓库，让 Maven 依赖、插件依赖都走国内源：
allprojects { repositories { maven { url 'https://maven.aliyun.com/repository/public' } maven { url 'https://maven.aliyun.com/repository/gradle-plugin' } mavenCentral() } buildscript { repositories { maven { url 'https://maven.aliyun.com/repository/public' } maven { url 'https://maven.aliyun.com/repository/gradle-plugin' } mavenCentral() } } }第二件事是给 Gradle 开启缓存和并行编译。项目的根目录下有个gradle.properties文件，我一般会把 JVM 参数调大一点，同时关闭严格校验，避免下载依赖时被签名校验卡住。
org.gradle.jvmargs=-Xmx4g -XX:MaxMetaspaceSize=1g org.gradle.parallel=true org.gradle.daemon=true顺手说一句，org.gradle.jvmargs这个参数非常关键。OpenTelemetry Java Instrumentation 的子模块数量非常多，Gradle 在解析整个工程图时吃内存相当猛，如果只给默认的 512M 堆，编译中期大概率会直接OutOfMemoryError。我踩过一次这个坑后直接把内存提到了 4G，再也没有因为编译内存问题卡过。
2. 核心构建流程：理解多模块结构与编译产物
2.1 先搞懂 javaagent、instrumentation、sdk 这三个概念
本地编译调试这件事之所以困扰新手，很大程度上是因为项目结构太绕。你可以把 OpenTelemetry Java Instrumentation 这个仓库理解成三层的“乐高积木”：
sdk层是 OpenTelemetry 的 SDK 实现，负责 trace、metric、log 的数据模型和导出链路。instrumentation层是各种库的埋点适配器，比如针对 Spring Web MVC、Tomcat、Jedis、Kafka 客户端等分别写一套“拦截逻辑”。javaagent层则把所有 instrumentation 模块和 SDK 打成一个大 jar，通过 Java Agent 的premain机制，在应用启动时用 ByteBuddy 改写目标字节码。
如果做一个不太严谨的类比：SDK 就像是汽车发动机，instrumentation 是各种型号的油管转接头，javaagent 是整台已经装好的整车。你本地编译出来的那个带-all.jar后缀的产物，就是这台整车，可以直接挂到任何 Java 8+ 应用上开跑。
理解这个结构对你的日常开发非常重要。因为当你只想调试 Spring 的埋点时，完全没必要每次都打整车包，你可以只编译对应的 instrumentation 子模块，在它的单元测试框架里快速验证埋点逻辑是否正确。这一条能让你的迭代速度提升好几倍。
2.2 常用编译命令：整包构建、子模块构建、跳过测试
我第一次编译整包时执行的命令是：
./gradlew :javaagent:shadowJar这条命令会触发整个项目的依赖解析，然后把你所有的 instrumentation 模块全部收集起来，通过 Gradle Shadow 插件打出 fat jar。最终产物位于：
javaagent/build/libs/opentelemetry-javaagent-<版本号>-all.jar不过我建议在本地开发阶段不要一上来就编译整包，因为全量编译涉及上百个子模块的 build 和测试，耗时随随便便超过十几分钟。更高效的做法是只针对你要改的模块跑测试。举个例子，如果我在改instrumentation/spring模块下的代码，我会这样执行：
./gradlew :instrumentation:spring:test这个命令只跑单个模块的测试，速度极快。测试框架里已经内置了一个轻量级的 Java Agent 加载机制，可以直接验证新增埋点是否生效。
只有当单模块测试通过、需要真实验证完整 Agent 行为时，我才会跑:javaagent:shadowJar去打包。打包时如果不想跑那些集成测试（比如涉及 Docker 容器的测试），可以在命令后面加上-x test跳过，节省时间：
./gradlew :javaagent:shadowJar -x test2.3 验证产物是否正确加载
打完包以后别急着丢进目标应用里。我习惯先用java -jar或java -javaagent跑一个最简单的空应用来验证 Agent 能正常启动。比如：
java -javaagent:/path/to/opentelemetry-javaagent-all.jar -Dotel.javaagent.debug=true -cp /path/to/empty-test-app.jar com.example.EmptyApp正常启动时，控制台会出现一堆 Agent 初始化的调试日志，比如加载了哪些 instrumentation 模块、ByteBuddy 成功安装等等。如果看到Agent is ready之类的输出，说明产物基本可用；如果直接抛异常，那就是后面要排查的问题了。
3. 本地调试的实际操作：从“看着不生效”到“拿到第一个 Span”
3.1 调试方式一：使用 InstrumentationTestRunner 单元测试框架
项目里有个testing-common模块，里面提供了现成的测试基类，比如InstrumentationTestRunner。它的套路是：测试类里写普通 JUnit 方法，测试框架会自动加载对应的 Agent 字节码增强逻辑，再执行你写的业务方法，最后从内存中的 SpanExporter 取出生成的 Span 做断言。
我第一次看到这个机制时觉得非常酷，因为它真正做到了“在单元测试里调试字节码增强”。你不需要启动一个完整应用，也不需要关心 Agent 怎么 attach，只需要像写普通单测一样写代码。举个例子，测试 Spring Web 埋点的大致长这样：
@ExtendWith(InstrumentationExtension.class) class SpringWebMvcTest { @Test void shouldCreateSpanForController(InstrumentationExtension testing) { // 这里写一个简单的 MVC 调用 // 然后通过 testing.spans() 拿到生成的 Span } }用这个框架调试的核心理念是：先把链路逻辑在单测里调通，再上真机验证。我个人的实践顺序永远是“单测优先”，除非遇到了 classloader 加载这一类单测模拟不了的问题，才考虑用真实应用去 attach。
3.2 调试方式二：用本地 Spring Boot 应用验证 Agent
这个方式比较贴近真实场景，也是最容易出“看起来没生效”的坑的地方。我的做法是准备一个极简的 Spring Boot Web 工程，然后启动命令里加上 Agent 参数：
java -javaagent:/path/to/opentelemetry-javaagent-all.jar \ -Dotel.javaagent.debug=true \ -Dotel.traces.exporter=logging \ -Dotel.metrics.exporter=none \ -Dotel.logs.exporter=none \ -jar my-spring-boot-app.jar解释一下几个参数的作用。-Dotel.javaagent.debug=true会开启 Agent 内部的调试日志，打印每个 instrumentation 模块是否成功安装；-Dotel.traces.exporter=logging表示把 Span 直接输出到控制台，省得搭 Collector 和 Jaeger；-Dotel.metrics.exporter=none和-Dotel.logs.exporter=none是为了关掉暂时不需要的信号。
只要应用里发起了 HTTP 请求，控制台就会输出类似这样的日志：
Span #0 Trace ID: xxxxx Parent ID: Name: GET /hello ...看到日志输出的那一刻，你的本地链路才算真正跑通了。之后想接 Jaeger 或者 OpenTelemetry Collector，只需要把logging换成otlp，再配上 endpoint 就行。
3.3 调试方式三：在 IDE 里断点调试 Agent 代码
如果上面的前置验证都过了，但你怀疑是 Agent 内部某个逻辑出了问题，那就要用 IDE 断点调试了。最实用的方案是“挂载调试模式跑目标应用”。
第一步，在 IDE 里打开你的目标应用工程，添加一个远程调试配置，端口比如5005。第二步，用以下命令启动目标应用：
java -javaagent:/path/to/opentelemetry-javaagent-all.jar \ -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005 \ -jar your-app.jar第三步，在 IDE 中对 OpenTelemetry Java Instrumentation 源码打上断点，然后 attach 到localhost:5005。Java Agent 本身就是跑在目标应用 JVM 里的，所以它的所有类都会被 IDE 识别和命中。这一步你可以在TypeInstrumentation的transform方法、Advice类的onEnter/onExit方法里直接观察方法入参和上下文变量，比靠日志猜要高效得多。
需要特别提醒的是，当你用 IDE 调试 Agent 时，务必确认当前进程的 classpath 指向的是源码模块而不是打出来的 fat jar。否则你在源代码里打的断点不会命中，反而会被反编译出来的字节码搞得一头雾水。
3.4 开启详细日志：把 Agent 的“内心活动”打出来
调试 Agent 时，最烦人的场景就是埋点明明存在，但 Span 没生成。这时我会开启更细粒度的日志，除了-Dotel.javaagent.debug=true，还可以配合 ByteBuddy 的日志输出：
-Dnet.bytebuddy.debug=true -Dnet.bytebuddy.logger=slf4j打开之后，ByteBuddy 会打印它对每个类的匹配分析过程，例如“是否匹配某个类的前缀”、“是否安装 Advice 到某个方法”。这些信息对排查“为什么这个第三方库没被埋点”非常有用。日志量会很大，建议重定向到文件里再看：
java ... -javaagent:/path/to/agent.jar ... > agent-debug.log 2>&1然后直接用 grep 去过滤关键类名。实测下来这个组合拳比瞎猜高效得多。
4. 高频问题与排查技巧实录：这些坑我替你踩过了
4.1 编译阶段问题速查表
| 现象 | 根本原因 | 解决方案 |
|---|---|---|
| Gradle 同步失败，报仓库访问超时 | 默认源太慢 | 配置阿里云镜像，见本文 1.2 节 |
编译时OutOfMemoryError | Gradle JVM 堆太小 | 在 gradle.properties 里把org.gradle.jvmargs调到 4G |
报Unsupported class file major version 65之类 | JDK 版本太新或太旧 | 统一用 JDK 17 |
执行:javaagent:shadowJar后各种依赖缺失 | 上次构建中断导致缓存损坏 | 执行./gradlew clean后再重试 |
下载依赖时Could not resolve io.opentelemetry... | 本地 maven 缓存里有旧版本 | 删除~/.m2/repository/io/opentelemetry或对应缓存目录 |
| 编译报 Kotlin DSL 脚本错误 | IDE 启用了错误的 Gradle 版本 | 确保使用 wrapper，不要用全局 Gradle |
4.2 运行阶段：Agent 没生效的排查路径
这是所有问题里最让人头疼的，因为你明明看到 Agent 在启动日志里打印了“加载成功”，但访问应用接口后就是没有 Span 产生。我的排查路径基本是这样的。
第一步，确认 Agent 版本确实是最新打出来的包。这一步存在感很低但出错率极高，经常有人改了代码并运行了shadowJar，但启动应用时引用的还是老 jar 路径。我学乖之后会在启动命令里先ls -l一下 jar 文件的修改时间。
第二步，确认目标插件库版本在 support matrix 范围内。OpenTelemetry Java Instrumentation 的埋点模块对目标库版本是有要求的。比如某个模块支持 Spring Web MVC 5.x，但你的测试应用用的是 Spring Boot 3.x，底层 Spring 6.x 可能不在匹配范围内，Agent 就不会对类做增强。此时参考项目官方的版本支持文档是最好的方法。
第三步，打开 debug 日志，看 Agent 启动时是否真的安装了目标类的 instrumentation。在agent-debug.log里搜索目标第三方库的类名，比如DispatcherServlet，如果根本没有提到这个类，说明你的模块没打进 agent 包，或者模块在注册时未启用。如果提到了但“匹配失败”，则要考虑类加载器隔离和版本匹配问题。
第四步，确认 classloader 是否隔离导致自定义代码未生效。OpenTelemetry Java Agent 的默认设计是，所有 instrumentation 模块里的类都放在 Agent ClassLoader 里，与应用的类隔离。这既是优点也是坑：如果某个第三方库和 Agent 之间出现版本冲突，你很难直观判断是谁加载了谁。遇到这种场景，可以在日志里开启-Dotel.javaagent.experimental.strong-metrics之类的实验参数辅助观察，不过这类参数随版本变化较大，具体看 README。
4.3 绕不过去的 ByteBuddy 字节码问题
还有一类问题是定位到自定义代码里后，你发现在 Advice 类的方法上打了断点却不命中。比如你用@Advice.OnMethodEnter写了埋点逻辑，但执行结果不符合预期。
最常见的原因有这几个：
- 方法名写错了。Java 重载、bridge 方法、lambda 方法在字节码层面和源码表面不一样，你匹配的方法可能被编译器改写了。这时候我用
javap -v直接反编译目标类，确认准确的方法签名。 - Advice 类里用了不支持的 API。ByteBuddy 对 Advices 有个限制：它会把 Advice 代码内联到目标方法中，所以你在 Advice 里引用的某些外部类，在真正运行时可能因为 classloader 隔离而找不到。处理办法是尽量让 Advice 代码保持简单，只做数据收集和参数传递，把复杂逻辑放到
InstrumentationModule或独立 helper 类里。 @Advice.OnMethodExit里没有判空。很多业务方法返回值可能是 null，如果你在 OnExit 里直接对返回值做断言和操作，会在业务线程里抛异常，甚至导致接口本身报错。这也是新手最容易忽略的坑：埋点代码的异常不能影响业务。OpenTelemetry 内部捕获了很多异常，但你的自定义代码最好自己防御好。
5. 从“会调试”到“会开发”：自定义 Instrumentation 模块的基本套路
5.1 搭一个最小可用的新模块
如果你先完成了前面的本地调试，那离写自己的埋点模块就不远了。OpenTelemetry Java Instrumentation 的扩展模型其实很适合理解成“适配器插件”。你不需要改 SDK 核心，只需要写一个新的 instrumentation 子模块，并通过@AutoService(InstrumentationModule.class)注册进去。
创建一个新模块时，最省事的办法是复制一个简单的现有模块，比如instrumentation/armeria这类结构清晰的模块，然后按新名称重命名。你需要关心的文件有这几个：
build.gradle.kts：声明模块依赖和自动生成配置。src/main/java/.../XxxInstrumentationModule.java：模块入口，定义要增强的目标类列表。src/main/java/.../XxxTypeInstrumentation.java：类型增强器，用 ByteBuddy 的 ElementMatchers 匹配目标类和方法。src/main/java/.../XxxAdvice.java：实际被内联的 Advice 代码。
一个最简的模块入口大致长这样：
@AutoService(InstrumentationModule.class) public final class MyLibraryInstrumentationModule extends InstrumentationModule { public MyLibraryInstrumentationModule() { super("my-library"); } @Override public List<TypeInstrumentation> typeInstrumentations() { return List.of(new MyLibraryTypeInstrumentation()); } }类型增强器里面则负责定义规则。比如我想拦截某个类的execute方法，并创建一个 Span：
public class MyLibraryTypeInstrumentation implements TypeInstrumentation { @Override public ElementMatcher<TypeDescription> typeMatcher() { return named("com.example.MyLibraryClient"); } @Override public void transform(TypeTransformer transformer) { transformer.applyAdviceToMethod( named("execute") .and(takesArguments(1)) .and(isPublic()), MyLibraryAdvice.class.getName()); } }5.2 Advice 代码怎么写才稳
Advice 类有一点很反直觉：它并不真正被实例化，而是由 ByteBuddy 在打包时把它的逻辑直接拷贝到目标类的目标方法里。所以你把它写成一个普通类即可，但必须保持方法静态化：
public class MyLibraryAdvice { @Advice.OnMethodEnter(suppress = Throwable.class) public static void onEnter(@Advice.Argument(0) String request, @Advice.Local("otelSpan") Span span) { span = tracer.spanBuilder("my-library.execute").startSpan(); } @Advice.OnMethodExit(onThrowable = Throwable.class, suppress = Throwable.class) public static void onExit(@Advice.Local("otelSpan") Span span) { span.end(); } }这里我用@Advice.Local在方法进入和退出之间传递了同一个 Span 实例，避免在字节码层面重复创建多个 Span。另外特意用了suppress = Throwable.class，保证埋点代码不会因为业务方法的异常而翻车，这个习惯强烈建议养成。
5.3 模块写完后如何快速验证
写完自定义模块后，我建议不要直接跑整包 shadowJar，因为在庞大构建里一旦出错不好定位。更顺滑的流程是：
- 先跑这个模块自己的单元测试，用
testing-common里的 instrument 机制验证 Span 是否生成。 - 单测通过后，再编译整包
shadowJar，把新 jar 挂到真实测试应用上验证一次。 - 最后确认在
-Dotel.javaagent.debug=true日志里能搜到你的模块名，说明 Agent 确实加载并安装了你的埋点。
这样一步步递进排查问题，定位效率是最高的。我亲眼见过不少同事跳过前两步直接打整包，结果埋点没生效，然后花一下午疯狂找日志，最后发现只是模块没注册进META-INF/services。
6. 最后再分享两个让我少走弯路的细节
第一点是关于迭代周期的。OpenTelemetry Java Instrumentation 的项目体积太大了，如果每次改完代码都要打一整包再启动应用，你的开发节奏会很崩溃。我现在基本只在单测框架里完成 90% 的埋点逻辑验证，只有像 classloader 冲突这种单测覆盖不到的场景，才会打包做端到端验证。这不仅是习惯问题，更是效率问题。
第二点是关于日志的“克制”。调试初期我恨不得把所有日志都打到最详细，结果密密麻麻的输出反而让我迷失了重点。后来我只看三类日志：Agent 启动时的模块安装日志、ByteBuddy 的类匹配日志、Span 导出日志。这三个节点足够了，其他细节在需要时再单独开。控制输出粒度，能让你在排错时保持清醒。
根据我个人的实际经验，编译调试 OpenTelemetry Java Instrumentation 最难的不是某个具体报错修不掉，而是缺少一条清晰的调试路径。只要把环境版本选对、构建命令理清、单测框架用熟，绝大多数问题都能在一小时内定位到正确方向。上面这些坑和绕坑方法，都是我在原生环境和各类定制需求里反复验证过的。希望你的本地调试之旅，比我当初顺利得多。
