Getting Started
Security Monitoring is now available Security Monitoring is now available

Getting Started

Profiling is shipped within the following tracing libraries. Select your language below to learn how to enable profiling for your application:

The Datadog Profiler requires JDK Flight Recorder. The Datadog Profiling library is supported in OpenJDK 11+, Oracle Java 11+, and Zulu Java 8+ (minor version 1.8.0_212+). All JVM-based languages, such as Scala, Groovy, Kotlin, Clojure, etc. are supported. To begin profiling applications:

  1. If you are already using Datadog, upgrade your agent to version 7.20.2+ or 6.20.2+. 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://repository.sonatype.org/service/local/artifact/maven/redirect?r=central-proxy&g=com.datadoghq&a=dd-java-agent&v=LATEST'

    Note: Profiling is available in the dd-java-agent.jar library in versions 0.55+.

  3. Set -Ddd.profiling.enabled flag or DD_PROFILING_ENABLED environment variable to true. Update to your service invocation should look like:

    java -javaagent:dd-java-agent.jar -Ddd.profiling.enabled=true -jar <YOUR_SERVICE>.jar <YOUR_SERVICE_FLAGS>
    
  4. After a minute or two, visualize your profiles on the Datadog APM > Profiling page.

Note:

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

    # Good:
    java -javaagent:dd-java-agent.jar ... -jar my-service.jar -more-flags
    # Bad:
    java -jar my-service.jar -javaagent:dd-java-agent.jar ...
  • We strongly recommend that you specify the service and version as this gives you the ability to slice and dice your profiles across these dimensions. Use environment variables to set the parameters:

Environment variableTypeDescription
DD_PROFILING_ENABLEDBooleanAlternate for -Ddd.profiling.enabled argument. Set to true to enable profiling.
DD_SERVICEStringYour service name, for example, web-backend.
DD_ENVStringYour environment name, for example: production.
DD_VERSIONStringThe version of your service.
DD_TAGSStringTags to apply to an uploaded profile. Must be a list of <key>:<value> separated by commas such as: layer:api, team:intake.

The Datadog Profiler requires Python 2.7+. Memory profiling is available on Python 3.5+. To begin profiling applications:

  1. If you are already using Datadog, upgrade your agent to version 7.20.2+ or 6.20.2+.

  2. Install ddtrace which contains both tracing and profiling:

    pip install ddtrace

    Note: Profiling is available in the ddtrace library for versions 0.36+.

  3. To automatically profile your code, set DD_PROFILING_ENABLED environment variable to true when you use ddtrace-run:

    DD_PROFILING_ENABLED=true ddtrace-run python app.py

    Note: DD_PROFILING_ENABLED is only supported in dd-trace version 0.40+. Use the alternate method if you are running an older version of dd-trace.

    Alternate method

    If you prefer to instrument the profiler through code, import ddtrace.profile.auto. After import, the Profiler starts:

    import ddtrace.profiling.auto
  4. After a minute or two, visualize your profiles on the Datadog APM > Profiling page.

Note:

  • Alternatively, profile your service by running it with the wrapper pyddprofile:

    $ pyddprofile server.py
  • It is strongly recommended to add tags like service or version as it provides the ability to slice and dice your profiles across these dimensions, enhancing your overall product experience. Use environment variables to set the parameters:

Environment variableTypeDescription
DD_PROFILING_ENABLEDBooleanSet to true to enable profiling. Supported from tracker version 0.40+.
DD_SERVICEStringThe Datadog service name.
DD_ENVStringThe Datadog environment name, for example, production.
DD_VERSIONStringThe version of your application.
DD_TAGSStringTags to apply to an uploaded profile. Must be a list of <key>:<value> separated by commas such as: layer:api,team:intake.
Recommended for advanced usage only.
  • When your process forks using os.fork, the profiler is stopped in the child process.

For Python 3.7+ on POSIX platforms, a new profiler is started if you enabled the profiler via pyddprofile or ddtrace.profiling.auto.

If you manually create a Profiler(), use Python < 3.6, or run on a non-POSIX platform, manually restart the profiler in your child with:

   ddtrace.profiling.auto.start_profiler()
  • If you want to manually control the lifecycle of the profiler, use the ddtrace.profiling.profiler.Profiler object:

    from ddtrace.profiling import Profiler
    
    prof = Profiler()
    prof.start()
    
    # At shutdown
    prof.stop()

The Datadog Profiler requires Go 1.12+. To begin profiling applications:

  1. If you are already using Datadog, upgrade your agent to version 7.20.2+ or 6.20.2+.

  2. Get dd-trace-go using the command:

    go get gopkg.in/DataDog/dd-trace-go.v1

    Note: Profiling is available in the dd-trace-go library for versions 1.23.0+.

  3. Import the profiler at the start of your application:

    import "gopkg.in/DataDog/dd-trace-go.v1/profiler"
  4. Add the following snippet to start the profiler:

    err := profiler.Start(
        profiler.WithService("<SERVICE_NAME>"),
        profiler.WithEnv("<ENVIRONMENT>"),
        profiler.WithVersion("<APPLICATION_VERSION>"),
        profiler.WithTags("<KEY1>:<VALUE1>,<KEY2>:<VALUE2>"),
    )
    if err != nil {
        log.Fatal(err)
    }
    defer profiler.Stop()
  5. After a minute or two, visualize your profiles in the Datadog APM > Profiling page.

Note:

  • It is strongly recommended to add tags like service or version as it provides the ability to slice and dice your profiles across these dimensions, enhancing your overall product experience. Use profiler configuration to set the parameters:
MethodTypeDescription
WithServiceStringThe Datadog service name, for example my-web-app.
WithEnvStringThe Datadog environment name, for example, production.
WithVersionStringThe version of your application.
WithTagsStringThe tags to apply to an uploaded profile. Must be a list of in the format <KEY1>:<VALUE1>,<KEY2>:<VALUE2>.
  • Alternatively you can also set the profiler configuration using environment variables:
Environment variableTypeDescription
DD_SERVICEStringThe Datadog service name.
DD_ENVStringThe Datadog environment name, for example, production.
DD_VERSIONStringThe version of your application.
DD_TAGSStringTags to apply to an uploaded profile. Must be a list of <key>:<value> separated by commas such as: layer:api,team:intake.

The Datadog Profiler requires Node 10.12+. To begin profiling applications:

  1. If you are already using Datadog, upgrade your agent to version 7.20.2+ or 6.20.2+.

  2. Install dd-trace which contains both tracing and profiling:

    npm install --save dd-trace

    Note: Profiling is available in the dd-trace library in versions 0.23.2+.

  3. To automatically profile your code, import and initialize dd-trace with profiling enabled:

    require('dd-trace').init({
      profiling: true
    })
    
  4. After a minute or two, visualize your profiles on the Datadog APM > Profiling page.

Note:

  • Tags such as service or version are also available. Use environment variables to set the parameters:
Environment variableTypeDescription
DD_PROFILING_ENABLEDBooleanSet to true to enable profiling.
DD_SERVICEStringThe Datadog service name.
DD_ENVStringThe Datadog environment name, for example production.
DD_VERSIONStringThe version of your application.
DD_TAGSStringThe tags to apply to an uploaded profile. Must be a list of <key>:<value> separated by commas such as: layer:api, team:intake.

Troubleshooting

If you’ve configured the profiler and don’t see profiles in the profile search page, please turn on debug mode and open a support ticket with debug files and the following information:

  • OS type and version (e.g Linux Ubuntu 14.04.3)
  • Runtime type, version, and vendor (e.g Java OpenJDK 11 AdoptOpenJDK)

Further Reading