Package io.opentelemetry.javaagent.tooling

Class InstrumentationModule

  • public abstract class InstrumentationModule
extends Object
    Instrumentation module groups several connected TypeInstrumentations together, sharing classloader matcher, helper classes, muzzle safety checks, etc. Ideally all types in a single instrumented library should live in a single module.

    Classes extending InstrumentationModule should be public and non-final so that it's possible to extend and reuse them in vendor distributions.

    • Field Detail

      • NOT_DECORATOR_MATCHER

        public static final net.bytebuddy.matcher.ElementMatcher.Junction<net.bytebuddy.description.annotation.AnnotationSource> NOT_DECORATOR_MATCHER

    • Constructor Detail

      • InstrumentationModule

        public InstrumentationModule​(String mainInstrumentationName,
                             String... additionalInstrumentationNames)
        Creates an instrumentation module. Note that all implementations of InstrumentationModule must have a default constructor (for SPI), so they have to pass the instrumentation names to the super class constructor.

        The instrumentation names should follow several rules:

        • Instrumentation names should consist of hyphen-separated words, e.g. instrumented-library;
        • In general, instrumentation names should be the as close as possible to the gradle module name - which in turn should be as close as possible to the instrumented library name;
        • The main instrumentation name should be the same as the gradle module name, minus the version if it's a part of the module name. When several versions of a library are instrumented they should all share the same main instrumentation name so that it's easy to enable/disable the instrumentation regardless of the runtime library version;
        • If the gradle module has a version as a part of its name, an additional instrumentation name containing the version should be passed, e.g. instrumented-library-1.0.

    • Method Detail

      • instrument

        public final net.bytebuddy.agent.builder.AgentBuilder instrument​(net.bytebuddy.agent.builder.AgentBuilder parentAgentBuilder)
        Add this instrumentation to an AgentBuilder.
        Parameters:
        parentAgentBuilder - AgentBuilder to base instrumentation config off of.
        Returns:
        the original agentBuilder and this instrumentation

      • getAllHelperClassNames

        public final List<String> getAllHelperClassNames()
        Returns all helper classes that will be injected into the application classloader, both ones provided by the implementation and ones that were collected by muzzle during compilation.

      • getOrder

        public int getOrder()
        Order of adding instrumentation to ByteBuddy. For example instrumentation with order 1 runs after an instrumentation with order 0 (default) matched on the same API.
        Returns:
        the order of adding an instrumentation to ByteBuddy. Default value is 0 - no order.

      • helperResourceNames

        public String[] helperResourceNames()
        Returns resource names to inject into the user's classloader.

      • classLoaderMatcher

        public net.bytebuddy.matcher.ElementMatcher.Junction<ClassLoader> classLoaderMatcher()
        An instrumentation module can implement this method to make sure that the classloader contains the particular library version. It is useful to implement that if the muzzle check does not fail for versions out of the instrumentation's scope.

        E.g. supposing version 1.0 has class A, but it was removed in version 2.0; A is not used in the helper classes at all; this module is instrumenting 2.0: this method will return not(hasClassesNamed("A")).

        Returns:
        A type matcher used to match the classloader under transform

      • typeInstrumentations

        public abstract List<TypeInstrumentation> typeInstrumentations()
        Returns a list of all individual type instrumentation in this module.