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

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

    • isIndyModule

      public boolean isIndyModule()
      Note this is an experimental feature until phase 1 of implementing the invokedynamic based instrumentation mechanism is complete. Instrumentation modules that override this to true (recommended) must use the inline=false Invoke Dynamic style of Byte Buddy advices which calls out to helper classes in their own classloader, thus enabling better isolation, best practice code development, avoids shading and enables standard debugging techniques. The non-inlining of advice will be enforced by muzzle (TODO)

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