Example of instrumentation which plugs in to the Elastic Java Agent and instruments an application

The Elastic APM Java Agent is a Java agent that automatically measures the performance of your application and tracks errors. Full documentation is available.

This project provides a detailed example of using the Elastic APM Java Plugin API to add custom instrumentation in to the agent, which the agent will automatically apply without the need for users to touch the target application's code.

Detailed articles on creating the instrumentation and on regression testing it are available

This project has two sub-projects

• application - a standalone runnable example application that is here purely to provide an example target to instrument
• plugin - the plugin that instruments the application

The application consists of a webserver and a client that executes some requests against the webserver. A webserver interface and two implementations are provided:

• ExampleAlreadyInstrumentedHttpServer uses the com.sun.net.httpserver.HttpServer that is a standard part of the JDK to implement the webserver interface; the Elastic APM Java Agent already automatically instruments this technology, so this implementation is provided as a reference for checking logging and output
• ExampleBasicHttpServer implements a very restricted custom webserver, to provide a target for the custom instrumentation

The ExampleClient provides an application entry point that, when run, will start the selected webserver (chosen by setting the property elastic.apm.service_name), and send it some requests before terminating.

Note the application implementation is deliberately simple (eg System.out instead of a logging framework) to keep it as easy to understand as possible.

The plugin consists of a single file holding the custom instrumentation, several classes for regression testing, and a pom that builds the correct plugin jar. The details of the plugin project are explained in the articles creating the instrumentation and regression testing it.

The full project can be built by cloning to your local system, changing to the root directory, and running mvn clean install.

Prerequisites: git, maven and JDK 11+ installed

git clone https://github.com/elastic/apm-agent-java-plugin-example.git
cd apm-agent-java-plugin-example
mvn clean install

Each sub-project can also be separately built the same way (changing to the sub-project root directory and running mvn clean install).

You need an Elastic APM Java Agent jar (the latest version is recommended, but at least version 1.31.0). Additionally an Elastic APM server is recommended, though not required (communications to the server will be dropped if it's unavailable).

The full set of example run instructions below are also available as a batch script in the project root directory, in file runExamples.bash/runExamples.bat

The latest agent version can be found in Maven. You can download using any of the standard download mechanisms, eg

wget https://repo1.maven.org/maven2/co/elastic/apm/elastic-apm-agent/1.32.0/elastic-apm-agent-1.32.0.jar

You can run the standalone application, with no agent, from the project root directory as follows

java -Delastic.apm.service_name=ExampleClient-ExampleAlreadyInstrumentedHttpServer -cp application/target/application-*.jar co.elastic.apm.example.webserver.ExampleClient
java -Delastic.apm.service_name=ExampleClient-ExampleBasicHttpServer -cp application/target/application-*.jar co.elastic.apm.example.webserver.ExampleClient

Assuming you have set the jar location in AGENT_JAR and if available the APM server is specified in APM_SERVER_URL and APM_SECRET_TOKEN, you can run the application with agent but no plugin, from the project root directory, as follows

export AGENT_JAR=...
export APM_SERVER_URL=...
export APM_SECRET_TOKEN=...

java -Delastic.apm.server_url=$APM_SERVER_URL -Delastic.apm.secret_token=$APM_SECRET_TOKEN -javaagent:$AGENT_JAR -Delastic.apm.log_level=DEBUG -Delastic.apm.service_name=ExampleClient-ExampleAlreadyInstrumentedHttpServer -cp application/target/application-*.jar co.elastic.apm.example.webserver.ExampleClient
java -Delastic.apm.server_url=$APM_SERVER_URL -Delastic.apm.secret_token=$APM_SECRET_TOKEN -javaagent:$AGENT_JAR -Delastic.apm.log_level=DEBUG -Delastic.apm.service_name=ExampleClient-ExampleBasicHttpServer -cp application/target/application-*.jar co.elastic.apm.example.webserver.ExampleClient

Assuming you have set the jar location in AGENT_JAR and if available the APM server is specified in APM_SERVER_URL and APM_SECRET_TOKEN, you can run the application with agent and plugin, from the project root directory, as follows

export AGENT_JAR=...
export APM_SERVER_URL=...
export APM_SECRET_TOKEN=...

java -Delastic.apm.enable_experimental_instrumentations=true -Delastic.apm.plugins_dir=plugin/target -Delastic.apm.server_url=$APM_SERVER_URL -Delastic.apm.secret_token=$APM_SECRET_TOKEN -javaagent:$AGENT_JAR -Delastic.apm.log_level=DEBUG -Delastic.apm.service_name=ExampleClient-ExampleAlreadyInstrumentedHttpServer -cp application/target/application-*.jar co.elastic.apm.example.webserver.ExampleClient
java -Delastic.apm.enable_experimental_instrumentations=true -Delastic.apm.plugins_dir=plugin/target -Delastic.apm.server_url=$APM_SERVER_URL -Delastic.apm.secret_token=$APM_SECRET_TOKEN -javaagent:$AGENT_JAR -Delastic.apm.log_level=DEBUG -Delastic.apm.service_name=ExampleClient-ExampleBasicHttpServer -cp application/target/application-*.jar co.elastic.apm.example.webserver.ExampleClient