What is a Java Agent, how does it instrument bytecode at load time, and what tools are built on it?

package com.bank.agent;

import java.lang.instrument.Instrumentation;

public class BankTimingAgent {

    // Called before the application's main method
    public static void premain(
            String agentArgs, Instrumentation inst) {
        System.out.println("Bank Timing Agent loaded");
        inst.addTransformer(new TransferTimingTransformer());
    }
}

# MANIFEST.MF for startup agent
Premain-Class: com.bank.agent.BankTimingAgent
Can-Retransform-Classes: true

# MANIFEST.MF for dynamic agent
Agent-Class: com.bank.agent.BankTimingAgent
Can-Retransform-Classes: true

# Startup attachment
java -javaagent:bank-timing-agent.jar=verbose \
     -jar bank-transfer-service.jar

# Dynamic attachment to running JVM (PID 12345)
# Using the Attach API programmatically

package com.bank.agent;

import java.lang.instrument.Instrumentation;

public class BankTimingAgent {

    // Startup: called before main
    public static void premain(
            String agentArgs, Instrumentation inst) {
        System.out.println("Startup agent: " + agentArgs);
        inst.addTransformer(
            new TransferTimingTransformer(), true);
    }

    // Dynamic: called when attached to running JVM
    public static void agentmain(
            String agentArgs, Instrumentation inst) {
        System.out.println("Dynamic agent: " + agentArgs);
        inst.addTransformer(
            new TransferTimingTransformer(), true);
        // Re-instrument already-loaded classes
        try {
            for (Class<?> cls : inst.getAllLoadedClasses()) {
                if (cls.getName().startsWith("com.bank")) {
                    inst.retransformClasses(cls);
                }
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

package com.bank.agent;

import java.lang.instrument.ClassFileTransformer;
import java.security.ProtectionDomain;

public class TransferTimingTransformer
        implements ClassFileTransformer {

    @Override
    public byte[] transform(
            ClassLoader loader,
            String className,
            Class<?> classBeingRedefined,
            ProtectionDomain protectionDomain,
            byte[] classfileBuffer) {

        // Only instrument bank service classes
        if (className == null
                || !className.startsWith("com/bank/service")) {
            return null; // Leave unchanged
        }

        System.out.println("Instrumenting: " + className);

        // Use ByteBuddy or ASM to modify classfileBuffer
        // and return modified bytes
        return instrumentWithTiming(classfileBuffer);
    }

    private byte[] instrumentWithTiming(byte[] original) {
        // In practice, use ByteBuddy or ASM here
        // to add timing probes at method entry/exit
        return original; // Simplified
    }
}

package com.bank.agent;

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

public class ByteBuddyTimingAgent {

    public static void premain(
            String args, Instrumentation inst) {
        new AgentBuilder.Default()
            .type(ElementMatchers.nameStartsWith("com.bank.service"))
            .transform((builder, type, classLoader, module, domain) ->
                builder.method(ElementMatchers.any())
                    .intercept(Advice.to(TimingAdvice.class))
            )
            .installOn(inst);
    }

    public static class TimingAdvice {

        @Advice.OnMethodEnter
        static long enter() {
            return System.nanoTime();
        }

        @Advice.OnMethodExit
        static void exit(
                @Advice.Enter long startTime,
                @Advice.Origin String method) {
            long elapsed = System.nanoTime() - startTime;
            if (elapsed > 1_000_000) { // > 1ms
                System.out.println(method + " took "
                    + elapsed / 1_000_000 + "ms");
            }
        }
    }
}

// After dynamic attachment, re-instrument TransferService
inst.retransformClasses(
    Class.forName("com.bank.service.TransferService")
);
// The transformer's transform() is called again
// for this class, even though it was already loaded

// WRONG: instrumenting everything including JDK classes
public byte[] transform(...) {
    return instrumentWithTiming(classfileBuffer); // Dangerous!
}

// CORRECT: filter to application classes only
public byte[] transform(...) {
    if (className == null
            || !className.startsWith("com/bank/")) {
        return null; // Leave JDK classes untouched
    }
    return instrumentWithTiming(classfileBuffer);
}