Who instruments the instrumenters?

1. Who Instruments the Instrumenters? Johannes Bechberger (SAP SE)
2. Code Instrumentation?
3. transform Code Instrumentation?
4. methodA(); log();sdfs methodA(); transform Code Instrumentation?
5. Executed Bytecode transform Bytecode In the JVM compile Code Instrumentation?
6. Executed Bytecode transform Bytecode In the JVM compile Code Instrumentation?
7. Why do we need it? Code Instrumentation?
8. Code Coverage
9. Code Coverage public class DiscountCalculator { public int calculateDiscount(int price, boolean isMember) { if (price > 100) { return isMember ? 20 : 10; } return isMember ? 5 : 0; } }
10. Code Coverage class DiscountCalculatorTest { @Test void calculateDiscount() { DiscountCalculator calc = new DiscountCalculator(); assertEquals(0, calc.calculateDiscount(50, false)); assertEquals(5, calc.calculateDiscount(50, true)); } }
11. Code Coverage public class DiscountCalculator { public int calculateDiscount(int price, boolean isMember) { if (price > 100) { return isMember ? 20 : 10; } return isMember ? 5 : 0; } } executed in the tests?
12. Code Coverage public class DiscountCalculator { public int calculateDiscount(int price, boolean isMember) { if (price > 100) { return isMember ? 20 : 10; } return isMember ? 5 : 0; } } log(…) log(…) log(…)
13. Code Coverage
14. Code Coverage
15. Testing @Mock List<String> mockedList; @Test public void testList() { mockedList.add("one"); Mockito.verify(mockedList).add("one"); }
16. Monitoring
17. Monitoring
18. Other Use Cases
19. Profiling void method() { !// do something }
20. Profiling void method() { logEntry("method"); !// do something logExit("method"); } void method() { !// do something }
21. Debugging
22. Debugging public class DiscountCalculator { public int calculateDiscount(int price, boolean isMember) { if (price > 100) { return isMember ? 20 : 10; } return isMember ? 5 : 0; } }
23. Debugging public class DiscountCalculator { public int calculateDiscount(int price, boolean isMember) { if (price > 100) { return isMember ? 20 : 10; } return isMember ? 5 : 0; } } dbg() dgb() dbg()
24. Debugging public class DiscountCalculator { public int calculateDiscount(int price, boolean isMember) { if (price > 100) { return isMember ? 20 : 10; } return isMember ? 5 : 0; } } dbg() dgb() dbg() Not in Java
25. Debugging public class DiscountCalculator { public int calculateDiscount(int price, boolean isMember) { if (price > 100) { return isMember ? 20 : 10; } return isMember ? 5 : 0; } } dbg() dgb() dbg() But in Python* https://mostlynerdless.de/blog/tag/lets-create-a-debugger-together/
26. sapmachine.io
27. How does Instrumentation work?
28. JVM Agent -javaattach:agent.jar=args
29. Can add Transformers Executed Bytecode transform Bytecode In the JVM compile
30. Example public class DiscountCalculator { public int calculateDiscount(int price, boolean isMember) { if (price > 100) { return isMember ? 20 : 10; } return isMember ? 5 : 0; } }
31. Example public class Main { public static void main(String[] args) { DiscountCalculator calculator = new DiscountCalculator(); use(calculator.calculateDiscount(150, true)); } }
32. Example public class Main { public static void main(String[] args) { DiscountCalculator calculator = new DiscountCalculator(); System.out.println("cd(" + 150 + ", " + true + ")"); use(calculator.calculateDiscount(150, true)); } }
33. public class AgentMain { public static void premain(String agentArgs, Instrumentation inst) { inst.addTransformer(new DiscountTransformer()); } } -javaattach:agent.jar=args
34. DiscountTransformer extends ClassFileTransformer “ An agent registers an implementation of this interface using the addTransformer method so that the transformer’s transform method is invoked when classes are loaded, redefined, or retransformed – ClassFileTransformer Documentation
35. ClassFileTransformer#transform byte[] transform( ClassLoader loader, String className, Class<?> klass, ProtectionDomain domain, byte[] classfileBuffer) throws IllegalClassFormatException { ... }
36. https://www.javassist.org/
37. class DiscountTransformer implements ClassFileTransformer { private final ScopedClassPoolFactoryImpl scopedClassPoolFactory = new ScopedClassPoolFactoryImpl(); @Override public byte[] transform(!!...) { ClassPool cp = scopedClassPoolFactory.create(loader, …); CtClass cc = cp.makeClass(new ByteArrayInputStream(buffer)); transform(cc); return cc.toBytecode(); }
38. class DiscountTransformer implements ClassFileTransformer { private void transform(CtClass cc){ var exprEditor = new DiscountEditor(); !// !!... for (CtMethod method : cc.getDeclaredMethods()) { method.instrument(exprEditor); } } }
39. class DiscountTransformer implements ClassFileTransformer { private void transform(CtClass cc){ var exprEditor = new DiscountEditor(); cc.instrument(exprEditor); } }
40. Class Transformer class DiscountEditor extends ExprEditor { @Override public void edit(MethodCall m) { if (isCalculateDiscountMethod(m)) { m.replace(""" { System.out.println("cd(" + $1 + ", " + $2 + ")"); $_ = $proceed($$); } """); } } }
41. Back to the Use Cases
42. Code Coverage
43. Code Coverage
44. Code Coverage
45. Quis custodiet ipsos custodes? - Juvenal
46. Who watches the watchmen? - Juvenal
47. Who instruments the instrumenters?
48. Meta-Agent https://github.com/parttimenerd/meta-agent Idea by Mikaël Francoeur
49. inst.addTransformer(…) InstrumentationHandler.addTransformer(…) https://github.com/parttimenerd/meta-agent/blob/main/src/main/java/me/bechberger/meta/ClassTransformer.java
50. InstrumentationHandler.addTransformer(…) public static void addTransformer( Instrumentation inst, ClassFileTransformer trans, boolean canRetransform) { !// !!... inst.addTransformer( new ClassFileTransformer() { @Override public byte[] transform(!!...) { byte[] old = classfileBuffer.clone(); byte[] current = transformer.transform(!!...); addDiff(transformer, old, current); return current; } }, canRetransform ) } https://github.com/parttimenerd/meta-agent/blob/main/src/main/java/me/bechberger/meta/runtime/InstrumentationHandler.java
51. InstrumentationHandler.addTransformer(…) public static void addTransformer( Instrumentation inst, ClassFileTransformer trans, boolean canRetransform) { !// !!... inst.addTransformer( new ClassFileTransformer() { @Override public byte[] transform(!!...) { byte[] old = classfileBuffer.clone(); byte[] current = transformer.transform(!!...); addDiff(transformer, old, current); return current; } }, canRetransform ) } https://github.com/parttimenerd/meta-agent/blob/main/src/main/java/me/bechberger/meta/runtime/InstrumentationHandler.java
52. Bytecode decompile
53. http://localhost:7071
54. http://localhost:7071/classes
55. public class DiscountCalculator { public int calculateDiscount(int price, boolean isMember) { if (price > 100) { return isMember ? 20 : 10; } return isMember ? 5 : 0; } }
57. Helps to understand your tools
58. Helps to understand your tools As JaCoCo works on byte code level also constructors and static initializers are counted as methods. Some of these methods may not have a direct correspondence in Java source code, like implicit and thus generated default constructors or initializers for constants. “ https://www.jacoco.org/jacoco/trunk/doc/counters.html
60. http://localhost:7071/full-diff/class?pattern=org.example.DiscountCalculator
63. Decompilation gives us only an educated guess
64. http://localhost:7071/all/decompile?pattern=java.lang.$JaCoCo http://localhost:7071/full-diff/class?pattern=org.example.DiscountCalculator
65. http://localhost:7071/all/decompile?pattern=java.lang.$JaCoCo http://localhost:7071/full-diff/class?pattern=org.example.DiscountCalculator
66. Object.equals(...) The equals method implements an equivalence relation on non-null object references: • It is reflexive • It is symmetric • It is transitive • It is consistent https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html#equals-java.lang.Object-
67. Object.equals(...) The equals method implements an equivalence relation on non-null object references: • It is reflexive • It is symmetric • It is transitive • It is consistent https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html#equals-java.lang.Object-
68. Making a runtime library available to all instrumented classes can be a painful or impossible task in frameworks that use their own class loading mechanisms. […] As our minimum target is Java 1.5 JaCoCo decouples the instrumented classes and the coverage runtime through official JRE API types only. The instrumented classes communicate through the Object.equals(Object) method with the runtime. A instrumented class can retrieve its probe array instance with the following code. JaCoCo – Implementation Design https://www.jacoco.org/jacoco/trunk/doc/implementation.html “
69. !!/** * Container for runtime execution and meta data. All access to the runtime data * is thread safe. !*/ public class RuntimeData { !/* !!... !*/ !!/** * In violation of the regular semantic of {@link Object#equals(Object)} * this implementation is used as the interface to the execution data store. * * @param args * the arguments as an {@link Object} array * @return has no meaning !*/ @Override public boolean equals(final Object args) { if (args instanceof Object[]) { getProbes((Object[]) args); } return super.equals(args); } !/* !!... !*/ https://github.com/jacoco/jacoco/blob/f0dcc6b0b78b04dd94617707551f6c2d18426d09/org.jacoco.core/src/org/jacoco/core/runtime/RuntimeData.java
70. Code Coverage
72. Testing @Mock List<String> mockedList; @Test public void testList() { mockedList.add("one"); Mockito.verify(mockedList).add("one"); }
73. @Mock List<String> mockedList; @Test public void testList() { mockedList.add("one"); Mockito.verify(mockedList).add("one"); }
74. interface Iterable { !// !!... default void forEach(Consumer<? super T> action) { Objects.requireNonNull(action); for (T element : this) { action.accept(element); } } }
75. interface Iterable { !// !!... default void forEach(Consumer<? super T> action) { MockMethodDispatcher mmd = MockMethodDispatcher.get("q9Lk1TRa", this); Callable handleForEach = mmd !!= null !&& mmd.isMocked(this) !&& !mmd.isOverridden(this, Iterable.class.getMethod("forEach", Consumer.class)) ? mmd.handle(this, Iterable.class.getMethod("forEach", Consumer.class), new Object[]{action}) : null; if (handleForEach !== null) { Objects.requireNonNull(action); for (T t : this) { action.accept(t); } } if (handleForEach !!= null) { handleForEach.call(); } } }
76. interface Iterable { !// !!... default void forEach(Consumer<? super T> action) { MockMethodDispatcher mmd = MockMethodDispatcher.get("q9Lk1TRa", this); Callable handleForEach = mmd !!= null !&& mmd.isMocked(this) !&& !mmd.isOverridden(this, Iterable.class.getMethod("forEach", Consumer.class)) ? mmd.handle(this, Iterable.class.getMethod("forEach", Consumer.class), new Object[]{action}) : null; if (handleForEach !== null) { Objects.requireNonNull(action); for (T t : this) { action.accept(t); } } if (handleForEach !!= null) { handleForEach.call(); } } }
77. interface Iterable { !// !!... default void forEach(Consumer<? super T> action) { MockMethodDispatcher mmd = MockMethodDispatcher.get("q9Lk1TRa", this); Callable handleForEach = mmd !!= null !&& mmd.isMocked(this) !&& !mmd.isOverridden(this, Iterable.class.getMethod("forEach", Consumer.class)) ? mmd.handle(this, Iterable.class.getMethod("forEach", Consumer.class), new Object[]{action}) : null; if (handleForEach !== null) { Objects.requireNonNull(action); for (T t : this) { action.accept(t); } } if (handleForEach !!= null) { handleForEach.call(); } } }
78. interface Iterable { !// !!... default void forEach(Consumer<? super T> action) { MockMethodDispatcher mmd = MockMethodDispatcher.get("q9Lk1TRa", this); Callable handleForEach = mmd !!= null !&& mmd.isMocked(this) !&& !mmd.isOverridden(this, Iterable.class.getMethod("forEach", Consumer.class)) ? mmd.handle(this, Iterable.class.getMethod("forEach", Consumer.class), new Object[]{action}) : null; if (handleForEach !== null) { Objects.requireNonNull(action); for (T t : this) { action.accept(t); } } if (handleForEach !!= null) { handleForEach.call(); } } }
79. interface Iterable { !// !!... default void forEach(Consumer<? super T> action) { MockMethodDispatcher mmd = MockMethodDispatcher.get("q9Lk1TRa", this); Callable handleForEach = mmd !!= null !&& mmd.isMocked(this) !&& !mmd.isOverridden(this, Iterable.class.getMethod("forEach", Consumer.class)) ? mmd.handle(this, Iterable.class.getMethod("forEach", Consumer.class), new Object[]{action}) : null; if (handleForEach !== null) { Objects.requireNonNull(action); for (T t : this) { action.accept(t); } } if (handleForEach !!= null) { handleForEach.call(); } } }
80. interface Iterable { !// !!... default void forEach(Consumer<? super T> action) { MockMethodDispatcher mmd = MockMethodDispatcher.get("q9Lk1TRa", this); Callable handleForEach = mmd !!= null !&& mmd.isMocked(this) !&& !mmd.isOverridden(this, Iterable.class.getMethod("forEach", Consumer.class)) ? mmd.handle(this, Iterable.class.getMethod("forEach", Consumer.class), new Object[]{action}) : null; if (handleForEach !== null) { Objects.requireNonNull(action); for (T t : this) { action.accept(t); } } if (handleForEach !!= null) { handleForEach.call(); } } }
81. But where is the List implementation? @Mock List<String> mockedList; @Test public void testList() { mockedList.add("one"); Mockito.verify(mockedList).add("one"); }
82. IDE to the Rescue
83. http://localhost:7071/all/decompile?pattern=org.mockito.codegen.List$MockitoMock$iBo7tFTz public class List$MockitoMock$iBo7tFTz implements List, MockAccess { private static final long serialVersionUID = 42L; private MockMethodInterceptor mockitoInterceptor; !// !!... !// $VF: synthetic field private static final Method cachedValue$46t0jdUa$sgg2351 = List.class.getMethod("add", Object.class); !// !!... @Override public boolean add(Object var1) { return (Boolean)DispatcherDefaultingToRealMethod .interceptAbstract(this, this.mockitoInterceptor, false, cachedValue$46t0jdUa$sgg2351, new Object[]{var1}); } public void setMockitoInterceptor(MockMethodInterceptor var1) { this.mockitoInterceptor = var1; } !// !!... }
84. http://localhost:7071/all/decompile?pattern=org.mockito.codegen.List$MockitoMock$iBo7tFTz public class List$MockitoMock$iBo7tFTz implements List, MockAccess { private static final long serialVersionUID = 42L; private MockMethodInterceptor mockitoInterceptor; !// !!... !// $VF: synthetic field private static final Method cachedValue$46t0jdUa$sgg2351 = List.class.getMethod("add", Object.class); !// !!... @Override public boolean add(Object var1) { return (Boolean)DispatcherDefaultingToRealMethod .interceptAbstract(this, this.mockitoInterceptor, false, cachedValue$46t0jdUa$sgg2351, new Object[]{var1}); } public void setMockitoInterceptor(MockMethodInterceptor var1) { this.mockitoInterceptor = var1; } !// !!... }
85. Implementation public interface Instrumentation { !!/** * Returns an array of all classes currently loaded !*/ @SuppressWarnings("rawtypes") Class[] getAllLoadedClasses(); Based on: https://github.com/openjdk/jdk/blob/bc5cde1b198baf6e2e36d370b0aaa907c8f35777/src/java.instrument/share/classes/java/lang/instrument/Instrumentation.java#L74
86. Live Demo
88. View Annotation Classes
89. @AnnotationTest.Annotation(key = "key", value = "value") public class AnnotationTest { @Retention(RetentionPolicy.RUNTIME) @interface Annotation { String key(); String value(); } @Test public void testAnnotation() throws InterruptedException { Annotation annotation = AnnotationTest.class.getAnnotation(Annotation.class); System.out.println(annotation.key()); System.out.println(annotation.value()); Thread.sleep(1000000); } }
90. @AnnotationTest.Annotation(key = "key", value = "value") public class AnnotationTest { @Retention(RetentionPolicy.RUNTIME) @interface Annotation { String key(); String value(); } @Test public void testAnnotation() throws InterruptedException { Annotation annotation = AnnotationTest.class.getAnnotation(Annotation.class); System.out.println(annotation.key()); System.out.println(annotation.value()); Thread.sleep(1000000); } }
91. @AnnotationTest.Annotation(key = "key", value = "value") public class AnnotationTest { @Retention(RetentionPolicy.RUNTIME) @interface Annotation { String key(); String value(); } @Test public void testAnnotation() throws InterruptedException { Annotation annotation = AnnotationTest.class.getAnnotation(Annotation.class); System.out.println(annotation.key()); System.out.println(annotation.value()); Thread.sleep(1000000); } } Type of this object?
92. IDE to the Rescue
94. public final class $Proxy7 extends Proxy implements Annotation { private static final Method hashCodeMethod; !// !!... public $Proxy7(InvocationHandler handler) { super(handler); } @Override public final int hashCode() { try { return (Integer) super.h.invoke(this, hashCodeMethod, null); } catch (RuntimeException | Error e) { throw e; } catch (Throwable t) { throw new UndeclaredThrowableException(t); } }
95. Objects are created by the Annotation Parser public static Annotation annotationForMap(final Class<? extends Annotation> type, final Map<String, Object> memberValues) { return AccessController.doPrivileged(new PrivilegedAction<Annotation>() { public Annotation run() { return (Annotation) Proxy.newProxyInstance( type.getClassLoader(), new Class<?>[] { type }, new AnnotationInvocationHandler(type, memberValues)); !}}); } Source: https://github.com/openjdk/jdk/blob/bc5cde1b198baf6e2e36d370b0aaa907c8f35777/src/java.base/share/classes/sun/reflect/annotation/AnnotationParser.java
96. Pitfalls for Instrumenters
97. Class Loader Hierarchies platform app bootstrap X Y class reference delegates to
98. Class Loader Hierarchies platform app bootstrap X Y class reference delegates to
99. Class Loader Hierarchies platform app bootstrap X Y class reference delegates to searches in runtime.jar https://mostlynerdless.de/blog/2023/06/02/class-loader-hierarchies/
100. Implementation public interface Instrumentation { void appendToBootstrapClassLoaderSearch( JarFile jarfile); Based on: https://github.com/openjdk/jdk/blob/bc5cde1b198baf6e2e36d370b0aaa907c8f35777/src/java.instrument/share/classes/java/lang/instrument/Instrumentation.java#L74
101. Load runtime classes only after adding them to the bootclasspath!
102. Meta-Agent Maven Plugin https://mostlynerdless.de/blog/2025/03/11/ who-instruments-the-instrumenters-and-has-a-runtime-handler/
103. public class PreventingInstrumentationHandler implements InstrumentationCallback { @Override public CallbackAction onAddTransformer( ClassFileTransformer transformer) { System.err.println("Preventing " + transformer.getClass().getName()); return CallbackAction.IGNORE; } }
104. public class PreventingInstrumentationHandler implements InstrumentationCallback { @Override public CallbackAction onAddTransformer( ClassFileTransformer transformer) { System.err.println("Preventing " + transformer.getClass().getName()); return CallbackAction.IGNORE; } }
105. <plugin> <groupId>me.bechberger!</groupId> <artifactId>meta-agent-maven-plugin!</artifactId> <version>0.0.3!</version> <executions> <execution> <phase>validate!</phase> <goals> <goal>meta-agent!</goal> !</goals> !</execution> !</executions> <configuration> <callbackClasses> <callbackClass>PreventingInstrumentationHandler!</callbackClass> !</callbackClasses> <server>true!</server> !</configuration> !</plugin>
106. timetableworld.com Johannes Bechberger mostlynerdless.de OpenJDK Developer, SAP Fin. https://github.com/parttimenerd/meta-agent sapmachine.io