DDTrace Java

Integrating APM into Java is quite convenient, as it does not require any modifications to the business code; you only need to inject the corresponding agent.

Preconditions¶

Install DataKit and enable the DDTrace Collector. If you want to collect some JVM runtime metrics, you need to enable the StatsD Collector.

Require JDK version 1.8 or above.

Install Dependencies¶

Forked VersionDatadog Version

To add support for more middleware, we have enhanced the DDTrace-Java implementation.

wget -O dd-java-agent.jar 'https://static.guance.com/dd-image/dd-java-agent.jar'

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

Running the Application¶

Host ApplicationKubernetes

You can run your Java code through various means, such as IDE, Maven, Gradle, or directly via the java -jar command. The following example starts the application with the java command:

java \
  -javaagent:/path/to/dd-java-agent.jar \
  -Ddd.logs.injection=true \
  -Ddd.service.name=<YOUR-SERVICE-NAME> \
  -Ddd.env=<YOUR-ENV-NAME> \
  -Ddd.agent.host=<YOUR-DATAKIT-HOST> \
  -Ddd.trace.agent.port=9529 \
  -jar path/to/your/app.jar

Fill in your basic parameter configurations for <YOUR-...> here. In addition to these, there are some optional parameters as follows:

Enable Profiling¶

The Profiling Collector needs to be enabled here.

After enabling Profiling, we can see more information about Java runtime:

java \
  -javaagent:/path/to/dd-java-agent.jar \
  -Ddd.profiling.enabled=true \
  -XX:FlightRecorderOptions=stackdepth=256 \
  ...

Enable Sampling Rate¶

We can enable a sampling rate to reduce the actual amount of data generated:

java \
  -javaagent:/path/to/dd-java-agent.jar \
  -Ddd.trace.sample.rate=0.8 \
  ...

Enable JVM Metrics Collection¶

The statsd Collector needs to be enabled here.

java \
  -javaagent:/path/to/dd-java-agent.jar \
  -Ddd.jmxfetch.enabled=true \
  -Ddd.jmxfetch.check-period=1000 \
  -Ddd.jmxfetch.statsd.host=<YOUR-DATAKIT-HOST>  \
  -Ddd.jmxfetch.statsd.port=8125 \
  ...

In Kubernetes, you can inject the trace agent through the DataKit Operator, or manually mount the trace agent into the application container.

apiVersion: apps/v1
kind: Deployment
spec:
  template:
    spec:
      containers:
        - name: <CONTAINER_NAME>
          image: <CONTAINER_IMAGE>/<TAG>
          env:
            - name: DD_AGENT_HOST
              value: "datakit-service.datakit.svc"
            - name: DD_TRACE_AGENT_PORT
              value: "9529"
            - name: DD_ENV
              value: <YOUR-ENV-NAME>
            - name: DD_SERVICE
              value: <YOUR-SERVICE-NAME>
            - name: DD_LOGS_INJECTION
              value: "true"

For more other parameter settings, refer to the corresponding ENV fields in the Parameter Explanation below.

Parameter Explanation¶

Below are the explanations for each command-line parameter and their corresponding environment variable configurations. For full parameter support, refer to the DataDog Official Documentation.

dd.env

ENV: DD_ENV

Set the environment information for the service, such as testing/prod.
dd.version

ENV: DD_VERSION

The version number of the APP.
dd.service.name

Set the service name. ENV: DD_SERVICE
dd.trace.agent.timeout

ENV: DD_TRACE_AGENT_TIMEOUT

The client network send timeout defaults to 10s.
dd.logs.injection

ENV: DD_LOGS_INJECTION

Whether to enable Java application log injection to associate logs with trace data, defaults to true.
dd.tags

ENV: DD_TAGS

Add default Tags to each Span.
dd.agent.host

ENV: DD_AGENT_HOST

The hostname where DataKit is listening, default is localhost.
dd.trace.agent.port

ENV: DD_TRACE_AGENT_PORT

The port number where DataKit is listening, default is 9529.
dd.trace.sample.rate

ENV: DD_TRACE_SAMPLE_RATE

Set the sampling rate from 0.0 (0%) to 1.0 (100%).
dd.jmxfetch.enabled

ENV: DD_JMXFETCH_ENABLED

Enable JMX metrics collection, default value is true.
dd.jmxfetch.config.dir

ENV: DD_JMXFETCH_CONFIG_DIR

Extra JMX metrics collection configuration directory. The Java Agent will look for jvm_direct: true in the instance section of the yaml configuration file to modify the configuration.
dd.jmxfetch.config

ENV: DD_JMXFETCH_CONFIG

Extra JMX metrics collection configuration file. The JAVA agent will look for jvm_direct: true in the instance section of the yaml configuration file to modify the configuration.
dd.jmxfetch.check-period

ENV: DD_JMXFETCH_CHECK_PERIOD

The frequency of sending JMX metrics (ms), default value is 1500.
dd.jmxfetch.refresh-beans-period

ENV: DD_JMXFETCH_REFRESH_BEANS_PERIOD

The frequency of refreshing JMX beans (s), default value is 600.
dd.jmxfetch.statsd.host

ENV: DD_JMXFETCH_STATSD_HOST

The Statsd host address for receiving JMX metrics, if using Unix Domain Socket please use a host address like unix://PATH_TO_UDS_SOCKET. The default value is the same as agent.host.
dd.jmxfetch.statsd.port

ENV: DD_JMXFETCH_STATSD_PORT

The StatsD port number for receiving JMX metrics, if using Unix Domain Socket please fill in 0. The default value is the same as agent.port.
dd.profiling.enabled

ENV: DD_PROFILING_ENABLED

Enable Profiling control, after enabling, the Profiling information during the Java application runtime will also be collected and reported to DataKit.

More¶

Secondary development version DDTrace JAVA extend
By default, JVM metrics will be collected, specific metrics: metrics
Sampling strategy considerations when DDTrace and OpenTelemetry are concatenated: Tracing Sampled