Automatic setup with apm-agent-attach.jaredit

Note

This installation method is experimental.

You can use the attacher as a standalone application on the command line or include it in your application to programmatically attach to the current JVM.

This installation method does not require you to alter the configuration of your application server and can be used to conveniently instrument all JVMs on a particular host.

The apm-agent-attach.jar is a small Java program which attaches the Elastic APM Java agent to a specific JVM or to all JVMs of the same host it runs on.

Caveatsedit

This method of attachment is only supported on HotSpot-based JVMs like the OpenJDK and Oracle JDK. It also requires the JDK, specifically the tools.jar to be present - a JRE is not sufficient.

The OS user executing apm-agent-attach.jar and the OS user of the application(s) to be monitored (the JVMs to attach to) has to be the same.

It’s recommended to use the same JDK to start the apm-agent-attach.jar that is used to run the applications you want to attach to.

Downloadedit

You can download the attach program from maven central: maven central

Usageedit

Attach to a JVM with a specific PIDedit

Attaches the agent to a JVM with a specific process ID. Optionally, you can pass in arguments to configure the agent. See Options for the format of the agent arguments.

java -jar apm-agent-attach.jar --pid <pid> [--args <agent_arguments>]

Example: The following command attaches the agent to the JVM with the PID 42 and exits. Additionally, it applies some configuration options.

java -jar apm-agent-attach.jar --pid 42 \
    --args 'service_name=my-cool-service;server_urls=http://localhost:8200'
Attach to a filtered set of JVMs on a certain hostedit

Attaches the agent to all matching JVMs on the host which confirm to the optional include and exclude filters.

java -jar apm-agent-attach.jar [-include <include_pattern>...]
       [-exclude <exclude_pattern>...] [--continuous]
       [--args <agent_arguments> | --args-provider <args_provider_script>]

Example: The following command attaches the agent to all JVMs whose main class contains MyApplication or which are started from a jar file named my-application.jar. It also makes the attacher run continuously so that it attaches the agent on starting JVMs which match the include pattern. Additionally, it applies some configuration options.

java -jar apm-agent-attach.jar \
    --include '.*MyApplication.*' '.*/my-application.jar' \
    --continuous \
    --args 'service_name=my-cool-service;server_urls=http://localhost:8200'
List running JVMsedit

Lists all currently running JVMs, including their PID and their main class name or the path to their jar file.

java -jar apm-agent-attach.jar --list
Optionsedit
-l, --list
Lists all running JVMs. Same output as jps -l.
-p, --pid <pid>

PID of the JVM to attach. If not provided, attaches to all currently running JVMs which match the --exclude and --include filters.

Note

This option cannot be used in conjunction with --continuous, --exclude, --include and --args-provider

-c, --continuous

If provided, this program continuously runs and attaches to all running and starting JVMs which match the --exclude and --include filters.

Note

This option cannot be used in conjunction with --pid

-e, --exclude <exclude_pattern>…​

A list of regular expressions of fully qualified main class names or paths to JARs of applications the java agent should not be attached to. (Matches the output of jps -l)

Note

This option cannot be used in conjunction with --pid

-i, --include <include_pattern>…​

A list of regular expressions of fully qualified main class names or paths to JARs of applications the java agent should be attached to. (Matches the output of jps -l)

Note

This option cannot be used in conjunction with --pid

-a, --args <agent_arguments>

If set, the arguments are used to configure the agent on the attached JVM (agentArguments of agentmain).

The syntax of the arguments is key1=value1;key2=value1,value2. See Configuration for all available configuration options.

Note

This option cannot be used in conjunction with --args-provider

-A, --args-provider <args_provider_script>

The name of a program which is called when a new JVM starts up. The program gets the pid and the main class name or path to the JAR file as an argument and returns an arg string which is used to configure the agent on the attached JVM (agentArguments of agentmain). When returning a non-zero status code from this program, the agent will not be attached to the starting JVM.

The syntax of the arguments is key1=value1;key2=value1,value2. See Configuration for all available configuration options.

Note

This option cannot be used in conjunction with --pid and --args