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.

Install Dependencies¶

GuanceCloud VersionDatadog Version

To add support for more middleware, GuanceCloud has 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.