别再无脑用 OpenTelemetry 默认探针了：用 ByteBuddy 打造百 KB 级轻量化 Java Agent 实践

在云原生微服务体系中，分布式链路追踪已经是标配。作为云原生标准的 OpenTelemetry (OTel) 更是成为了许多团队的首选。然而，当你直接把官方提供的 opentelemetry-javaagent.jar（通常有 20MB ~ 30MB）挂载到 JVM 上时，你可能会面临以下尴尬：

1. 冷启动变慢：JVM 启动时，探针需要扫描并加载成百上千个不相关的第三方库适配器（从 Netty, OkHttp 到 JDBC, Logan），导致容器冷启动耗时翻倍甚至更长。
2. 内存消耗暴增：每个探针对 Class 字节码的修改和元数据缓存，都会无形中侵占 JVM 的 Metaspace 和 Heap 内存。
3. 类冲突与版本地狱：OTel 探针内置了大量依赖，尽管做了 Shading 处理，但在复杂的业务系统中，依然可能与应用本身的依赖发生微妙的冲突。

事实上，大部分业务系统只需要监控特定的 Web 框架（如 Spring Web / Dubbo）和特定的数据库组件。本文将带你用 ByteBuddy 和 Byteman 编写一个自定义、百 KB 级别的轻量级 Agent，既能保留 OpenTelemetry 的标准链路能力，又能彻底摆脱默认探针的臃肿。

方案对比：ByteBuddy 还是 Byteman？

在开始写代码前，我们先理清这两款字节码工具的适用场景：

生产环境的最佳实践：

• 采用 ByteBuddy 编写常驻生产的轻量级监控 Agent。
• 采用 Byteman 作为应急排查工具，动态注入规则定位临时故障。

第一部分：用 ByteBuddy 编写 100KB 的轻量 Agent

我们要实现的目标是：只拦截 Spring Web 的 Controller，自动创建 OpenTelemetry Span，而不引入 OTel 默认探针那几百个无关的 Instrumentation 插件。

1. 极简 Maven 配置（注意避坑）

我们需要依赖 byte-buddy 以及 OpenTelemetry API 接口（仅 API，不含 Agent 运行时）。

要保证 Agent 能够正常加载且不与业务应用冲突，必须使用 maven-shade-plugin 将 ByteBuddy 依赖重命名（Shade）。

<dependencies>
    <!-- ByteBuddy 核心依赖 -->
    <dependency>
        <groupId>net.bytebuddy</groupId>
        <artifactId>byte-buddy</artifactId>
        <version>1.14.12</version>
    </dependency>
    <!-- 仅引入 OTel API，用于构建 Span -->
    <dependency>
        <groupId>io.opentelemetry</groupId>
        <artifactId>opentelemetry-api</artifactId>
        <version>1.35.0</version>
    </dependency>
</dependencies>

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-jar-plugin</artifactId>
            <version>3.2.2</version>
            <configuration>
                <archive>
                    <manifestEntries>
                        <!-- 指定 Premain-Class 作为 Agent 入口 -->
                        <Premain-Class>com.example.agent.LightweightAgent</Premain-Class>
                        <Can-Redefine-Classes>true</Can-Redefine-Classes>
                        <Can-Retransform-Classes>true</Can-Retransform-Classes>
                    </manifestEntries>
                </archive>
            </configuration>
        </plugin>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-shade-plugin</artifactId>
            <version>3.4.1</version>
            <executions>
                <execution>
                    <phase>package</phase>
                    <goals>
                        <goal>shade</goal>
                    </goals>
                    <configuration>
                        <relocations>
                            <!-- 避坑指南：必须 Shade ByteBuddy，防止与应用内低版本冲突 -->
                            <relocation>
                                <pattern>net.bytebuddy</pattern>
                                <shadedPattern>com.example.agent.shaded.bytebuddy</shadedPattern>
                            </relocation>
                        </relocations>
                    </configuration>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

2. 编写 Agent 入口类

premain 方法会在 main 方法执行前被 JVM 调用。我们在这里使用 ByteBuddy 定义拦截规则。

package com.example.agent;

import net.bytebuddy.agent.builder.AgentBuilder;
import net.bytebuddy.asm.Advice;
import net.bytebuddy.matcher.ElementMatchers;
import java.lang.instrument.Instrumentation;

public class LightweightAgent {
    public static void premain(String agentArgs, Instrumentation inst) {
        System.out.println("[Lightweight Agent] Starting initialization...");

        new AgentBuilder.Default()
            // 排除不必要扫描的包，加快启动速度
            .ignore(ElementMatchers.nameStartsWith("java.")
                .or(ElementMatchers.nameStartsWith("javax."))
                .or(ElementMatchers.nameStartsWith("sun."))
                .or(ElementMatchers.nameStartsWith("com.example.agent.")))
            // 匹配所有带有 @RestController 或 @Controller 注解的类
            .type(ElementMatchers.isAnnotatedWith(
                ElementMatchers.named("org.springframework.web.bind.annotation.RestController")
                    .or(ElementMatchers.named("org.springframework.stereotype.Controller"))
            ))
            // 转换字节码：在符合条件的方法前后织入 Advice
            .transform((builder, typeDescription, classLoader, module, protectionDomain) ->
                builder.method(ElementMatchers.isPublic() // 仅拦截 public 方法
                       .and(ElementMatchers.not(ElementMatchers.isConstructor())))
                       .intercept(Advice.to(ControllerAdvice.class))
            )
            .installOn(inst);
        
        System.out.println("[Lightweight Agent] Handlers registered successfully.");
    }
}

3. 编写织入逻辑 (Advice)

ByteBuddy 的 Advice 机制非常高效，它会把代码直接“内联”到目标方法的开头和结尾，不产生额外的调用栈消耗。

我们在方法进入时启动 OpenTelemetry Span，在退出时结束 Span 并处理异常。

package com.example.agent;

import io.opentelemetry.api.GlobalOpenTelemetry;
import io.opentelemetry.api.trace.Span;
import io.opentelemetry.api.trace.Tracer;
import io.opentelemetry.context.Scope;
import net.bytebuddy.asm.Advice;

public class ControllerAdvice {

    private static final Tracer tracer = GlobalOpenTelemetry.getTracer("lightweight-agent", "1.0.0");

    // 方法进入时：创建并激活 Span
    @Advice.OnMethodEnter(suppress = Throwable.class)
    public static void onEnter(
            @Advice.Origin("#t.#m") String methodName, // 获取拦截的方法全名
            @Advice.Local("otelSpan") Span span,       // 本地局部变量传递给 Exit
            @Advice.Local("otelScope") Scope scope) {

        span = tracer.spanBuilder(methodName).startSpan();
        scope = span.makeCurrent();
    }

    // 方法退出时：关闭 Scope，标记异常或正常结束
    @Advice.OnMethodExit(onThrowable = Throwable.class, suppress = Throwable.class)
    public static void onExit(
            @Advice.Local("otelSpan") Span span,
            @Advice.Local("otelScope") Scope scope,
            @Advice.Thrown Throwable throwable) {

        if (scope != null) {
            scope.close();
        }
        if (span != null) {
            if (throwable != null) {
                span.recordException(throwable);
                span.setStatus(io.opentelemetry.api.trace.StatusCode.ERROR, throwable.getMessage());
            }
            span.end();
        }
    }
}

注意：suppress = Throwable.class 是极其重要的防误操作。即使我们自己的 Agent 逻辑因各种原因抛出异常，也绝对不能影响业务正常运行。

第二部分：用 Byteman 实现动态/免打包调试

ByteBuddy 适合构建静态打包的 Agent。但如果在排查线上问题时，不想重启服务，只想零成本注入几行代码监控某个具体的方法调用，Byteman 是更优雅的选择。

Byteman 基于 ECA (Event-Condition-Action) 规则脚本工作。

1. 编写 Byteman 规则脚本 (otel.txt)

例如，我们希望在不重启服务的情况下，拦截特定接口并打印执行耗时，或者通过 OTel 接口注入临时 Trace：

RULE trace spring controller entry
CLASS org.example.demo.controller.UserController
METHOD getUserDetail
AT ENTRY
IF true
DO
  traceln("[Byteman Trace] Entering getUserDetail at: " + java.lang.System.currentTimeMillis());
ENDRULE

RULE trace spring controller exit
CLASS org.example.demo.controller.UserController
METHOD getUserDetail
AT EXIT
IF true
DO
  traceln("[Byteman Trace] Exiting getUserDetail.");
ENDRULE

2. 在运行时动态挂载

无需修改启动命令，直接使用 Byteman 的脚本注入工具，将上述规则热加载到运行中的 JVM 里：

# 下载 byteman 并解压
export BYTEMAN_HOME=/path/to/byteman

# 动态将 byteman 代理注入到指定的 Java 进程 PID
$BYTEMAN_HOME/bin/byteman-install.sh <PID>

# 加载我们写好的监测规则
$BYTEMAN_HOME/bin/byteman-submit.sh -l otel.txt

当 UserController.getUserDetail 被调用时，控制台便会实时打印出进入与退出的耗时。调试完毕后，可随时卸载：

# 卸载规则
$BYTEMAN_HOME/bin/byteman-submit.sh -u otel.txt

生产落地：如何桥接 OpenTelemetry 收集端？

虽然我们用 ByteBuddy 写出了不到 100KB 的精简 Agent，但这个 Agent 需要和业务项目共享一个 OpenTelemetry SDK 实例。有两种常见玩法：

方案 A：宿主应用负责配置 SDK (推荐)

你的业务 Spring Boot 应用本身引入了 opentelemetry-sdk 依赖，并通过配置文件指定了 OTLP Exporter 的上报地址。自定义 Agent 只需要从 GlobalOpenTelemetry.getTracer() 获取实例。

• 优点：Agent 体积小，上报管道配置灵活，可以使用 Spring 的 ApplicationContext 进行动态管理。
• 缺点：应用需要显示依赖 OTel 相关的 SDK 包。

方案 B：Agent 内部打包 SDK

如果要求业务应用保持纯净，必须将 opentelemetry-sdk 打包进自定义的 Agent 中，并在 premain 阶段通过代码硬编码或读取环境变量初始化 SDK 导出器（OTLP Exporter）。

• 优点：对业务应用完全零侵入。
• 缺点：Agent Jar 包体积会增大到 2MB ~ 3MB，但相比官方 20MB+ 依然属于绝对的轻量级。

极致调优：如何压缩至极限？

1. 绝对不要用 OTel 默认探针的 shaded 大包：必须使用 opentelemetry-api 这个纯接口包（约 200KB）。
2. 拒绝全面扫描：使用 AgentBuilder 时，一定要将扫描范围限制在特定的 Package 下（例如 net.bytebuddy.matcher.ElementMatchers.nameStartsWith("com.yourcompany.")），这不仅可以防止扫描无关类导致启动变慢，还能大幅降低探针加载时的 CPU 尖峰。
3. 选择性忽略中间件：如果对特定中间件不感冒，不要匹配它。仅仅织入你需要监控的边界服务（如 Web 入口、RPC 客户端出口和数据库调用连接池）。

通过以上方式定制的 Agent，其实测内存开销几乎无法被微基准测试（JMH）捕捉到，冷启动耗时增加可以忽略不计（<200ms），能够完美解决全量探针带来的容器资源浪费。