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.

Installation and getting started

Follow the Quickstart instructions within the Datadog app for the best experience, including:

  • Step-by-step instructions scoped to your deployment configuration (hosts, Docker, Kubernetes, or Amazon ECS).
  • Dynamically set service, env, and version tags.
  • Enable the Continuous Profiler, ingesting 100% of traces, and Trace ID injection into logs during setup.

Configure the Datadog Agent for APM

Install and configure the Datadog Agent to receive traces from your instrumented application. By default, the Datadog Agent is enabled in your datadog.yaml file under apm_config with enabled: true and listens for trace data at http://localhost:8126. For containerized environments, follow the links below to enable trace collection within the Datadog Agent.

    1. Set apm_non_local_traffic: true in the apm_config section of your main datadog.yaml configuration file.

    2. See the specific setup instructions to ensure that the Agent is configured to receive traces in a containerized environment:

    Docker
    Kubernetes
    Amazon ECS
    ECS Fargate

    1. After the application is instrumented, the trace client attempts to send traces to the Unix domain socket /var/run/datadog/apm.socket by default. If the socket does not exist, traces are sent to http://localhost:8126.

      If a different socket, host, or port is required, use the DD_TRACE_AGENT_URL environment variable. Some examples follow:

      DD_TRACE_AGENT_URL=http://custom-hostname:1234
DD_TRACE_AGENT_URL=unix:///var/run/datadog/apm.socket

      java -javaagent:<DD-JAVA-AGENT-PATH>.jar -jar <YOUR_APPLICATION_PATH>.jar

      You can also use system properties:

      java -javaagent:<DD-JAVA-AGENT-PATH>.jar \
    -Ddd.trace.agent.url=$DD_TRACE_AGENT_URL \
    -jar <YOUR_APPLICATION_PATH>.jar

      Similarly, the trace client attempts to send stats to the /var/run/datadog/dsd.socket Unix domain socket. If the socket does not exist, then stats are sent to http://localhost:8125.

    1. Set DD_SITE in the Datadog Agent to to ensure the Agent sends data to the right Datadog location.

    To set up Datadog APM in AWS Lambda, see the Tracing Serverless Functions documentation.

    Tracing is available for a number of other environments, such as Heroku, Cloud Foundry, AWS Elastic Beanstalk, and Azure App Service.

    For other environments, refer to the Integrations documentation for that environment and contact support if you are encountering any setup issues.

    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

      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

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

    Environment VariableSystem PropertyDescription
    DD_ENVdd.envYour application environment (production, staging, etc.)
    DD_SERVICEdd.serviceThe name of a set of processes that do the same job. Used for grouping stats for your application.
    DD_VERSIONdd.versionYour application version (for example, 2.5, 202003181415, 1.3-alpha, etc.)
    DD_PROFILING_ENABLEDdd.profiling.enabledEnable the Continous Profiler
    DD_LOGS_INJECTIONdd.logs.injectionEnable automatic MDC key injection for Datadog trace and span IDs. See Advanced Usage for details.
    DD_TRACE_SAMPLE_RATEdd.trace.sample.rateSet a sampling rate at the root of the trace for all services.
    DD_TRACE_SAMPLING_RULESdd.trace.sampling.rulesSet a sampling rate at the root of the trace for services that match the specified rule.

    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.

      Open your Tomcat startup script file, for example setenv.sh on Linux, and add:

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

      Or on Windows, setenv.bat:

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

      If a setenv file does not exist, create it in the ./bin directory of the Tomcat project folder.

      • 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:

      1. Select Servers. Under Server Type, select WebSphere application servers and select your server.
      2. Select Java and Process Management > Process Definition.
      3. In the Additional Properties section, click Java Virtual Machine.
      4. 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.

      Further Reading

      Additional helpful documentation, links, and articles:

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