- Essentials
- In The App
- Infrastructure
- Application Performance
- Log Management
- Security Platform
- UX Monitoring
- Administration
The latest Java Tracer supports all JVMs version 7 and higher on all platforms.
For a full list of Datadog’s Java version and framework support (including legacy and maintenance versions), read Compatibility Requirements.
Follow the Quickstart instructions within the Datadog app for the best experience, including:
service
, env
, and version
tags.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.
Set apm_non_local_traffic: true
in the apm_config
section of your main datadog.yaml
configuration file.
See the specific setup instructions to ensure that the Agent is configured to receive traces in a containerized environment:
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
.
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, please refer to the Integrations documentation for that environment and contact support if you are encountering any setup issues.
After the agent is installed, to begin tracing your applications:
Download dd-java-agent.jar
that contains the latest Agent class files:
wget -O dd-java-agent.jar https://dtdg.co/latest-java-tracer
To access a specific tracer version, visit Datadog’s Maven repository.
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 -jar path/to/your/app.jar -Ddd.version=1.0
Note: 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_SERVICE | dd.service | The name of a set of processes that do the same job. Used for grouping stats for your application. |
DD_VERSION | dd.version | Your application version (for example, 2.5 , 202003181415 , 1.3-alpha , etc.) |
DD_PROFILING_ENABLED | dd.profiling.enabled | Enable the Continous Profiler |
DD_LOGS_INJECTION | dd.logs.injection | Enable automatic MDC key injection for Datadog trace and span IDs. See Advanced Usage for details. |
DD_TRACE_SAMPLE_RATE | dd.trace.sample.rate | Set a sampling rate at the root of the trace for all services. |
DD_TRACE_SAMPLING_SERVICE_RULES | dd.trace.sampling.service.rules | Set a sampling rate at the root of the trace for services that match the specified rule. |
Additional configuration options are described below.
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"
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:
-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 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.
Instrumentation may come from auto-instrumentation, the OpenTracing API, or a mixture of both. Instrumentation generally captures the following info:
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.
Additional helpful documentation, links, and articles: