Package io.opentelemetry.javaagent.extension.instrumentation

Class InstrumentationModule

  • All Implemented Interfaces:
    Ordered
    public abstract class InstrumentationModule
extends Object
implements Ordered
    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.

    InstrumentationModule is an SPI, you need to ensure that a proper META-INF/services/ provider file is created for it to be picked up by the agent. See ServiceLoader for more details.

    • Constructor Detail

      • InstrumentationModule

        protected 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

      • isEnabled

        public final boolean isEnabled()
        Returns true if this instrumentation module should be installed.

      • defaultEnabled

        protected boolean defaultEnabled()
        Allows instrumentation modules to disable themselves by default, or to additionally disable themselves on some other condition.

      • isHelperClass

        public boolean isHelperClass​(String className)
        Instrumentation modules can override this method to specify additional packages (or classes) that should be treated as "library instrumentation" packages. Classes from those packages will be treated by muzzle as instrumentation helper classes: they will be scanned for references and automatically injected into the application classloader if they're used in any type instrumentation. The classes for which this predicate returns true will be treated as helper classes, in addition to the default ones defined in the HelperClassPredicate class.
        Parameters:
        className - The name of the class that may or may not be a helper class.

      • registerHelperResources

        public void registerHelperResources​(HelperResourceBuilder helperResourceBuilder)
        Register resource names to inject into the user's class loader.

      • 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.

      • getAdditionalHelperClassNames

        public List<String> getAdditionalHelperClassNames()
        Returns a list of additional instrumentation helper classes, which are not automatically detected during compile time.

        If your instrumentation module does not apply and you see warnings about missing classes in the logs, you may need to override this method and provide fully qualified classes names of helper classes that your instrumentation uses.

        These helper classes will be injected into the application classloader after automatically detected ones.