Enable Dynamic Instrumentation for Java

Docs > Dynamic Instrumentation > Enabling Dynamic Instrumentation > Enable Dynamic Instrumentation for Java

Dynamic Instrumentation is a feature of supporting Datadog tracing libraries. If you are already using APM to collect traces for your application, ensure your Agent and tracing library are on the required version, and go directly to enabling Dynamic Instrumentation in step 4.

Requirements

The Datadog Dynamic Instrumentation library is supported in JDK version 8 and above.
For a better experience, Datadog recommends enabling autocomplete and search (in Preview).

Installation

Install or upgrade your Agent to version 7.45.0 or higher.
If you don’t already have APM enabled, in your Agent configuration, set the DD_APM_ENABLED environment variable to true and listening to the port 8126/TCP.

Download dd-java-agent.jar:

wget -O dd-java-agent.jar 'https://dtdg.co/latest-java-tracer'

curl -Lo dd-java-agent.jar 'https://dtdg.co/latest-java-tracer'

ADD 'https://dtdg.co/latest-java-tracer' dd-java-agent.jar

Note: Dynamic Instrumentation is available in the dd-java-agent.jar library in versions 1.34.0 and later.

Run your service with Dynamic Instrumentation enabled by setting -Ddd.dynamic.instrumentation.enabled flag or DD_DYNAMIC_INSTRUMENTATION_ENABLED environment variable to true. Specify dd.service, dd.env, and dd.version Unified Service Tags so you can filter and group your probes and target active clients across these dimensions.

Example service startup command:

java \
    -javaagent:dd-java-agent.jar \
    -Ddd.service=<YOUR_SERVICE> \
    -Ddd.env=<YOUR_ENVIRONMENT> \
    -Ddd.version=<YOUR_VERSION> \
    -Ddd.dynamic.instrumentation.enabled=true \
    -jar <YOUR_SERVICE>.jar <YOUR_SERVICE_FLAGS>

export DD_SERVICE=<YOUR_SERVICE>
export DD_ENV=<YOUR_ENV>
export DD_VERSION=<YOUR_VERSION>
export DD_DYNAMIC_INSTRUMENTATION_ENABLED=true
java \
    -javaagent:dd-java-agent.jar \
    -jar <YOUR_SERVICE>.jar <YOUR_SERVICE_FLAGS>

Note: The -javaagent argument needs to be before -jar, adding it as a JVM option rather than an application argument. For more information, see the Oracle documentation:

# Good:
java -javaagent:dd-java-agent.jar ... -jar my-service.jar -more-flags
# Bad:
java -jar my-service.jar -javaagent:dd-java-agent.jar ...

After starting your service with Dynamic Instrumentation enabled, you can start using Dynamic Instrumentation on the APM > Dynamic Instrumentation page.

Configuration

Configure Dynamic Instrumentation using the following environment variables:

Environment variable	Type	Description
`DD_DYNAMIC_INSTRUMENTATION_ENABLED`	Boolean	Alternate for `-Ddd.dynamic.instrumentation.enabled` argument. Set to `true` to enable Dynamic Instrumentation.
`DD_SERVICE`	String	The service name, for example, `web-backend`.
`DD_ENV`	String	The environment name, for example: `production`.
`DD_VERSION`	String	The version of your service.
`DD_TAGS`	String	Tags to apply to produced data. Must be a list of `<key>:<value>` separated by commas such as: `layer:api,team:intake`.