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.

Choose your instrumentation method

After you deploy or install and configure your Datadog Agent, the next step is to instrument your application. You can do this in the following ways, depending on the infrastructure your app runs on, the language it’s written in, and the level of configuration you require.

See the following pages for supported deployment scenarios and languages:

• Inject the instrumentation library locally (at the Agent);
• Inject the instrumentation library from the Datadog UI (beta); or
• Add the tracing library directly in the application, as described in the Install the tracer section. Read more about compatibility information.

Instrument your application

If you are collecting traces from a Kubernetes application, or from an application on a Linux host or container, as an alternative to the following instructions, you can inject the tracing library into your application. Read Injecting Libraries for instructions.

After the Agent is installed, to begin tracing your applications:

1. 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.

2. 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 -XX:FlightRecorderOptions=stackdepth=256 -Ddd.logs.injection=true -Ddd.service=my-app -Ddd.env=staging -Ddd.version=1.0 -jar path/to/your/app.jar
   

   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.

   Enabling profiling may impact your bill depending on your APM bundle. See the pricing page for more information.

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:

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

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

set CATALINA_OPTS=%CATALINA_OPTS% -javaagent:"c:\path\to\dd-java-agent.jar"

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

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

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

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

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

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

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.

Further Reading

Additional helpful documentation, links, and articles:

Datadog Java APM source codeGITHUB Explore your services, resources, and tracesDOCUMENTATION