Enabling the Java Profiler

The profiler is shipped within Datadog tracing libraries. If you are already using APM to collect traces for your application, you can skip installing the library and go directly to enabling the profiler.

Requirements

For a summary of the minimum and recommended runtime and tracer versions across all languages, read Supported Language and Tracer Versions.

    Available profile types:

    • CPU
    • Wallclock (latency)
    • Allocations
    • Live heap (memory leak detection)
    • Exception profiling
    • I/O profiling
    JDK DistributionMinimum VersionNotes
    OpenJDK8u352+, 11.0.17+, 17.0.5+, 21+Includes builds from Amazon Corretto, Azul Zulu, Eclipse Temurin, BellSoft Liberica, and other OpenJDK-based distributions
    Oracle JDK8u351+, 11.0.17+, 17.0.5+, 21+
    OpenJ9 JDK8u372+, 11.0.18+, 17.0.6+Includes Eclipse OpenJ9, IBM JDK, and IBM Semeru Runtime
    Azul Platform Prime23.05.0.0+

    Available profile types:

    • CPU
    • Allocations
    • I/O profiling
    • Exception
    JDK DistributionMinimum VersionNotes
    OpenJDK8u282+, 11.0.17+, 17.0.5+, 21.0.3+Includes builds from Amazon Corretto, Azul Zulu, Eclipse Temurin, BellSoft Liberica, and other OpenJDK-based distributions
    Oracle JDK11.0.17+, 17.0.5+, 21.0.3+JFR may require commercial license. Oracle JDK 8u40+ supported with limited features (CPU profiling only)
    Azul Zulu8u212+, 11.0.17+, 17.0.5+, 21.0.3+
    GraalVM17.0.11+, 21.0.3+JIT mode and native-image(AOT)

    • All JVM-based languages, such as Java, Scala, Groovy, Kotlin, and Clojure are supported.

    • The profiler supports only actively maintained LTS JDK versions and the most recent General Availability (GA) JDK releases.

    • Java Profiler is not supported on serverless environments.

    Installation

    To begin profiling applications:

    1. Install and run Datadog Agent v6+. Datadog recommends using Datadog Agent v7+. If you don’t have APM enabled to set up your application to send data to Datadog, in your Agent, set the DD_APM_ENABLED environment variable to true and listening to the port 8126/TCP.

    2. Download dd-java-agent.jar, which contains the Java Agent class files:

        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

      • Enable the profiler by setting -Ddd.profiling.enabled flag or DD_PROFILING_ENABLED environment variable to true. Specify dd.service, dd.env, and dd.version so you can filter and group your profiles across these dimensions:

          java \
    -javaagent:dd-java-agent.jar \
    -Ddd.service=<YOUR_SERVICE> \
    -Ddd.env=<YOUR_ENVIRONMENT> \
    -Ddd.version=<YOUR_VERSION> \
    -Ddd.profiling.enabled=true \
    -jar <YOUR_SERVICE>.jar <YOUR_SERVICE_FLAGS>

          export DD_SERVICE=<YOUR_SERVICE>
export DD_ENV=<YOUR_ENV>
export DD_VERSION=<YOUR_VERSION>
export DD_PROFILING_ENABLED=true
java \
    -javaagent:dd-java-agent.jar \
    -jar <YOUR_SERVICE>.jar <YOUR_SERVICE_FLAGS>

          Note: The -javaagent argument needs to be before -jar. This adds it as a JVM option rather than an application argument. For more information, see the Oracle documentation.

        Optional: Set up Source Code Integration to connect your profiling data with your Git repositories.

        1. After a couple of minutes, your profiles appear on the Datadog APM > Profiling page.

        2. For more information on available profile types, see Profile Types.

        Note: For GraalVM native-image applications, see Enabling the Profiler for GraalVM Native Image.

        Configuration

        In addition to the environment, service, and version variables shown in the installation steps, you can apply custom tags to uploaded profiles with DD_TAGS (a comma-separated list of <key>:<value> pairs such as layer:api, team:intake).

        For additional configuration options, see the Configuration reference in the troubleshooting guide.

        Not sure what to do next?

        The Getting Started with Profiler guide takes a sample service with a performance problem and shows you how to use Continuous Profiler to understand and fix the problem.

        Facing issues while enabling the profiler or need troubleshooting guidance? See the Java Profiler Troubleshooting guide.

        Further Reading

        Additional helpful documentation, links, and articles:

        Getting Started with ProfilerDOCUMENTATION more more Learn more about available profile visualizationsDOCUMENTATION more more Fix problems you encounter while using the profilerDOCUMENTATION more more