Tracing Java Applications

Docs > APM > Application Instrumentation > Add the Datadog Tracing Library > Tracing Java Applications

Compatibility requirements

The latest Java Tracer supports all JVMs version 8 and higher. For additional information about JVM versions below 8, read Supported JVM runtimes.

For a full list of Datadog’s Java version and framework support (including legacy and maintenance versions), read Compatibility Requirements.

Getting started

Before you begin, make sure you’ve already installed and configured the Agent.

Instrument your application

After you install and configure your Datadog Agent, the next step is to add the tracing library directly in the application to instrument it. Read more about compatibility information.

To begin tracing your applications:

Download dd-java-agent.jar that contains the latest tracer class files, to a folder that is accessible by your Datadog user:

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: To download the latest build of a specific major version, use the https://dtdg.co/java-tracer-vX link instead, where X is the desired major version. For example, use https://dtdg.co/java-tracer-v1 for the latest version 1 build. Minor version numbers must not be included. Alternatively, see Datadog’s Maven repository for any specific version.

Note: Release Candidate versions are made available in GitHub DataDog/dd-trace-java releases. These have “RC” in the version and are recommended for testing outside of your production environment. You can subscribe to GitHub release notifications to be informed when new Release Candidates are available for testing. If you experience any issues with Release Candidates, reach out to Datadog support.

To run your app from an IDE, Maven or Gradle application script, or java -jar command, with the Continuous Profiler, deployment tracking, and logs injection (if you are sending logs to Datadog), add the -javaagent JVM argument and the following configuration options, as applicable:
```
java -javaagent:/path/to/dd-java-agent.jar -Ddd.profiling.enabled=true -Ddd.logs.injection=true -Ddd.service=my-app -Ddd.env=staging -Ddd.version=1.0 -jar path/to/your/app.jar
```
Note: If you have a strong need to reduce the size of your image and omit modules, you can use the jdeps command to identify dependencies. However, required modules can change over time, so do this at your own risk.
Note: When enabling the tracer for Java 24+, you may see warnings related to JNI native access or sun.misc.Unsafe memory access. Suppress these warnings by adding the --illegal-native-access=allow and --sun-misc-unsafe-memory-access=allow environment variables right before the -javaagent:/path/to/dd-java-agent.jar argument. See JEP 472 and JEP 498 for more information.
Enabling profiling may impact your bill depending on your APM bundle. See the pricing page for more information.

Environment Variable	System Property	Description
`DD_ENV`	`dd.env`	Your application environment (`production`, `staging`, etc.)
`DD_LOGS_INJECTION`	`dd.logs.injection`	Enable automatic MDC key injection for Datadog trace and span IDs. See Advanced Usage for details. Starting in version 1.18.3, if Agent Remote Configuration is enabled where this service runs, you can set `DD_LOGS_INJECTION` in the Software Catalog UI.
`DD_PROFILING_ENABLED`	`dd.profiling.enabled`	Enable the Continuous Profiler
`DD_SERVICE`	`dd.service`	The name of a set of processes that do the same job. Used for grouping stats for your application.
`DD_TRACE_SAMPLE_RATE`	`dd.trace.sample.rate`	Set a sampling rate at the root of the trace for all services. Starting in version 1.18.3, if Agent Remote Configuration is enabled where this service runs, you can set `DD_TRACE_SAMPLE_RATE` in the Software Catalog UI.
`DD_TRACE_SAMPLING_RULES`	`dd.trace.sampling.rules`	Set a sampling rate at the root of the trace for services that match the specified rule.
`DD_VERSION`	`dd.version`	Your application version (for example, `2.5`, `202003181415`, or `1.3-alpha`)

Additional configuration options are described below.

Add the Java Tracer to the JVM

Use the documentation for your application server to figure out the right way to pass in -javaagent and other JVM arguments. Here are instructions for some commonly used frameworks:

If your app is called my_app.jar, create a my_app.conf, containing:

JAVA_OPTS=-javaagent:/path/to/dd-java-agent.jar

For more information, see the Spring Boot documentation.

Linux

To enable tracing when running Tomcat on Linux:

Open your Tomcat startup script file, for example setenv.sh.

Add the following to setenv.sh:

CATALINA_OPTS="$CATALINA_OPTS -javaagent:/path/to/dd-java-agent.jar"

Windows (Tomcat as a Windows service)

To enable tracing when running Tomcat as a Windows service:

Open the “tomcat@VERSION_MAJOR@w.exe” maintenance utility located in the ./bin directory of the Tomcat project folder.
Navigate to the Java tab, and add the following to Java Options:

-javaagent:C:\path\to\dd-java-agent.jar

Restart your Tomcat services for changes to take effect.

In standalone mode:
Add the following line to the end of standalone.conf:

JAVA_OPTS="$JAVA_OPTS -javaagent:/path/to/dd-java-agent.jar"

In standalone mode and on Windows, add the following line to the end of standalone.conf.bat:

set "JAVA_OPTS=%JAVA_OPTS% -javaagent:X:/path/to/dd-java-agent.jar"

In domain mode:
Add the following line in the file domain.xml, under the tag server-groups.server-group.jvm.jvm-options:

<option value="-javaagent:/path/to/dd-java-agent.jar"/>

For more details, see the JBoss documentation.

If you use jetty.sh to start Jetty as a service, edit it to add:

JAVA_OPTIONS="${JAVA_OPTIONS} -javaagent:/path/to/dd-java-agent.jar"

If you use start.ini to start Jetty, add the following line (under --exec, or add --exec line if it isn’t there yet):

-javaagent:/path/to/dd-java-agent.jar

In the administrative console:

Select Servers. Under Server Type, select WebSphere application servers and select your server.
Select Java and Process Management > Process Definition.
In the Additional Properties section, click Java Virtual Machine.
In the Generic JVM arguments text field, enter:

-javaagent:/path/to/dd-java-agent.jar

For additional details and options, see the WebSphere docs.

Note

If you’re adding the -javaagent argument to your java -jar command, it needs to be added before the -jar argument, as a JVM option, not as an application argument. For example:
```
java -javaagent:/path/to/dd-java-agent.jar -jar my_app.jar
```
For more information, see the Oracle documentation.
Never add dd-java-agent to your classpath. It can cause unexpected behavior.

Automatic instrumentation

Automatic instrumentation for Java uses the java-agent instrumentation capabilities provided by the JVM. When a java-agent is registered, it can modify class files at load time.

Note: Classes loaded with remote ClassLoader are not instrumented automatically.

Instrumentation may come from auto-instrumentation, the OpenTracing API, or a mixture of both. Instrumentation generally captures the following info:

Timing duration is captured using the JVM’s NanoTime clock unless a timestamp is provided from the OpenTracing API
Key/value tag pairs
Errors and stack traces which are unhandled by the application
A total count of traces (requests) flowing through the system

Configuration

If needed, configure the tracing library to send application performance telemetry data as you require, including setting up Unified Service Tagging. Read Library Configuration for details.

Remote configuration

Remote Configuration allows the Datadog Agent to dynamically configure tracing settings without requiring application restarts. By default, Remote Configuration is enabled. To disable it, set the environment variable: