Extensions

Extensions add capabilities to the agent without having to create a separate distribution.

Introduction

Extensions add new features and capabilities to the OpenTelemetry Java agent without requiring you to create a separate distribution (a custom version of the entire agent). Think of extensions as plugins that customize how the agent behaves.

Extensions allow you to:

  • Add new instrumentations for libraries not currently supported
  • Customize existing instrumentation behavior
  • Implement custom SDK components (samplers, exporters, propagators)
  • Customize configuration programmatically, for cases that aren’t covered by environment variables or declarative configuration
  • Modify telemetry data collection and processing

Quick start

Here’s a minimal extension that adds a custom span processor to get you started:

Create a Gradle project (build.gradle.kts):

plugins {
    id("java")
    id("com.gradleup.shadow")
}

java {
    toolchain {
        languageVersion.set(JavaLanguageVersion.of(8))
    }
}

dependencies {
    // Use BOM to manage OpenTelemetry dependency versions
    compileOnly(platform("io.opentelemetry:opentelemetry-bom:1.64.0"))

    // OpenTelemetry SDK autoconfiguration SPI (provided by agent)
    compileOnly("io.opentelemetry:opentelemetry-sdk-extension-autoconfigure-spi")

    // OpenTelemetry SDK (needed for SpanProcessor and trace classes)
    compileOnly("io.opentelemetry:opentelemetry-sdk")

    // Annotation processor for automatic SPI registration
    compileOnly("com.google.auto.service:auto-service:1.1.1")
    annotationProcessor("com.google.auto.service:auto-service:1.1.1")

    // Add any external dependencies with 'implementation' scope
    // implementation("org.apache.commons:commons-lang3:3.19.0")
}

tasks.assemble {
    dependsOn(tasks.shadowJar)
}

Create a SpanProcessor implementation:

public class MySpanProcessor implements SpanProcessor {

  @Override
  public void onStart(Context parentContext, ReadWriteSpan span) {
    // Add custom attributes when span starts
    span.setAttribute("custom.processor", "active");
  }

  @Override
  public boolean isStartRequired() {
    return true;
  }

  @Override
  public void onEnd(ReadableSpan span) {
    // Process span when it ends (optional)
  }

  @Override
  public boolean isEndRequired() {
    return false;
  }

  @Override
  public CompletableResultCode shutdown() {
    return CompletableResultCode.ofSuccess();
  }
}

Create an extension class that uses the AutoConfigurationCustomizerProvider SPI:

@AutoService(AutoConfigurationCustomizerProvider.class)
public class MyExtensionProvider implements AutoConfigurationCustomizerProvider {

  @Override
  public void customize(AutoConfigurationCustomizer config) {
    config.addTracerProviderCustomizer(this::configureTracer);
  }

  private SdkTracerProviderBuilder configureTracer(
      SdkTracerProviderBuilder tracerProvider, ConfigProperties config) {
    return tracerProvider
        .setSpanLimits(SpanLimits.builder().setMaxNumberOfAttributes(1024).build())
        .addSpanProcessor(new MySpanProcessor());
  }
}

Build the extension:

./gradlew shadowJar

Use the extension:

java -javaagent:opentelemetry-javaagent.jar \
     -Dotel.javaagent.extensions=build/libs/my-extension-all.jar \
     -jar myapp.jar

Using extensions

There are two ways to use extensions with the Java agent:

  • Load as a separate JAR file - Flexible for development and testing
  • Embed in the agent - Single JAR deployment for production
ApproachProsConsBest for
Runtime loadingEasy to swap extensions, no rebuild neededExtra command-line flag requiredDevelopment, testing
EmbeddingSingle JAR, simpler deployment, can’t forget to loadRequires rebuild to change extensionsProduction, distribution

Loading extensions at runtime

Extensions can be loaded at runtime using the otel.javaagent.extensions system property or OTEL_JAVAAGENT_EXTENSIONS environment variable. This configuration option accepts comma-separated paths to extension JAR files or directories containing extension JARs.

Single extension

java -javaagent:path/to/opentelemetry-javaagent.jar \
     -Dotel.javaagent.extensions=/path/to/my-extension.jar \
     -jar myapp.jar

Multiple extensions

java -javaagent:path/to/opentelemetry-javaagent.jar \
     -Dotel.javaagent.extensions=/path/to/extension1.jar,/path/to/extension2.jar \
     -jar myapp.jar

Extension directory

You can specify a directory containing multiple extension JARs, and all JARs in that directory will be loaded:

java -javaagent:path/to/opentelemetry-javaagent.jar \
     -Dotel.javaagent.extensions=/path/to/extensions-directory \
     -jar myapp.jar

Mixed paths

You can combine individual JAR files and directories:

java -javaagent:path/to/opentelemetry-javaagent.jar \
     -Dotel.javaagent.extensions=/path/to/extension1.jar,/opt/extensions,/tmp/custom.jar \
     -jar myapp.jar

How extension loading works

When you load extensions at runtime, the agent:

  1. Makes OpenTelemetry APIs available to your extension without needing to package them in your extension JAR
  2. Discovers your extension’s components using Java’s ServiceLoader mechanism (via @AutoService annotations in your code, for example)

Embedding extensions in the agent

Another deployment option is to create a single JAR file that contains both the OpenTelemetry Java agent and your extension(s). This approach simplifies deployment (just one JAR file to manage) and eliminates the need for the -Dotel.javaagent.extensions command line option, which makes it harder to accidentally forget to load your extension.

How it works

The agent automatically looks for extensions in a special extensions/ directory inside the agent JAR file, so we can use a Gradle build task to:

  1. Download the OpenTelemetry Java agent JAR
  2. Extract its contents
  3. Add your extension JAR(s) into the extensions/ directory
  4. Repackage everything into a single JAR

The extendedAgent Gradle task

Add the following to your extension project’s build.gradle.kts file:

plugins {
    id("java")

    // Shadow plugin: Combines all your extension's code and dependencies into one JAR
    // This is required because extensions must be packaged as a single JAR file
    id("com.gradleup.shadow") version "9.2.2"
}

group = "com.example"
version = "1.0"

configurations {
    // Create a temporary configuration to download the agent JAR
    // Think of this as a "download slot" that's separate from your extension's dependencies
    create("otel")
}

dependencies {
    // Download the official OpenTelemetry Java agent into the 'otel' configuration
    "otel"("io.opentelemetry.javaagent:opentelemetry-javaagent:2.34.0")

    /*
      Interfaces and SPIs that we implement. We use `compileOnly` dependency because during
      runtime all necessary classes are provided by javaagent itself.
     */
    compileOnly("io.opentelemetry:opentelemetry-sdk-extension-autoconfigure-spi:1.68.0")
    compileOnly("io.opentelemetry:opentelemetry-sdk:1.68.0")
    compileOnly("io.opentelemetry:opentelemetry-api:1.68.0")

    // Required for custom instrumentation
    compileOnly("io.opentelemetry.javaagent:opentelemetry-javaagent-extension-api:2.34.0-alpha")
    compileOnly("io.opentelemetry.instrumentation:opentelemetry-instrumentation-api-incubator:2.34.0-alpha")
    compileOnly("net.bytebuddy:byte-buddy:1.15.10")

    // Provides @AutoService annotation that makes registration of our SPI implementations much easier
    compileOnly("com.google.auto.service:auto-service:1.1.1")
    annotationProcessor("com.google.auto.service:auto-service:1.1.1")
}

// Task: Create an extended agent JAR (agent + your extension)
val extendedAgent by tasks.registering(Jar::class) {
    dependsOn(configurations["otel"])
    archiveFileName.set("opentelemetry-javaagent.jar")

    // Step 1: Unpack the official agent JAR
    from(zipTree(configurations["otel"].singleFile))

    // Step 2: Add your extension JAR to the "extensions/" directory
    from(tasks.shadowJar.get().archiveFile) {
        into("extensions")
    }

    // Step 3: Preserve the agent's startup configuration (MANIFEST.MF)
    doFirst {
        manifest.from(
            zipTree(configurations["otel"].singleFile).matching {
                include("META-INF/MANIFEST.MF")
            }.singleFile
        )
    }
}

tasks {
    // Make sure the shadow JAR is built during the normal build process
    assemble {
        dependsOn(shadowJar)
    }
}

For a complete example, reference the gradle file from the extension example.

Building and using the extended agent

Once you’ve added the extendedAgent task to your build.gradle.kts:

# 1. Build your extension and create the extended agent
./gradlew extendedAgent

# 2. Find the output in build/libs/
ls build/libs/opentelemetry-javaagent.jar

# 3. Use it with your application (no -Dotel.javaagent.extensions needed)
java -javaagent:build/libs/opentelemetry-javaagent.jar -jar myapp.jar

Embedding multiple extensions

To embed multiple extensions, modify the extendedAgent task to include multiple extension JARs:

val extendedAgent by tasks.registering(Jar::class) {
  dependsOn(configurations["otel"])
  archiveFileName.set("opentelemetry-javaagent.jar")

  from(zipTree(configurations["otel"].singleFile))

  // Add multiple extensions
  from(tasks.shadowJar.get().archiveFile) {
    into("extensions")
  }
  from(file("../other-extension/build/libs/other-extension-all.jar")) {
    into("extensions")
  }

  doFirst {
    manifest.from(
      zipTree(configurations["otel"].singleFile).matching {
        include("META-INF/MANIFEST.MF")
      }.singleFile
    )
  }
}

Writing extensions

Creating an extension involves implementing one or more Service Provider Interface (SPI) classes, packaging them as a JAR file, and pointing the agent at that JAR when you run your application (see Using extensions).

Project setup and dependencies

Extensions must carefully manage their dependencies to avoid conflicts with the agent and application. For background on how the agent isolates extensions across class loaders, see Java agent structure.

Dependencies provided by agent (use compileOnly)

These APIs are available at runtime from the agent:

compileOnly("io.opentelemetry:opentelemetry-sdk-extension-autoconfigure-spi")
compileOnly("io.opentelemetry.instrumentation:opentelemetry-instrumentation-api")
compileOnly("io.opentelemetry.instrumentation:opentelemetry-instrumentation-api-incubator")
compileOnly("io.opentelemetry.javaagent:opentelemetry-javaagent-extension-api")

Dependencies from application classpath (use compileOnly)

When creating instrumentation, you need to reference classes from the target application. These should also be compileOnly:

// Only accessible in Advice classes during instrumentation
compileOnly("javax.servlet:javax.servlet-api:3.0.1")

External runtime dependencies (use implementation)

Any external libraries your extension needs at runtime must use implementation scope and will be packaged into the shadow JAR:

implementation("org.apache.commons:commons-lang3:3.19.0")
implementation("com.google.guava:guava:33.0.0-jre")

Extension points overview

OpenTelemetry Java agent provides multiple extension points through SPI interfaces. Here are the most commonly used ones:

Extension pointPackagePurpose
AutoConfigurationCustomizerProviderio.opentelemetry.sdk.autoconfigure.spiMain entry point for SDK customization
ConfigurablePropagatorProviderio.opentelemetry.sdk.autoconfigure.spiRegister custom propagators
ConfigurableSamplerProviderio.opentelemetry.sdk.autoconfigure.spi.tracesRegister custom samplers
ResourceProviderio.opentelemetry.sdk.autoconfigure.spiAdd custom resource attributes
InstrumenterCustomizerProviderio.opentelemetry.instrumentation.api.incubator.instrumenterCustomize existing instrumentations
InstrumentationModuleio.opentelemetry.javaagent.extension.instrumentationCreate new instrumentations

For a full reference of the autoconfiguration SPIs, including built-in and community implementations, see SPI (Service provider interface).

Configuration in extensions

Extensions can read and provide configuration to customize their behavior.

Accessing configuration in extensions

Many SPI methods receive a ConfigProperties parameter that allows you to read configuration:

@Override
public Sampler createSampler(ConfigProperties config) {
  // Read configuration with defaults
  String endpoint = config.getString("otel.exporter.otlp.endpoint", "http://localhost:4317");
  int threshold = config.getInt("otel.instrumentation.myext.threshold", 100);
  boolean enabled = config.getBoolean("otel.instrumentation.myext.enabled", true);
  return new MySampler(endpoint, threshold, enabled);
}

Providing default configuration

Extensions can provide default configuration values that will be used if not overridden:

@Override
public void customize(AutoConfigurationCustomizer config) {
  config.addPropertiesSupplier(() -> {
    Map<String, String> props = new HashMap<>();
    props.put("otel.exporter.otlp.endpoint", "http://my-backend:8080");
    props.put("otel.service.name", "my-service");
    props.put("otel.instrumentation.myext.enabled", "true");
    return props;
  });
}

Configuration naming conventions

Follow these conventions for configuration parameter names:

Standard OpenTelemetry properties use an otel.* prefix.

  • otel.service.name
  • otel.traces.sampler
  • otel.exporter.otlp.endpoint

Instrumentation-specific properties use otel.instrumentation.<name>.*.

  • otel.instrumentation.cassandra.enabled
  • otel.instrumentation.jdbc.statement-sanitizer.enabled

Extension-specific properties follow the same pattern.

  • otel.instrumentation.myextension.enabled
  • otel.instrumentation.myextension.threshold
  • otel.instrumentation.myextension.custom-value

Using @AutoService

The @AutoService annotation automatically generates the required META-INF/services/ files for SPI registration. To use it:

Add the dependency:

compileOnly("com.google.auto.service:auto-service:1.1.1")
annotationProcessor("com.google.auto.service:auto-service:1.1.1")

And then annotate your SPI implementations like this:

import com.google.auto.service.AutoService;

@AutoService(AutoConfigurationCustomizerProvider.class)
public class MyExtension implements AutoConfigurationCustomizerProvider {
  // Implementation
}

This is equivalent to manually creating META-INF/services/io.opentelemetry.sdk.autoconfigure.spi.AutoConfigurationCustomizerProvider with your class name.

Extension point reference

AutoConfigurationCustomizerProvider

This is the main entry point for customizing SDK configuration. It allows you to:

  • Customize the tracer provider
  • Add span processors and exporters
  • Provide default configuration properties
  • Customize other SDK components

Example:

@AutoService(AutoConfigurationCustomizerProvider.class)
public class DemoAutoConfigurationCustomizerProvider
    implements AutoConfigurationCustomizerProvider {

  @Override
  public void customize(AutoConfigurationCustomizer autoConfiguration) {
    autoConfiguration
        .addTracerProviderCustomizer(this::configureSdkTracerProvider)
        .addPropertiesSupplier(this::getDefaultProperties);
  }

  private SdkTracerProviderBuilder configureSdkTracerProvider(
      SdkTracerProviderBuilder tracerProvider, ConfigProperties config) {

    return tracerProvider
        .setIdGenerator(new DemoIdGenerator())
        .setSpanLimits(SpanLimits.builder().setMaxNumberOfAttributes(1024).build())
        .addSpanProcessor(new DemoSpanProcessor())
        .addSpanProcessor(SimpleSpanProcessor.create(new DemoSpanExporter()));
  }

  private Map<String, String> getDefaultProperties() {
    Map<String, String> properties = new HashMap<>();
    properties.put("otel.exporter.otlp.endpoint", "http://backend:8080");
    properties.put("otel.exporter.otlp.insecure", "true");
    properties.put("otel.config.max.attrs", "16");
    properties.put("otel.traces.sampler", "demo");
    return properties;
  }
}

InstrumenterCustomizerProvider

Customize existing instrumentations without modifying their code. This is the recommended way to add attributes, metrics, or modify behavior of built-in instrumentations.

Example:

/**
 * This example demonstrates how to use the InstrumenterCustomizerProvider SPI to customize
 * instrumentation behavior without modifying the core instrumentation code.
 *
 * <p>This customizer adds:
 *
 * <ul>
 *   <li>Custom attributes to HTTP server spans (based on instrumentation name)
 *   <li>Custom attributes to HTTP client spans (based on instrumentation type)
 *   <li>Custom metrics for HTTP operations
 *   <li>Request correlation IDs via context customization
 *   <li>Custom span name transformation
 * </ul>
 *
 * <p>The customizer will be automatically applied to instrumenters that match the specified
 * instrumentation name or type.
 *
 * @see InstrumenterCustomizerProvider
 * @see InstrumenterCustomizer
 */
@AutoService(InstrumenterCustomizerProvider.class)
public class DemoInstrumenterCustomizerProvider implements InstrumenterCustomizerProvider {

  @Override
  public void customize(InstrumenterCustomizer customizer) {
    String instrumentationName = customizer.getInstrumentationName();
    if (isHttpServerInstrumentation(instrumentationName)) {
      customizeHttpServer(customizer);
    }

    if (customizer.hasType(InstrumenterCustomizer.InstrumentationType.HTTP_CLIENT)) {
      customizeHttpClient(customizer);
    }
  }

  private boolean isHttpServerInstrumentation(String instrumentationName) {
    return instrumentationName.contains("servlet")
        || instrumentationName.contains("jetty")
        || instrumentationName.contains("tomcat")
        || instrumentationName.contains("undertow")
        || instrumentationName.contains("spring-webmvc");
  }

  private void customizeHttpServer(InstrumenterCustomizer customizer) {
    customizer.addAttributesExtractor(new DemoAttributesExtractor());
    customizer.addOperationMetrics(new DemoMetrics());
    customizer.addContextCustomizer(new DemoContextCustomizer());
    customizer.setSpanNameExtractorCustomizer(
        unused -> (SpanNameExtractor<Object>) object -> "CustomHTTP/" + object.toString());
  }

  private void customizeHttpClient(InstrumenterCustomizer customizer) {
    // Simple customization for HTTP client instrumentations
    customizer.addAttributesExtractor(new DemoHttpClientAttributesExtractor());
  }

  /** Custom attributes extractor for HTTP client instrumentations. */
  private static class DemoHttpClientAttributesExtractor
      implements AttributesExtractor<Object, Object> {
    private static final AttributeKey<String> CLIENT_ATTR =
        AttributeKey.stringKey("demo.client.type");

    @Override
    public void onStart(AttributesBuilder attributes, Context context, Object request) {
      attributes.put(CLIENT_ATTR, "demo-http-client");
    }

    @Override
    public void onEnd(
        AttributesBuilder attributes,
        Context context,
        Object request,
        Object response,
        Throwable error) {}
  }

  /** Custom attributes extractor that adds demo-specific attributes. */
  private static class DemoAttributesExtractor implements AttributesExtractor<Object, Object> {
    private static final AttributeKey<String> CUSTOM_ATTR = AttributeKey.stringKey("demo.custom");
    private static final AttributeKey<String> ERROR_ATTR = AttributeKey.stringKey("demo.error");

    @Override
    public void onStart(AttributesBuilder attributes, Context context, Object request) {
      attributes.put(CUSTOM_ATTR, "demo-extension");
    }

    @Override
    public void onEnd(
        AttributesBuilder attributes,
        Context context,
        Object request,
        Object response,
        Throwable error) {
      if (error != null) {
        attributes.put(ERROR_ATTR, error.getClass().getSimpleName());
      }
    }
  }

  /** Custom metrics that track request counts. */
  private static class DemoMetrics implements OperationMetrics {
    @Override
    public OperationListener create(Meter meter) {
      LongCounter requestCounter =
          meter
              .counterBuilder("demo.requests")
              .setDescription("Number of requests")
              .setUnit("requests")
              .build();

      return new OperationListener() {
        @Override
        public Context onStart(Context context, Attributes attributes, long startNanos) {
          requestCounter.add(1, attributes);
          return context;
        }

        @Override
        public void onEnd(Context context, Attributes attributes, long endNanos) {
          // Could add duration metrics here if needed
        }
      };
    }
  }

  /** Context customizer that adds request correlation IDs and custom context data. */
  private static class DemoContextCustomizer implements ContextCustomizer<Object> {
    private static final AtomicLong requestIdCounter = new AtomicLong(1);
    private static final ContextKey<String> REQUEST_ID_KEY = ContextKey.named("demo.request.id");

    @Override
    public Context onStart(Context context, Object request, Attributes startAttributes) {
      // Generate a unique request ID for correlation
      String requestId = "req-" + requestIdCounter.getAndIncrement();

      // Add custom context data that can be accessed throughout the request lifecycle
      context = context.with(REQUEST_ID_KEY, requestId);
      return context;
    }
  }
}

ConfigurablePropagatorProvider

Register custom propagators that can be referenced by name in the otel.propagators configuration.

Example:

@AutoService(ConfigurablePropagatorProvider.class)
public class DemoPropagatorProvider implements ConfigurablePropagatorProvider {
  @Override
  public TextMapPropagator getPropagator(ConfigProperties config) {
    return new DemoPropagator();
  }

  @Override
  public String getName() {
    return "demo";
  }
}

ConfigurableSamplerProvider

Register custom samplers that can be referenced in the otel.traces.sampler configuration.

Example (otel.traces.sampler=demo):

@AutoService(ConfigurableSamplerProvider.class)
public class DemoConfigurableSamplerProvider implements ConfigurableSamplerProvider {

  @Override
  public Sampler createSampler(ConfigProperties config) {
    return new DemoSampler();
  }

  @Override
  public String getName() {
    return "demo";
  }
}

ResourceProvider

Add custom resource attributes that will be automatically merged with other resource providers.

Example:

@AutoService(ResourceProvider.class)
public class DemoResourceProvider implements ResourceProvider {
  @Override
  public Resource createResource(ConfigProperties config) {
    Attributes attributes = Attributes.builder().put("custom.resource", "demo").build();
    return Resource.create(attributes);
  }
}

Writing custom instrumentation

Custom instrumentation allows you to inject bytecode into specific methods to add observability to libraries not currently supported by the agent, or to augment existing instrumentation.

When to use custom instrumentation

Use custom instrumentation when you need to:

  • Add tracing, metrics, logs, or events to a library or framework not supported by the agent
  • Run your code before or after specific methods execute
  • Modify the behavior of existing instrumentation using the order() method

For simpler use cases (modifying span attributes, custom samplers, etc.), use SDK customizations (SpanProcessor, Sampler) as shown earlier in this guide.

Components of custom instrumentation

Custom instrumentation is usually comprised of the following components:

  1. InstrumentationModule - Defines what to instrument and when
  2. TypeInstrumentation - Specifies which classes and methods to target
  3. Advice - Contains the code to inject (runs before/after target methods)
  4. Instrumenter - Manages span creation, context propagation, and attributes

Required dependencies

Custom instrumentation requires all the dependencies for writing extensions, plus additional dependencies for bytecode manipulation.

If you haven’t already reviewed the Project setup and dependencies section, start there to understand dependency scopes (compileOnly vs implementation).

For custom instrumentation specifically, ensure your build.gradle.kts includes:

plugins {
  id("java")
  id("com.gradleup.shadow") version "9.2.2"

  // Muzzle plugins - required for all custom instrumentation
  id("io.opentelemetry.instrumentation.muzzle-generation") version "2.34.0-alpha"
  id("io.opentelemetry.instrumentation.muzzle-check") version "2.34.0-alpha"
}

dependencies {
  // The alpha instrumentation BOM manages the javaagent and instrumentation
  // artifacts as well as everything in opentelemetry-bom, so no OpenTelemetry
  // compileOnly dependency below needs a version
  compileOnly(platform("io.opentelemetry.instrumentation:opentelemetry-instrumentation-bom-alpha:2.34.0-alpha"))

  // Core extension dependencies (provided by agent at runtime)
  compileOnly("io.opentelemetry:opentelemetry-sdk-extension-autoconfigure-spi")
  compileOnly("io.opentelemetry:opentelemetry-sdk")
  compileOnly("io.opentelemetry:opentelemetry-api")

  // Additional dependencies for custom instrumentation
  compileOnly("io.opentelemetry.javaagent:opentelemetry-javaagent-extension-api")
  compileOnly("io.opentelemetry.instrumentation:opentelemetry-instrumentation-api-incubator")
  compileOnly("net.bytebuddy:byte-buddy:1.15.10")

  // Auto-service for @AutoService annotation
  compileOnly("com.google.auto.service:auto-service:1.1.1")
  annotationProcessor("com.google.auto.service:auto-service:1.1.1")

  // Target library you're instrumenting (example)
  compileOnly("javax.servlet:javax.servlet-api:3.0.1")

  // Muzzle code generation and tooling (the BOM above doesn't apply to these
  // configurations, so they need explicit versions)
  add("codegen", "io.opentelemetry.javaagent:opentelemetry-javaagent-tooling:2.34.0-alpha")
  add("muzzleBootstrap", "io.opentelemetry.instrumentation:opentelemetry-instrumentation-annotations-support:2.34.0-alpha")
  add("muzzleTooling", "io.opentelemetry.javaagent:opentelemetry-javaagent-extension-api:2.34.0-alpha")
  add("muzzleTooling", "io.opentelemetry.javaagent:opentelemetry-javaagent-tooling:2.34.0-alpha")
}

// Muzzle configuration - specify the library versions your instrumentation
// is compatible with
muzzle {
  pass {
    group.set("javax.servlet")
    module.set("javax.servlet-api")
    versions.set("[3.0,)")
    assertInverse.set(true)
  }
}

The Instrumenter API

The OpenTelemetry Java Instrumentation project provides an Instrumenter API that simplifies creating custom instrumentation. The Instrumenter encapsulates the logic for:

  • Creating and managing spans
  • Extracting and applying span attributes
  • Propagating context (for distributed tracing)
  • Recording operation metrics
  • Handling span status and error conditions

Creating multiple instrumenters

A single instrumentation module may create multiple Instrumenter instances when different operations require different telemetry handling. Common patterns include:

  • Different operations: For example, JDBC creates separate instrumenters for statement execution and transaction management
  • Different messaging patterns: For example, many messaging instrumentations use separate instrumenters for producing messages, receiving messages, and processing messages
  • Different span kinds: Use buildClientInstrumenter(), buildServerInstrumenter(), buildProducerInstrumenter(), or buildConsumerInstrumenter() to create instrumenters that generate CLIENT, SERVER, PRODUCER, or CONSUMER spans respectively

Custom instrumentation basic structure

Create an InstrumentationModule

An InstrumentationModule groups related TypeInstrumentation implementations together. It must be registered using @AutoService:

@AutoService(InstrumentationModule.class)
public class MyCustomInstrumentationModule extends InstrumentationModule {

  public MyCustomInstrumentationModule() {
    super("my-custom-library");
  }

  @Override
  public List<TypeInstrumentation> typeInstrumentations() {
    return Collections.singletonList(new MyTypeInstrumentation());
  }
}

Create a TypeInstrumentation

A TypeInstrumentation defines which classes to instrument and what transformations to apply:

public class MyTypeInstrumentation implements TypeInstrumentation {

  @Override
  public ElementMatcher<TypeDescription> typeMatcher() {
    return named("com.example.MyClass");
  }

  @Override
  public void transform(TypeTransformer transformer) {
    transformer.applyAdviceToMethod(
      named("myMethod")
        .and(isPublic())
        .and(takesArguments(1))
        .and(returns(String.class)),
      this.getClass().getName() + "$MyMethodAdvice");
  }
}

The second argument to applyAdviceToMethod() is the fully qualified name of the Advice class. The $MyMethodAdvice suffix refers to a nested class, which you define in Create an Advice class.

Create an Instrumenter

Create a singleton Instrumenter instance. The Instrumenter is parameterized with REQUEST and RESPONSE types.

  • REQUEST - Represents the operation input (e.g., HTTP request, database query)
  • RESPONSE - Represents the operation output (e.g., HTTP response, query result). Use Void when there is no meaningful response object to capture
public final class MySingletons {

  private static final Instrumenter<MyRequest, MyResponse> INSTRUMENTER;

  static {
    INSTRUMENTER = Instrumenter.<MyRequest, MyResponse>builder(
        GlobalOpenTelemetry.get(),
        "io.opentelemetry.my-custom-library",
        request -> request.getOperationName())
      .addAttributesExtractor(new MyAttributesExtractor())
      .buildInstrumenter(); // Creates INTERNAL spans
  }

  public static Instrumenter<MyRequest, MyResponse> instrumenter() {
    return INSTRUMENTER;
  }

  private MySingletons() {}
}

Create an Advice class

The Advice class contains the code that is inlined into the target method. It is where you actually invoke the Instrumenter: start a span (and make its context current) when the method is entered, and end the span when the method exits. Add it as a nested class of the TypeInstrumentation so that the $MyMethodAdvice reference from applyAdviceToMethod() resolves.

Advice methods are annotated with Byte Buddy’s @Advice.OnMethodEnter and @Advice.OnMethodExit. Values are passed between the enter and exit methods using @Advice.Local fields:

public class MyTypeInstrumentation implements TypeInstrumentation {

  // typeMatcher() and transform() as shown above

  @SuppressWarnings("unused")
  public static class MyMethodAdvice {

    @Advice.OnMethodEnter(suppress = Throwable.class)
    public static void onEnter(
        @Advice.Argument(0) Object argument,
        @Advice.Local("otelRequest") MyRequest request,
        @Advice.Local("otelContext") Context context,
        @Advice.Local("otelScope") Scope scope) {

      // Use Java8BytecodeBridge instead of Context.current() so the advice
      // works on applications running Java 8.
      Context parentContext = Java8BytecodeBridge.currentContext();
      request = new MyRequest(argument);

      if (!instrumenter().shouldStart(parentContext, request)) {
        return;
      }

      context = instrumenter().start(parentContext, request);
      scope = context.makeCurrent();
    }

    @Advice.OnMethodExit(onThrowable = Throwable.class, suppress = Throwable.class)
    public static void onExit(
        @Advice.Return Object returnValue,
        @Advice.Thrown Throwable throwable,
        @Advice.Local("otelRequest") MyRequest request,
        @Advice.Local("otelContext") Context context,
        @Advice.Local("otelScope") Scope scope) {

      if (scope == null) {
        // shouldStart() returned false, so nothing was started.
        return;
      }
      scope.close();

      MyResponse response = new MyResponse(returnValue);
      instrumenter().end(context, request, response, throwable);
    }
  }
}

Because instrumenter() is a static import of MySingletons.instrumenter(), the same singleton Instrumenter created above is reused for every invocation of the instrumented method.

Extension examples

For more extension examples, see the extension project within the Java instrumentation repository.