Building a lightweight method tracer with Byte Buddy — from runtime subclassing to a Java agent

You inherit a service that calls an external system, and someone asks the deceptively simple question: how long does each call take, and how often does it fail? The honest answer should take ten minutes, but the service has no metrics, no tracing, and its construction is buried three frameworks deep. You could add timing code by hand — and then do it again for the next service, and the next.

This article builds the small tool instead: a method tracer that records the method name, execution time, success or failure, and a correlation ID — without changing the service’s source code. You will build it three ways, each motivated by the limitations of the last: a runtime subclass with MethodDelegation, the same tracer using inlined advice, and finally a premain Java agent built on AgentBuilder that transforms the class as it loads. By the end you will also attach the agent to a running JVM and retransform an already-loaded class, which is where the interesting constraints live.

The target output looks like this:

1
[trace] ok   in.o612.eng.tracedemo.service.OrderService.quote 3291 µs cid=req-1042
2
[trace] ok   in.o612.eng.tracedemo.service.OrderService.charge 13817 µs cid=req-1042
3
charged: order O-100 priced at 49.90
4
[trace] fail in.o612.eng.tracedemo.service.OrderService.quote 49 µs cid=req-1043 error=IllegalStateException
5
caller saw: unknown order O-999

Everything below was compiled and executed on JDK 21 with Byte Buddy 1.18.14, the current release at the time of writing. Byte Buddy’s API is stable, but the version-sensitive details — matcher names, annotation attributes, agent builder interfaces — were checked against that release specifically.

Three ways to change what a method does

Before writing code, it is worth being precise about what “instrument a method” can mean, because Byte Buddy supports three distinct operations and they differ in when they take effect and which objects they reach.

Subclassing generates a new class — OrderService$ByteBuddy$KGpCWwck or similar — that extends your class and overrides matched methods. The original class file is untouched. Only instances of the generated class are intercepted; a new OrderService() elsewhere in the program runs the original code, and objects created before the subclass exists are unaffected. Calls reach the original implementation through super, exactly as if you had written a subclass by hand.

Redefinition replaces the byte array of a class before it is loaded — a ClassFileTransformer registered through java.lang.instrument sees every class file as it enters a class loader and can substitute new bytes. Every instance of the class gets the new behavior, but the transformation must happen before the class is first loaded.

Retransformation replaces the bytecode of a class that is already loaded. This is the only mechanism that changes code for objects that already exist, and it comes with the JVM’s hard constraint: the new version may not add, remove, or rename fields or methods, change signatures, or alter the class hierarchy. Method bodies may change freely. (The restriction comes from Instrumentation.retransformClasses, not Byte Buddy — see the java.lang.instrument javadoc.) One more subtlety: methods already on the call stack continue executing the old bytecode until they return.

That table is the spine of the article. We will hit its limits in order.

The sample service

The example is deliberately small. OrderService has one method that succeeds and one that throws, plus a wrinkle: charge calls quote internally through this, which will matter when we discuss what “interception” actually covers.

1
package in.o612.eng.tracedemo.service;
2

3
import java.math.BigDecimal;
4
import java.util.Map;
5

6
public class OrderService {
7

8
    private final Map<String, BigDecimal> prices =
9
        Map.of("O-100", new BigDecimal("49.90"), "O-200", new BigDecimal("12.50"));
10

11
    public String quote(String orderId) {
12
        BigDecimal price = prices.get(orderId);
13
        if (price == null) {
14
            throw new IllegalStateException("unknown order " + orderId);
15
        }
16
        return "order " + orderId + " priced at " + price;
17
    }
18

19
    public String charge(String orderId) {
20
        // Internal call through `this` — virtual dispatch still applies.
21
        return "charged: " + quote(orderId);
22
    }
23
}

TraceRecorder is the entire runtime of the tool — time the call, emit a line, read a correlation ID from a ThreadLocal. The thread-local belongs to the caller: whoever runs a unit of work sets it, and clears it in a finally so it cannot leak into the next task on a pooled thread. The tracer only reads it.

1
package in.o612.eng.tracer;
2

3
public final class TraceRecorder {
4

5
    /** Populated and cleared by the caller's unit of work; the tracer only reads it. */
6
    public static final ThreadLocal<String> CORRELATION_ID = new ThreadLocal<>();
7

8
    private TraceRecorder() {
9
    }
10

11
    public static long enter() {
12
        return System.nanoTime();
13
    }
14

15
    public static void exit(String signature, long startNanos, Throwable thrown) {
16
        long micros = (System.nanoTime() - startNanos) / 1_000L;
17
        String cid = CORRELATION_ID.get();
18
        String status = thrown == null ? "ok  " : "fail";
19
        String detail = thrown == null ? "" : " error=" + thrown.getClass().getSimpleName();
20
        String context = cid == null ? "" : " cid=" + cid;
21
        System.out.printf("[trace] %s %s %d µs%s%s%n", status, signature, micros, context, detail);
22
    }
23
}

System.nanoTime() is the right clock here — it is monotonic and cheap; wall-clock time (System.currentTimeMillis) can move backwards under NTP corrections and would corrupt durations.

Project layout

A single Maven module is enough. The same jar will later double as the agent jar.

1
bytebuddy-tracer/
2
├── pom.xml
3
└── src/main/java/in/o612/eng/
4
    ├── tracedemo/
5
    │   ├── Main.java
6
    │   ├── SubclassDemo.java
7
    │   ├── AdviceDemo.java
8
    │   ├── AttachDemo.java
9
    │   └── service/OrderService.java
10
    └── tracer/
11
        ├── TraceRecorder.java
12
        ├── TimingInterceptor.java
13
        ├── TracingAdvice.java
14
        └── TracingAgent.java

1
<project xmlns="http://maven.apache.org/POM/4.0.0"
2
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
3
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
4
  <modelVersion>4.0.0</modelVersion>
5
  <groupId>in.o612.eng</groupId>
6
  <artifactId>bytebuddy-tracer</artifactId>
7
  <version>1.0.0</version>
8

9
  <properties>
10
    <maven.compiler.release>21</maven.compiler.release>
11
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
12
  </properties>
13

14
  <dependencies>
15
    <dependency>
16
      <groupId>net.bytebuddy</groupId>
17
      <artifactId>byte-buddy</artifactId>
18
      <version>1.18.14</version>
19
    </dependency>
20
    <!-- Only needed for the runtime-attach demo later. -->
21
    <dependency>
22
      <groupId>net.bytebuddy</groupId>
23
      <artifactId>byte-buddy-agent</artifactId>
24
      <version>1.18.14</version>
25
    </dependency>
26
  </dependencies>
27

28
  <build>
29
    <plugins>
30
      <plugin>
31
        <artifactId>maven-jar-plugin</artifactId>
32
        <configuration>
33
          <archive>
34
            <manifestEntries>
35
              <Premain-Class>in.o612.eng.tracer.TracingAgent</Premain-Class>
36
              <Can-Retransform-Classes>true</Can-Retransform-Classes>
37
            </manifestEntries>
38
          </archive>
39
        </configuration>
40
      </plugin>
41
    </plugins>
42
  </build>
43
</project>

net.bytebuddy:byte-buddy is the code-generation library itself; byte-buddy-agent is the separate artifact for attaching to a running JVM (it is not needed for -javaagent usage — premain receives the Instrumentation instance for free).

Stage 1 — a subclassing tracer

The simplest thing that works: generate a subclass, override the public methods, and delegate each call to a tracing interceptor.

1
package in.o612.eng.tracedemo;
2

3
import static net.bytebuddy.matcher.ElementMatchers.isDeclaredBy;
4
import static net.bytebuddy.matcher.ElementMatchers.isPublic;
5
import static net.bytebuddy.matcher.ElementMatchers.not;
6

7
import in.o612.eng.tracedemo.service.OrderService;
8
import in.o612.eng.tracer.TimingInterceptor;
9
import in.o612.eng.tracer.TraceRecorder;
10
import net.bytebuddy.ByteBuddy;
11
import net.bytebuddy.dynamic.loading.ClassLoadingStrategy;
12
import net.bytebuddy.implementation.MethodDelegation;
13

14
public final class SubclassDemo {
15

16
    public static void main(String[] args) throws Exception {
17
        OrderService traced = new ByteBuddy()
18
            .subclass(OrderService.class)
19
            .method(isPublic().and(not(isDeclaredBy(Object.class))))
20
            .intercept(MethodDelegation.to(TimingInterceptor.class))
21
            .make()
22
            .load(OrderService.class.getClassLoader(), ClassLoadingStrategy.Default.WRAPPER)
23
            .getLoaded()
24
            .getDeclaredConstructor()
25
            .newInstance();
26

27
        System.out.println("traced instance class: " + traced.getClass().getName());
28
        run(traced);
29

30
        System.out.println("-- plain instance below --");
31
        run(new OrderService());
32
    }
33

34
    static void run(OrderService service) {
35
        TraceRecorder.CORRELATION_ID.set("req-1042");
36
        try {
37
            System.out.println(service.charge("O-100"));
38
        } finally {
39
            TraceRecorder.CORRELATION_ID.remove();
40
        }
41

42
        TraceRecorder.CORRELATION_ID.set("req-1043");
43
        try {
44
            service.quote("O-999");
45
        } catch (IllegalStateException expected) {
46
            System.out.println("caller saw: " + expected.getMessage());
47
        } finally {
48
            TraceRecorder.CORRELATION_ID.remove();
49
        }
50
    }
51
}

1
package in.o612.eng.tracer;
2

3
import java.lang.reflect.Method;
4
import java.util.concurrent.Callable;
5
import net.bytebuddy.implementation.bind.annotation.AllArguments;
6
import net.bytebuddy.implementation.bind.annotation.Origin;
7
import net.bytebuddy.implementation.bind.annotation.RuntimeType;
8
import net.bytebuddy.implementation.bind.annotation.SuperCall;
9

10
public final class TimingInterceptor {
11

12
    private TimingInterceptor() {
13
    }
14

15
    @RuntimeType
16
    public static Object trace(@Origin Method method,
17
                               @AllArguments Object[] args,
18
                               @SuperCall Callable<?> superCall) {
19
        long start = TraceRecorder.enter();
20
        try {
21
            Object result = superCall.call();
22
            TraceRecorder.exit(method.getName(), start, null);
23
            return result;
24
        } catch (Throwable t) {
25
            TraceRecorder.exit(method.getName(), start, t);
26
            throw rethrow(t);
27
        }
28
    }
29

30
    // Checked exceptions are a javac concept; at the bytecode level this rethrows
31
    // the original Throwable unchanged, so the caller sees identical semantics.
32
    @SuppressWarnings("unchecked")
33
    private static <E extends Throwable> RuntimeException rethrow(Throwable t) throws E {
34
        throw (E) t;
35
    }
36
}

Running it produces:

1
traced instance class: in.o612.eng.tracedemo.service.OrderService$ByteBuddy$KGpCWwck
2
[trace] ok   quote 4209 µs cid=req-1042
3
[trace] ok   charge 13813 µs cid=req-1042
4
charged: order O-100 priced at 49.90
5
[trace] fail quote 58 µs cid=req-1043 error=IllegalStateException
6
caller saw: unknown order O-999
7
-- plain instance below --
8
charged: order O-100 priced at 49.90
9
caller saw: unknown order O-999

Several things worth noticing in that output:

• The internal charge → quote call is traced. Because charge invokes this.quote(...), and this is an instance of the generated subclass, virtual dispatch lands on the override. Subclass interception does capture self-calls — that is a difference from wrapper/proxy schemes that sit outside the object.
• The exception propagates with identical semantics. caller saw: unknown order O-999 — the caller catches the same IllegalStateException it would have seen without instrumentation.
• The plain new OrderService() produces no trace lines. The generated subclass is a different class; existing construction sites are untouched. This is the fundamental limit we will dissolve later.

ClassLoadingStrategy.Default.WRAPPER loads the generated class in a new class loader beneath the one that loaded OrderService. That is the safest default: it avoids mutating the application class loader, and the generated class resolves TimingInterceptor and TraceRecorder through normal parent delegation. The alternative, INJECTION, defines the class in the same loader — necessary if you intercept package-private or protected methods, which WRAPPER cannot see across the loader boundary. All our targets are public, so WRAPPER suffices.

What Byte Buddy actually generated: a class extending OrderService with a synthetic name, each matched method overridden to build the argument array, call TimingInterceptor.trace(...), and — this is the important part — an auxiliary super-call method that invokes OrderService.quote via invokespecial, wrapped in the Callable passed to superCall.call(). The interceptor is therefore a genuine method call away from the original code, not bytecode merged into it.

What MethodDelegation does — and what it costs

The interceptor’s parameters are not magic; they are bound by a resolver that matches each parameter to what the instrumented method can supply, using the annotations:

• @SuperCall Callable<?> superCall — invokes the original (super) implementation. Returning a Callable rather than invoking eagerly is what lets the interceptor wrap the call in try/catch.
• @Origin Method method — the java.lang.reflect.Method of the instrumented method. @Origin can also inject String templates ("#t.#m" produces com.foo.Bar.baz), Class, MethodHandle, and several other shapes.
• @AllArguments Object[] args — the invocation arguments, boxed into an array. We do not use them yet, but they are the hook for logging inputs — and for accidentally logging a customer’s password, which is why production tracers filter arguments rather than dumping them.

Two binding rules bit me while writing this example, and both produce the same terse error — None of [...] allows for delegation from ...:

1. @RuntimeType is required for a return-type mismatch. The interceptor returns Object, but quote returns String. Without @RuntimeType, Byte Buddy requires the delegate’s return type to be assignable to the instrumented method’s return type — Object is not assignable to String. The annotation tells the binder to insert a checkcast at the call site. (The cast is checked by the JVM, so a wrong return type fails with ClassCastException, not silent corruption.)
2. Declared exceptions are checked. An early version of TimingInterceptor declared throws Throwable — and binding failed again, because the binder validates that every checked exception the delegate declares is compatible with the target method’s throws clause. quote declares none, so the delegate may declare none either. That is why rethrow uses the generic sneaky-throw: <E extends Throwable> RuntimeException rethrow(Throwable t) throws E compiles to a plain athrow — the JVM does not verify checked exceptions at the bytecode level, so the original exception escapes with its exact type and stack trace. Catching Throwable and rethrowing via throw t would not compile, and wrapping it in RuntimeException would change the failure contract.

The cost model of delegation: each intercepted call allocates the argument array (@AllArguments) and — depending on Byte Buddy’s caching — a Callable for the super-call, executes a reflective-style dispatch through the interceptor, and box/unboxes primitives into the Object[]. The interceptor frame also sits on the stack between caller and target. None of that is fatal at low call rates, but on a hot path it is real, measurable garbage. Delegation’s strength is flexibility — full reflection metadata, replaceable arguments (@Morph, @DefaultCall, @This), pluggable interceptors — not minimal overhead.

And the structural limits remain: only overridable methods can be intercepted (final, private, static, and constructors cannot be overridden), the target class itself must not be final, and — the reason we are not done — only instances of the generated subclass are instrumented.

Stage 2 — Advice: the same tracer, inlined

Advice works differently. Instead of generating a method that calls out to a delegate, Byte Buddy copies the advice’s bytecode into the instrumented method — at entry and at exit — around the original body. Nothing delegates; there is no interceptor frame, no Callable, no Method object lookup. The same TraceRecorder from stage 1 carries over unchanged.

1
package in.o612.eng.tracer;
2

3
import net.bytebuddy.asm.Advice;
4

5
public final class TracingAdvice {
6

7
    private TracingAdvice() {
8
    }
9

10
    @Advice.OnMethodEnter
11
    static long enter() {
12
        return TraceRecorder.enter();
13
    }
14

15
    @Advice.OnMethodExit(onThrowable = Throwable.class)
16
    static void exit(@Advice.Origin("#t.#m") String signature,
17
                     @Advice.Enter long start,
18
                     @Advice.Thrown Throwable thrown) {
19
        TraceRecorder.exit(signature, start, thrown);
20
    }
21
}

Three bindings do the work:

• @Advice.OnMethodEnter runs at method entry; its non-void return value can be passed to the exit advice via @Advice.Enter — this is how start travels from entry to exit without any thread-local bookkeeping. Because Byte Buddy stores it in a new local variable of the instrumented method, it is correct under recursion and concurrency with zero extra work.
• @Advice.OnMethodExit(onThrowable = Throwable.class) is the critical piece for correctness: the exit advice runs whether the method returns normally or throws, and the exception is rethrown after the advice completes — the catch block around the method body lives in bytecode, so the caller’s view of the exception is unchanged. @Advice.Thrown binds that throwable (null on normal return). Without onThrowable, the exit advice is skipped on exceptional exit and failed calls would vanish from the trace.
• @Advice.Origin("#t.#m") injects a constant string — DeclaringType.methodName — resolved at instrumentation time. It costs nothing at runtime.

The demo is identical except for the implementation strategy:

1
OrderService traced = new ByteBuddy()
2
    .subclass(OrderService.class)
3
    .method(isPublic().and(not(isDeclaredBy(Object.class))))
4
    .intercept(Advice.to(TracingAdvice.class))
5
    .make()
6
    .load(OrderService.class.getClassLoader(), ClassLoadingStrategy.Default.WRAPPER)
7
    .getLoaded()
8
    .getDeclaredConstructor()
9
    .newInstance();

What “inlined” concretely means is easiest to see in the generated bytecode. Running javap -c on the transformed OrderService.quote:

1
public java.lang.String quote(java.lang.String);
2
  Code:
3
     0: invokestatic  TraceRecorder.enter:()J
4
     6: lstore_2                        // @Advice.Enter start
5
     ...
6
    14: <original method body>
7
    74: astore        5                 // catch Throwable -> thrown
8
    79: ldc           "in.o612.eng.tracedemo.service.OrderService.quote"
9
    81: lload_2
10
    82: aload         5
11
    84: invokestatic  TraceRecorder.exit:(Ljava/lang/String;JLjava/lang/Throwable;)V
12
    90: aload         5
13
    92: ifnull        98
14
    95: aload         5
15
    97: athrow                          // rethrow original exception
16
    98: aload         4
17
   100: areturn
18
  Exception table:
19
     from    to  target type
20
       14    66    74   Class java/lang/Throwable

The signature string is an ldc constant; the catch handler captures Throwable into a local, the shared exit path calls TraceRecorder.exit, and then either athrow rethrows the captured throwable or areturn returns the captured result. Entry timing went into local slot 2. There is no delegation anywhere in this bytecode — the advice became part of the method.

Is Advice “faster” than delegation here? Marginally — it removes the interceptor frame, the Callable, and the argument array we never used. But the honest reason it is the better fit at this stage is structural, not benchmarked: inlining is what makes transformation of already-loaded classes possible at all. A delegate requires auxiliary methods (the super-call plumbing) that retransformation cannot add; inlined advice only touches method bodies. Advice is also more constrained — it cannot change the method signature, it binds fields of the target class with @Advice.FieldValue, and by default exceptions thrown by the advice itself propagate to the caller. If a tracer bug must never break the traced application, add suppress = Throwable.class to the advice annotations — a deliberate choice: instrumentation failures become invisible, so pair it with a debug listener.

Two more properties worth internalizing, because they will matter in the agent stage:

• The inlined code executes in the instrumented class’s class-loader context. The invokestatic TraceRecorder.exit inside OrderService.quote is resolved by OrderService’s class loader — so TraceRecorder must be visible to that loader, not to the agent’s. Keep this in mind; it is the cause of the most common agent failure.
• Advice classes are templates, not delegates. TracingAdvice’s methods are never called — only copied. Anything the advice references (TraceRecorder) is referenced by the copied code, so it must exist where the instrumented class lives.

Stage 3 — packaging as a Java agent

Now the payoff: trace OrderService without changing how it is constructed. A Java agent is a jar with a Premain-Class manifest entry; the JVM calls premain(String, Instrumentation) before main, giving the agent a ClassFileTransformer hook into every class load.

1
package in.o612.eng.tracer;
2

3
import static net.bytebuddy.matcher.ElementMatchers.isDeclaredBy;
4
import static net.bytebuddy.matcher.ElementMatchers.isMethod;
5
import static net.bytebuddy.matcher.ElementMatchers.isPublic;
6
import static net.bytebuddy.matcher.ElementMatchers.isSynthetic;
7
import static net.bytebuddy.matcher.ElementMatchers.nameStartsWith;
8
import static net.bytebuddy.matcher.ElementMatchers.not;
9

10
import java.lang.instrument.Instrumentation;
11
import net.bytebuddy.agent.builder.AgentBuilder;
12
import net.bytebuddy.asm.Advice;
13

14
public final class TracingAgent {
15

16
    public static void premain(String agentArgs, Instrumentation instrumentation) {
17
        new AgentBuilder.Default()
18
            .ignore(nameStartsWith("net.bytebuddy.")
19
                .or(nameStartsWith("in.o612.eng.tracer."))
20
                .or(isSynthetic()))
21
            .type(nameStartsWith("in.o612.eng.tracedemo.service."))
22
            .transform(new AgentBuilder.Transformer.ForAdvice()
23
                .include(TracingAgent.class.getClassLoader())
24
                .advice(isMethod()
25
                        .and(isPublic())
26
                        .and(not(isDeclaredBy(Object.class))),
27
                    TracingAdvice.class.getName()))
28
            .installOn(instrumentation);
29
    }
30
}

Dissecting the builder:

• .ignore(...) runs before the type matcher and excludes three categories: Byte Buddy’s own classes, the tracer itself (in.o612.eng.tracer), and synthetic types. Our type matcher is narrow enough that none of these would match anyway, but the ignore is cheap insurance — the moment someone widens in.o612.eng.tracedemo.service. to in.o612.eng., the tracer’s own classes come into scope, and an instrumented TraceRecorder.exit called from inlined advice inside TraceRecorder.exit is infinite recursion. (Byte Buddy additionally guards against circular transformation with a built-in circularity lock, but that protects the transformation pipeline, not your matchers.)
• .type(nameStartsWith("in.o612.eng.tracedemo.service.")) is the scoping decision. In a real service this would be something like nameStartsWith("com.acme.billing.") or isAnnotatedWith(RestController.class). Resist ElementMatchers.any() — every discovered class pays the price of evaluating your transformer, and instrumenting JDK internals is a reliable way to produce confusing NoClassDefFoundErrors during startup.
• AgentBuilder.Transformer.ForAdvice applies advice by class name, reading the advice class’s bytecode through .include(...)’s class-loader-based locator. This is the idiomatic agent pattern: the advice class is used as a template without being prematurely loaded or linked.
• The method matcher isMethod().and(isPublic()).and(not(isDeclaredBy(Object.class))) excludes constructors (isMethod matches only methods, not <init>/<clinit>) and the Object trio.

The demo Main is deliberately boring — plain construction, no Byte Buddy imports:

1
package in.o612.eng.tracedemo;
2

3
import in.o612.eng.tracedemo.service.OrderService;
4
import in.o612.eng.tracer.TraceRecorder;
5

6
public final class Main {
7

8
    public static void main(String[] args) {
9
        OrderService service = new OrderService();
10

11
        TraceRecorder.CORRELATION_ID.set("req-1042");
12
        try {
13
            System.out.println(service.charge("O-100"));
14
        } finally {
15
            TraceRecorder.CORRELATION_ID.remove();
16
        }
17

18
        TraceRecorder.CORRELATION_ID.set("req-1043");
19
        try {
20
            service.quote("O-999");
21
        } catch (IllegalStateException expected) {
22
            System.out.println("caller saw: " + expected.getMessage());
23
        } finally {
24
            TraceRecorder.CORRELATION_ID.remove();
25
        }
26
    }
27
}

Build and run:

1
mvn package
2
java -javaagent:target/bytebuddy-tracer-1.0.0.jar \
3
     -cp target/bytebuddy-tracer-1.0.0.jar \
4
     in.o612.eng.tracedemo.Main

1
[trace] ok   in.o612.eng.tracedemo.service.OrderService.quote 3291 µs cid=req-1042
2
[trace] ok   in.o612.eng.tracedemo.service.OrderService.charge 13817 µs cid=req-1042
3
charged: order O-100 priced at 49.90
4
[trace] fail in.o612.eng.tracedemo.service.OrderService.quote 49 µs cid=req-1043 error=IllegalStateException
5
caller saw: unknown order O-999

Same output as stage 1, but new OrderService() — unmodified — is traced. Two subtle differences worth noticing:

• #t now prints the real class name. Under subclassing, @Origin resolved to OrderService$ByteBuddy$...; under transformation the instrumented class is OrderService, which is what you want in logs.
• The tracer classes resolve through the application class loader. -javaagent appends the agent jar to the system classpath, so in.o612.eng.tracer.* classes are loadable by the same loader that owns OrderService, and the inlined invokestatic resolves. If you instrumented a class loaded by the bootstrap loader (a java.* class, say), that loader cannot see the classpath — the inlined call would fail with NoClassDefFoundError. Real agents solve this by injecting helper classes into the bootstrap loader (ClassInjector.UsingInstrumentation, wrapped by AgentBuilder’s bootstrap-injection support); for an application-scoped tracer, staying on the system classpath is enough.

Correlation ID lifecycle. CORRELATION_ID.set(...) enters the context at the boundary of the unit of work; remove() in finally ends it. The tracer reads the thread-local when emitting the record — the value travels into the trace output and is then dropped by the caller’s cleanup. In a Spring service the boundary would be a HandlerInterceptor or servlet filter that the agent also instruments; the demo simulates that boundary inline. What the demo does not do is propagate context across threads — the quote/charge calls run on the calling thread, so a plain ThreadLocal suffices; once work hops to an executor, you need context propagation (transmittable thread-locals, or capturing context at task-submission time), which is squarely out of scope here.

When the class is already loaded: attach and retransformation

premain only sees classes loaded after the JVM hands it control. For a running process — a Spring Boot service you cannot restart — agents can also attach dynamically via agentmain or, in-process, ByteBuddyAgent.install() from byte-buddy-agent. The AgentBuilder gains one new ingredient: RedefinitionStrategy.RETRANSFORMATION, which additionally scans for already-loaded classes matching the type matcher and calls Instrumentation.retransformClasses on them.

1
OrderService service = new OrderService();
2
service.quote("O-100");  // untraced — class already loaded and executed
3

4
var instrumentation = ByteBuddyAgent.install();
5
new AgentBuilder.Default()
6
    .ignore(nameStartsWith("net.bytebuddy.")
7
        .or(nameStartsWith("in.o612.eng.tracer."))
8
        .or(isSynthetic()))
9
    .type(nameStartsWith("in.o612.eng.tracedemo.service."))
10
    .transform(new AgentBuilder.Transformer.ForAdvice()
11
        .include(AttachDemo.class.getClassLoader())
12
        .advice(isMethod().and(isPublic()).and(not(isDeclaredBy(Object.class))),
13
            TracingAdvice.class.getName()))
14
    .with(AgentBuilder.RedefinitionStrategy.RETRANSFORMATION)
15
    .with(AgentBuilder.InitializationStrategy.NoOp.INSTANCE)
16
    .installOn(instrumentation);
17

18
service.quote("O-200");  // traced — same instance, new bytecode

1
before: order O-100 priced at 49.90
2
[trace] ok   in.o612.eng.tracedemo.service.OrderService.quote 407 µs
3
after: order O-200 priced at 12.50

The same service instance — created before any instrumentation — now traces. There is one non-obvious line: InitializationStrategy.NoOp.INSTANCE. Without it, the retransformation fails with class redefinition failed: attempted to add a method. The dump (Byte Buddy writes generated classes to disk with -Dnet.bytebuddy.dump=/path) shows why: the default initialization strategy adds a <clinit> to the transformed class that calls net.bytebuddy.dynamic.Nexus.initialize(...) — Byte Buddy’s mechanism for registering initialization callbacks on classes living in loaders it does not control. A class initializer counts as a method, and retransformation may not add methods. NoOp drops the hook; our advice needs no auxiliary types, so nothing is lost.

This is the general shape of retransformation bugs: not the advice (it inlines cleanly), but everything around it — initializers, auxiliary types, delegation plumbing — that must fit the JVM’s “same schema” rule.

How the pieces compose

The pipeline has four independent knobs, and every stage above moved exactly one of them:

• Matchers select what to change (.ignore, .type, .advice(matcher, ...)) — they run per discovered class and are evaluated on TypeDescriptions, without loading the target class.
• Implementation defines the change itself — MethodDelegation (dispatch to an interceptor) or Advice (inline into the method body).
• AgentBuilder defines when — at load time via the ClassFileTransformer, or retroactively via retransformation.
• Class-loading strategy defines where the result lives — WRAPPER/INJECTION for generated classes, or the existing loader for transformed ones.

Decision guide

What this is not yet

This is a working tracer, not an observability framework. Before attaching it to anything you care about:

• Filter aggressively. isPublic() on a package prefix is a scalpel; a sink of per-method lines on a hot path is a firehose. Match on annotations (@Timed-style markers) or explicit class lists.
• Measure the overhead. Every traced call pays for nanoTime twice, a ThreadLocal read, string concatenation, and printf — the I/O dwarfs the instrumentation. Benchmark with JMH under representative load before declaring it cheap, and batch records to a sink rather than printing per call.
• Never trace arguments blindly. @AllArguments is where credentials, PII, and payloads live; this is exactly how secrets end up in log aggregators.
• Decide your failure mode. Should a tracer exception kill the business call? suppress = Throwable.class says no — and then instrumentation failures are silent, which is its own incident.
• Mind the correlation context. A ThreadLocal dies at the first thread hop; async and reactive paths need propagation machinery.

Troubleshooting

What you built

One small TraceRecorder, three delivery mechanisms. The subclass proved the interception model — matchers select methods, generated overrides dispatch to an interceptor, self-calls through this are caught, and existing instances are unreachable. MethodDelegation exposed the binding machinery and its costs. Advice inlined the same behavior into the method body, which is what made the premain agent — and then retransformation of a loaded class — possible without adding a single member to the target.

The combination is the point: matchers scope, advice inlines, the agent installs, and the class-loading strategy decides which objects ever see the result. Everything else — filtering, sinks, propagation, overhead budgets — is production work on top of a mechanism you can now predict.

Further reading: the Byte Buddy tutorial and javadoc cover the full annotation surface (@This, @DefaultCall, @Morph, MethodCall), and the java.lang.instrument specification documents exactly what premain, agentmain, and retransformation guarantee.