spring-instrument

Active contributors: Juergen Hoeller

Purpose

spring-instrument is a Java agent for class instrumentation. It exists to support load-time weaving (LTW) for AspectJ aspects defined in spring-aspects (and any user-supplied ClassFileTransformer). When attached at JVM startup, it makes the JDK's Instrumentation API available to Spring so that classes can be transformed as they are loaded.

Directory layout

spring-instrument/
└── src/main/java/org/springframework/instrument/
    ├── InstrumentationSavingAgent.java           # the agent's premain entrypoint
    └── ClassFileTransformer.java                 # placeholder type

The module ships two source files, making it among the smallest published Spring artifacts. Its JAR manifest declares Premain-Class and Agent-Class so Java recognizes it as an agent.

Key abstractions

Type	File	Role
InstrumentationSavingAgent	spring-instrument/src/main/java/org/springframework/instrument/InstrumentationSavingAgent.java	Captures Instrumentation instance for later retrieval

How it works

1. Start your JVM with -javaagent:spring-instrument-X.Y.Z.jar.
2. The JVM calls InstrumentationSavingAgent.premain(...) and hands it an Instrumentation reference.
3. The agent stores that reference in a static field.
4. Later, Spring's LoadTimeWeaver (part of spring-context) retrieves the reference and registers ClassFileTransformers for AspectJ, JPA enhancement, etc.

graph LR
    JVM_START["java -javaagent:spring-instrument.jar"] -->|"premain"| Agent[InstrumentationSavingAgent]
    Agent -->|"stores Instrumentation"| Static[Static reference]
    Static -->|"retrieved by"| LTW[InstrumentationLoadTimeWeaver]
    LTW -->|"addTransformer"| AspectJ[AspectJ ClassFileTransformer]
    AspectJ -->|"weaves @Transactional, @Async, …"| Classes[Loaded classes]

When you need this

• Load-time AspectJ weaving (@EnableLoadTimeWeaving, META-INF/aop.xml).
• JPA bytecode enhancement that requires the JPA LoadTimeWeaver SPI.
• Custom ClassFileTransformers that need to run early.

If you're not using LTW, you don't need this agent. Most applications don't.

Integration points

• Used by spring-context's InstrumentationLoadTimeWeaver.
• Companion to spring-aspects (whose aspects are commonly load-time-woven).

See also

• spring-aspects — what gets woven
• features/aop