Package io.opentelemetry.javaagent.extension.instrumentation

Class InstrumentationModule

java.lang.Object
io.opentelemetry.javaagent.extension.instrumentation.InstrumentationModule
All Implemented Interfaces:
io.opentelemetry.sdk.autoconfigure.spi.Ordered
Direct Known Subclasses:
V3PreviewFallbackEnabledInstrumentationModule
public abstract class InstrumentationModule extends Object implements io.opentelemetry.sdk.autoconfigure.spi.Ordered
Instrumentation module groups several connected TypeInstrumentations together, sharing class loader 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 Summary

    Constructors
    Modifier
    Constructor
    Description
    protected
    InstrumentationModule(String mainInstrumentationName, String... additionalInstrumentationNames)
    Creates an instrumentation module.

  • Method Summary

    Modifier and Type
    Method
    Description
    net.bytebuddy.matcher.ElementMatcher.Junction<ClassLoader>
    classLoaderMatcher()
    An instrumentation module can implement this method to make sure that the class loader contains the particular library version.
    boolean
    defaultEnabled()
    Allows instrumentation modules to disable themselves by default, or to additionally disable themselves on some other condition.
    boolean
    defaultEnabled(io.opentelemetry.sdk.autoconfigure.spi.ConfigProperties config)
    Allows instrumentation modules to disable themselves by default, or to additionally disable themselves on some other condition.
    List<String>
    exposedClassNames()
    Returns a list of instrumentation helper class names that must be visible to the application class loader while remaining loaded by an isolated instrumentation module class loader.
    List<String>
    getAdditionalHelperClassNames()
    Returns a list of additional instrumentation helper classes, which are not automatically detected during compile time.
    List<String>
    injectedClassNames()
    Returns a list of helper class names that must be defined in the class loader of the instrumented library instead of an isolated instrumentation module class loader.
    final String
    instrumentationName()
    Returns the main instrumentation name.
    final Set<String>
    instrumentationNames()
    Returns all instrumentation names assigned to this module.
    boolean
    isHelperClass(String className)
    Instrumentation modules can override this method to specify additional packages (or classes) that should be treated as "library instrumentation" packages.
    void
    registerHelperResources(HelperResourceBuilder helperResourceBuilder)
    Register resource names to inject into the user's class loader.
    abstract List<TypeInstrumentation>
    typeInstrumentations()
    Returns a list of all individual type instrumentation in this module.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    Methods inherited from interface io.opentelemetry.sdk.autoconfigure.spi.Ordered

    order

  • Constructor Details

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

      When enabling or disabling the instrumentation module configuration property that corresponds to the main instrumentation name is considered first, after that additional instrumentation names are considered in the order they are listed here.

      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 Details

    • instrumentationNames

      public final Set<String> instrumentationNames()
      Returns all instrumentation names assigned to this module. See InstrumentationModule(String, String...) for more details about instrumentation names.

    • instrumentationName

      public final String instrumentationName()
      Returns the main instrumentation name. See InstrumentationModule(String, String...) for more details about instrumentation names.

    • defaultEnabled

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

    • defaultEnabled

      public boolean defaultEnabled(io.opentelemetry.sdk.autoconfigure.spi.ConfigProperties config)
      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 class loader 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 class loader 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 class loader 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 class loader after automatically detected ones.

    • injectedClassNames

      public List<String> injectedClassNames()
      Returns a list of helper class names that must be defined in the class loader of the instrumented library instead of an isolated instrumentation module class loader.

      The agent automatically determines whether to inject all helper classes or load them in an isolated class loader, typically based on whether the module uses inlined or non-inlined advice. This method only has an effect when isolated loading is used; when all helper classes are injected, they are already defined in the class loader of the instrumented library.

      Override this method when a helper class must access package-private members of an instrumented library class.

    • exposedClassNames

      public List<String> exposedClassNames()
      Returns a list of instrumentation helper class names that must be visible to the application class loader while remaining loaded by an isolated instrumentation module class loader.

      The agent automatically determines whether to inject all helper classes or load them in an isolated class loader, typically based on whether the module uses inlined or non-inlined advice. This method only has an effect when isolated loading is used; isolated helper classes are not otherwise visible to the instrumented application.

      Override this method when an isolated helper class must be loaded through the application class loader, for example when providing an SPI implementation loaded by ServiceLoader.