Java中 SkyWalking 自定义 @Trace 注解怎么结合 Agent 字节码增强追踪链路-java教程-PHP中文网

@Trace 注解不会被 SkyWalking Agent 自动增强，因其仅为语义标记而非增强指令；Agent 仅通过预定义插件增强特定框架类，不扫描自定义注解；需配合 Tracer API 手动创建 Span 或借助 Spring AOP 实现半自动埋点。

java中 skywalking 自定义 @trace 注解怎么结合 agent 字节码增强追踪链路

Java 中 SkyWalking 的 @Trace 注解本身**不会被 Agent 自动识别和增强**，它仅是 SkyWalking SDK 提供的“手动埋点”标记，需配合 Tracer API 显式创建 Span 才能真正上报链路。Agent 的字节码增强（ByteBuddy）默认只处理 SkyWalking 内置插件（如 Spring MVC、Dubbo、OkHttp 等），**不扫描或增强用户自定义注解**。

为什么 @Trace 不会被 Agent 自动增强？

SkyWalking Agent 的插件机制基于“已知目标类 + 方法签名 + 增强逻辑”的预定义规则。它不会：

全局扫描所有带 @Trace 的方法并自动插入字节码
将 @Trace 视为“触发增强的元数据”（类似 Spring AOP 的 @Aspect）
在运行时动态生成代理或修改未在插件配置中声明的目标类

换句话说：@Trace 是一个“语义标记”，不是“增强指令”。它的作用是提醒开发者此处需要追踪，但执行追踪仍需主动调用 SDK。

正确结合方式：@Trace + 手动 Tracer API

推荐做法是在标注 @Trace 的方法内，使用 Tracer 创建本地 Span。这是轻量、可控且与 Agent 完全兼容的方式：

确保项目已引入 skywalking-agent.jar 并正常启动（-javaagent）
添加 SDK 依赖：org.apache.skywalking.apm.toolkit:apm-toolkit-trace
在业务方法中显式使用 Tracer：

@Trace
public void doBusiness() {
    // 创建本地 Span（属于当前 TraceContext）
    AbstractSpan span = Tracer.createLocalSpan("DoBusiness");
    try {
        // 你的业务逻辑
        Thread.sleep(100);
    } catch (Exception e) {
        span.error(e); // 标记异常
        throw e;
    } finally {
        span.end(); // 必须调用，否则 Span 不上报
    }
}

进阶：自定义 Agent 插件支持 @Trace（需开发插件）

若确实希望“零侵入”地让 Agent 自动增强所有 @Trace 方法，可开发自定义插件：

Java注释规范Skills

当用户要求为 Java 代码添加注释、修改注释、审查注释、整理注释格式，或要求按照代码注释规范处理 Java 文件时，使用本技能。本技能用于统一生成和维护 Java 类注释模板、按 Git 对比 release 判断版本号、补充每行代码上方中文块注释、调整注释空行规则，并保持 Java 文件 UTF-8 无 BOM 编码。典型触发场景包括：补充类注释、更新 @version、检查 @author 来源、整理行尾注释、把注释放到代码上一行、检查注释是否符合规范、构建前检查 Java 注释风格。

下载

新建模块，继承 ClassEnhancePluginDefine，重写 define 方法
匹配目标类中带有 @Trace 注解的方法（使用 AnnotationMatch）
指定前置（TraceMethodInterceptor.beforeMethod）和后置（afterMethod）拦截器
在拦截器中调用 Tracer.createLocalSpan() 和 span.end()
将插件 JAR 放入 Agent plugins/ 目录，重启应用

⚠️ 注意：该方式需熟悉 SkyWalking 插件开发规范，且每次升级 Agent 版本都需验证兼容性，生产环境慎用。

替代方案：用 Spring AOP + @Trace 实现半自动埋点

若项目使用 Spring，更实用的做法是结合 AOP 统一处理 @Trace：

定义切面，拦截所有标注 @Trace 的 public 方法
在 @Around 中创建 Span，捕获异常，统一结束
避免每个方法重复写 Tracer 模板代码

@Aspect
@Component
public class TraceAspect {
    @Around("@annotation(org.apache.skywalking.apm.toolkit.trace.Trace)")
    public Object traceMethod(ProceedingJoinPoint joinPoint) throws Throwable {
        String methodName = joinPoint.getSignature().toShortString();
        AbstractSpan span = Tracer.createLocalSpan("AOP-" + methodName);
        try {
            return joinPoint.proceed();
        } catch (Exception e) {
            span.error(e);
            throw e;
        } finally {
            span.end();
        }
    }
}

这种方式无需改 Agent，复用现有 SDK，又减少了样板代码，适合大多数 Spring Boot 场景。