Working with Instrumentation

1. Understanding Java Agent Basics

Concept	Detail
Agent	JAR with `Premain-Class` or `Agent-Class`
Premain	Loaded with `-javaagent:agent.jar` at startup
Agentmain	Attached at runtime via Attach API
Capability	Transform bytecode of loaded classes

2. Creating Java Agents

Example: Premain agent

public class TimingAgent {
    public static void premain(String args, Instrumentation inst) {
        inst.addTransformer(new TimingTransformer(), true);
    }
}

Manifest Attr	Use
Premain-Class	Startup agents
Agent-Class	Runtime-attached
Can-Retransform-Classes	true to retransform
Can-Redefine-Classes	true to redefine

3. Using Instrumentation API

Method	Use
`addTransformer(t[, canRetransform])`	Register transformer
`retransformClasses(c...)`	Re-apply transformers
`redefineClasses(defs...)`	Replace class bytes
`getAllLoadedClasses()`	Snapshot
`getObjectSize(obj)`	Shallow size

4. Transforming Classes (ClassFileTransformer)

Example: Transformer

class TimingTransformer implements ClassFileTransformer {
    public byte[] transform(ClassLoader cl, String name, Class<?> classBeingRedefined,
                            ProtectionDomain pd, byte[] classfileBuffer) {
        if (!name.startsWith("com/acme/")) return null;
        return rewrite(classfileBuffer);
    }
}

Return	Meaning
null	No change
byte[]	Replacement bytecode

5. Retransforming Classes

Aspect	Detail
Restriction	Cannot add/remove fields, methods, supers
Use	Modify method bodies after load
Trigger	`inst.retransformClasses(MyClass.class)`

6. Using Byte Buddy for Instrumentation

API	Use
`new ByteBuddy().subclass(...)`	Generate subclass
`AgentBuilder`	Fluent transformer DSL
`Advice`	Inject @OnMethodEnter/@OnMethodExit
Use	APM (New Relic, Datadog)

7. Using ASM Library

Component	Use
ClassReader	Parse bytecode
ClassWriter	Emit bytecode
ClassVisitor / MethodVisitor	Visitor pattern
Tree API	Higher-level node tree

8. Attaching Agents at Runtime

Example: Attach API

VirtualMachine vm = VirtualMachine.attach(pid);
vm.loadAgent("/path/agent.jar", "options");
vm.detach();

Aspect	Detail
Module	`jdk.attach`
Permission	Same UID; `-XX:+EnableDynamicAgentLoading` (Java 21+ warning)

9. Profiling with Agents

Tool	Mechanism
async-profiler	JVMTI + perf_events
YourKit / JProfiler	JVMTI agents
JFR	Built-in low-overhead
APM	Bytecode instrumentation via ByteBuddy

10. Understanding Security Implications

Warning: Agents can read/modify any code, including security-sensitive classes. Treat agent JARs as fully trusted code. From Java 21, dynamic agent loading triggers a warning; future releases may require -XX:+EnableDynamicAgentLoading.

Risk	Mitigation
Tampering	Sign agent JARs, verify provenance
Performance	Measure overhead per transformer
Stability	Test transformations against all class shapes

Related Cheat Sheets

Authentication Authorization