Plugin API

The plugin API of the Elastic APM Java agent lets you add custom instrumentation to the agent, which the agent will automatically apply the same way as it applies the internally defined instrumentation.

The plugin API is the OpenTelemetry API, plus a dependency to the Plugin SDK (apm-agent-plugin-sdk), and requires a version 1.31.0+ agent.

<dependency>
    <groupId>co.elastic.apm</groupId>
    <artifactId>apm-agent-plugin-sdk</artifactId>
    <version>${elastic-apm.version}</version>
</dependency>

compile "co.elastic.apm:apm-agent-plugin-sdk:$elasticApmVersion"

Replace the version placeholders with the latest version from maven central:

An example repo and an article provide a detailed example of adding custom instrumentation for an application to the agent. An overview is

1. subclass co.elastic.apm.agent.sdk.ElasticApmInstrumentation
2. specify matchers the define which classes and methods will be instrumented
3. add an instrumentation advice implementation
4. create a META-INF/services/co.elastic.apm.agent.sdk.ElasticApmInstrumentation file which lists the fully qualified instrumentation class names, one class name per line
5. create a plugin jar that includes the instrumentation classes, the co.elastic.apm.agent.sdk.ElasticApmInstrumentation file, and any dependencies (apart from the agent itself, though including the plugin API as shown above)
6. start your application with the agent as normal, but additionally with the plugins_dir configuration option set to a directory which includes the created plugin jar (and which should only hold plugin jars, as the agent will attempt to load any jar in that directory).

To help our community, we’ve provided a page where you can list plugins you create that you think the community can use.