Class IndyBootstrap
- java.lang.Object
-
- co.elastic.apm.agent.bci.IndyBootstrap
-
public class IndyBootstrap extends java.lang.ObjectWhenTracerAwareInstrumentation.indyPlugin()returnstrue, we instruct Byte Buddy (viaAdvice.WithCustomMapping.bootstrap(java.lang.reflect.Method)) to dispatch non-inlined advices via an invokedynamic (indy) instruction. The target method is linked to a dynamically created plugin class loader that is specific to an instrumentation plugin and the class loader of the instrumented method.The first invocation of an
INVOKEDYNAMICcauses the JVM to dynamically link aCallSite. In this case, it will use thebootstrap(java.lang.invoke.MethodHandles.Lookup, java.lang.String, java.lang.invoke.MethodType, java.lang.Object...)method to do that. This will also create the plugin class loader.Bootstrap CL ←──────────────────────────── Agent CL ↑ └java.lang.IndyBootstrapDispatcher ─ ↑ ─→ └bootstrap(java.lang.invoke.MethodHandles.Lookup, java.lang.String, java.lang.invoke.MethodType, java.lang.Object...)Ext/Platform CL ↑ │ ╷ ↑ ╷ │ ↓ System CL ╷ │IndyPluginClassLoaderFactory.getOrCreatePluginClassLoader(java.lang.ClassLoader, java.util.List<java.lang.String>, java.lang.ClassLoader, net.bytebuddy.dynamic.ClassFileLocator, net.bytebuddy.matcher.ElementMatcher<? super net.bytebuddy.description.type.TypeDescription>)↑ ╷ │ ╷ Common linking of CallSiteExternalPluginClassLoader↑ ↑ (on first invocation) ↑ ├ AdviceClass ╷ WebApp1 WebApp2 ╷ │ ├ AdviceHelper creates ↑ - InstrumentedClass ╷ │ ├ GlobalState ╷ │ ╷ ╷ │ └ LookupExposer ╷ │ INVOKEDYNAMIC │ ↓ └────────────────┼──────────────────IndyPluginClassLoader└╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶→ ├ AdviceClass ├ AdviceHelper └ LookupExposer Legend: ╶╶→ method calls ──→ class loader parent/child relationshipsAdvantages:
-
OSGi class loaders
can't interfere with class loading.
Instrumented classes only need to see java.lang.IndyBootstrapDispatcher.
The actual advice class is invoked via
INVOKEDYNAMICinstruction, basically a dynamically looked upMethodHandle. -
Performance:
As the target
MethodHandleis not changed after the initial lookup (we return aConstantCallSitefrombootstrap(java.lang.invoke.MethodHandles.Lookup, java.lang.String, java.lang.invoke.MethodType, java.lang.Object...)), the JIT can easily inline the advice into the instrumented method. -
Runtime attachment
This approach circumvents any OSGi issues even when attaching the agent at runtime.
Setting the
org.osgi.framework.bootdelegationproperty after the OSGi class loaders have already initialized has no effect. This is also a more holistic solution that also works for non-OSGi filtering class loaders. -
Runtime detachment:
After un-instrumenting classes (
ElasticApmAgent.reset()) and stopping all agent threads there should be no references to any Plugin CL or the Agent CL. This means the GC should be able to completely remove all loaded classes and class loaders of the agent, except forjava.lang.IndyBootstrapDispatcher. This can be useful to completely remove/detach the agent at runtime or to update the agent version without restarting the application. - Class visibility: The plugins can access both the specific types of the library they access and the agent classes as the Plugin CL has both the Agent CL and the CL of the instrumented class as its parent. Again, OSGi class loaders can't interfere here as both the Plugin CL and the Agent CL are under full control of the agent.
- Debugging advices: Advice classes can easily be debugged as they are not inlined in the instrumented methods.
- Unit testing: Classes loaded from the bootstrap class loader can be instrumented in unit tests.
- No shading: When loading the agent in an isolated class loader, we don't have to shade every dependency anymore. This makes packaging, source jar generation, and instrumenting shaded dependencies such as log4j2 much easier.
Challenges:
-
As we're working with
INVOKEDYNAMICinstructions that have only been introduced in Java 7, we have to patch classes we instrument that are compiled with Java 6 bytecode level (50) to Java 7 bytecode level (51). This involves re-computing stack frames and removing JSR instructions. See alsoElasticApmAgent.applyAdvice(co.elastic.apm.agent.impl.ElasticApmTracer, net.bytebuddy.agent.builder.AgentBuilder, co.elastic.apm.agent.sdk.ElasticApmInstrumentation, net.bytebuddy.matcher.ElementMatcher<? super net.bytebuddy.description.type.TypeDescription>). This makes instrumentation a bit slower but it seems to work reliably, even when re-transforming classes (important for runtime attachment). -
The
INVOKEDYNAMICsupport of early Java 7 versions is not reliable. That's why we disable the agent on them. See alsoJavaVersionBootstrapCheck -
There are some things to watch out for when writing plugins,
as explained in
TracerAwareInstrumentation.indyPlugin()
- See Also:
TracerAwareInstrumentation.indyPlugin()
-
OSGi class loaders
can't interfere with class loading.
Instrumented classes only need to see java.lang.IndyBootstrapDispatcher.
The actual advice class is invoked via
-
-
Field Summary
Fields Modifier and Type Field Description static java.lang.StringLOOKUP_EXPOSER_CLASS_NAMEThe name of the class we use as the lookup class during the invokedynamic bootstrap flow.
-
Constructor Summary
Constructors Constructor Description IndyBootstrap()
-
Method Summary
All Methods Static Methods Concrete Methods Modifier and Type Method Description static java.lang.invoke.ConstantCallSitebootstrap(java.lang.invoke.MethodHandles.Lookup lookup, java.lang.String adviceMethodName, java.lang.invoke.MethodType adviceMethodType, java.lang.Object... args)Is called byjava.lang.IndyBootstrapDispatcher#bootstrapvia reflection.static java.lang.reflect.MethodgetIndyBootstrapMethod(org.slf4j.Logger logger)
-
-
-
Field Detail
-
LOOKUP_EXPOSER_CLASS_NAME
public static final java.lang.String LOOKUP_EXPOSER_CLASS_NAME
The name of the class we use as the lookup class during the invokedynamic bootstrap flow. The bytecode of this class is injected into the plugin class loader, then loaded from that class loader and used as the lookup class to link the instrumented call site to the advice method.- See Also:
- Constant Field Values
-
-
Method Detail
-
getIndyBootstrapMethod
public static java.lang.reflect.Method getIndyBootstrapMethod(org.slf4j.Logger logger)
-
bootstrap
@Nullable public static java.lang.invoke.ConstantCallSite bootstrap(java.lang.invoke.MethodHandles.Lookup lookup, java.lang.String adviceMethodName, java.lang.invoke.MethodType adviceMethodType, java.lang.Object... args)Is called byjava.lang.IndyBootstrapDispatcher#bootstrapvia reflection.This is to make it impossible for OSGi or other filtering class loaders to restrict access to classes in the bootstrap class loader. Normally, additional classes that have been injected have to be explicitly allowed via the
org.osgi.framework.bootdelegationsystem property. But because we inject our class directly in thejava.langpackage which has to be on the allow list of filtering class loaders we can be sure that any other class can always call that class.This method gets called the first time an instrumented method is called. On instrumentation an
invokedynamicinstruction is inserted that delays the linking to the target method until runtime. The linking to the target method is done in this method.If not already created, the lookup of the target method creates a dedicated class loader for the classes in the plugin that has instrumented the
instrumentedType. Via package scanning it finds all the classes that are in the package of the advice that was responsible for the instrumentation. It then links to the advice loaded from the plugin class loader. The advice can access both agent types and the types of the instrumented library.Exceptions and
This is how a bootstrap method looks like in the class file:nullreturn values are handled byjava.lang.IndyBootstrapDispatcher#bootstrap.BootstrapMethods: 1: #1060 REF_invokeStatic java/lang/IndyBootstrapDispatcher.bootstrap:(Ljava/lang/invoke/MethodHandles$Lookup;Ljava/lang/String;Ljava/lang/invoke/MethodType;[Ljava/lang/Object;)Ljava/lang/invoke/CallSite; Method arguments: #1049 co.elastic.apm.agent.bci.InstrumentationTest$CommonsLangInstrumentation #1050 0 #12 org/apache/commons/lang3/StringUtils #1072 isNotEmpty #1075 REF_invokeStatic org/apache/commons/lang3/StringUtils.isNotEmpty:(Ljava/lang/CharSequence;)ZAnd this is how a invokedynamic instruction looks like inside methods, referencing above bootstrap methodinvokedynamic #1076, 0 // InvokeDynamic #1:onEnter:()V- Parameters:
lookup- Ajava.lang.invoke.MethodHandles.Lookuprepresenting the instrumented method.adviceMethodName- AStringrepresenting the advice method name.adviceMethodType- AMethodTyperepresenting the arguments and return type of the advice method.args- Additional arguments that are provided by Byte Buddy:- A
Stringof the binary target class name. - A
intwith value0for an enter advice and {code 1} for an exist advice. - A
Classrepresenting the class implementing the instrumented method. - A
Stringwith the name of the instrumented method. - A
MethodHandlerepresenting the instrumented method unless the target is the type's static initializer.
- A
- Returns:
- a
ConstantCallSitethat is the target of the invokedynamic
-
-