--- title: Enabling the Profiler description: Datadog, the leading service for cloud-scale monitoring. breadcrumbs: Docs > Continuous Profiler > Enabling the Profiler --- # Enabling the Profiler {% section displayed-if="Language is Java" %} This section only applies to users who meet the following criteria: Language is Java The profiler is shipped within Datadog SDKs. If you are already using [APM to collect traces](https://docs.datadoghq.com/tracing/trace_collection.md) for your application, you can skip installing the library and go directly to enabling the profiler. ## Requirements{% #requirements %} For a summary of the minimum and recommended runtime and tracer versions across all languages, read [Supported Language and Tracer Versions](https://docs.datadoghq.com/profiler/enabling/supported_versions.md). {% section displayed-if="Runtime is JVM" %} This section only applies to users who meet the following criteria: Runtime is JVM {% tab title="Linux" %} **Available profile types**: - CPU - Wallclock (latency) - Allocations - Live heap (memory leak detection) - Exception profiling - I/O profiling | JDK Distribution | Minimum Version | Notes | | ------------------- | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------- | | OpenJDK | 8u352+, 11.0.17+, 17.0.5+, 21+ | Includes builds from Amazon Corretto, Azul Zulu, Eclipse Temurin, BellSoft Liberica, and other OpenJDK-based distributions | | Oracle JDK | 8u351+, 11.0.17+, 17.0.5+, 21+ | | OpenJ9 JDK | 8u372+, 11.0.18+, 17.0.6+ | Includes Eclipse OpenJ9, IBM JDK, and IBM Semeru Runtime | | Azul Platform Prime | 23.05.0.0+ | {% /tab %} {% tab title="Windows" %} **Available profile types**: - CPU - Allocations - I/O profiling - Exception | JDK Distribution | Minimum Version | Notes | | ---------------- | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | | OpenJDK | 8u282+, 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 JDK | 11.0.17+, 17.0.5+, 21.0.3+ | JFR may require commercial license. Oracle JDK 8u40+ supported with limited features (CPU profiling only) | | Azul Zulu | 8u212+, 11.0.17+, 17.0.5+, 21.0.3+ | | GraalVM | 17.0.11+, 21.0.3+ | JIT mode and native-image(AOT) | {% /tab %} - 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. - Continuous Profiler is not supported on serverless platforms. {% /section %} {% section displayed-if="Runtime is GraalVM Native Image" %} This section only applies to users who meet the following criteria: Runtime is GraalVM Native Image {% alert level="warning" %} Datadog Profiler support for GraalVM native-image is in Preview. Datadog recommends evaluating the profiler in a non-sensitive environment before deploying in production. {% /alert %} {% dl %} {% dt %} Minimum version {% /dt %} {% dd %} GraalVM 17+ {% /dd %} {% dt %} Supported platforms {% /dt %} {% dd %} Linux, Windows, macOS {% /dd %} {% dt %} Available profile types {% /dt %} {% dd %} CPU, Allocations {% /dd %} {% /dl %} {% /section %} ## Installation{% #installation %} To begin profiling applications: 1. Install and run Datadog Agent v6+. Datadog recommends using [Datadog Agent v7+](https://app.datadoghq.com/account/settings/agent/latest?platform=overview). 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 the port to `8126/TCP`. {% section displayed-if="Runtime is JVM" %} This section only applies to users who meet the following criteria: Runtime is JVM Download `dd-java-agent.jar`, which contains the Java Agent class files: {% tab title="Wget" %} ``` wget -O dd-java-agent.jar 'https://dtdg.co/latest-java-tracer' ``` {% /tab %} {% tab title="cURL" %} ``` curl -Lo dd-java-agent.jar 'https://dtdg.co/latest-java-tracer' ``` {% /tab %} {% tab title="Dockerfile" %} ``` ADD 'https://dtdg.co/latest-java-tracer' dd-java-agent.jar ``` {% /tab %} Enable the profiler and specify your service, environment, and version: {% tab title="Command arguments" %} ``` java \ -javaagent:dd-java-agent.jar \ -Ddd.service= \ -Ddd.env= \ -Ddd.version= \ -Ddd.profiling.enabled=true \ -jar .jar ``` {% /tab %} {% tab title="Environment variables" %} ``` export DD_SERVICE= export DD_ENV= export DD_VERSION= export DD_PROFILING_ENABLED=true java \ -javaagent:dd-java-agent.jar \ -jar .jar ``` {% /tab %} {% alert level="info" %} 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](https://docs.oracle.com/javase/7/docs/technotes/tools/solaris/java.html). {% /alert %} Optional: Set up [Source Code Integration](https://docs.datadoghq.com/integrations/guide/source-code-integration.md?tab=java) to connect your profiling data with your Git repositories. After a couple of minutes, your profiles appear on the [Datadog APM > Profiler page](https://app.datadoghq.com/profiling). If they do not, see the [Troubleshooting](https://docs.datadoghq.com/profiler/profiler_troubleshooting/java.md) guide. For more information on available profile types, see [Profile Types](https://docs.datadoghq.com/profiler/profile_types.md?tab=java). {% alert level="info" %} For GraalVM native-image applications, switch the **Runtime** filter above to **GraalVM Native Image**. {% /alert %} {% /section %} {% section displayed-if="Runtime is GraalVM Native Image" %} This section only applies to users who meet the following criteria: Runtime is GraalVM Native Image Follow the [Tracer Setup Instructions](https://docs.datadoghq.com/tracing/trace_collection/compatibility/java.md?tab=graalvm#setup) to build your GraalVM native image with the Datadog Java Profiler instrumentation. Run with profiling enabled: ``` export DD_SERVICE= export DD_ENV= export DD_VERSION= export DD_PROFILING_ENABLED=true export DD_PROFILING_DIRECTALLOCATION_ENABLED=true ./my_service ``` After a couple of minutes, your profiles appear on the [Datadog APM > Profiler page](https://app.datadoghq.com/profiling). ### Limitations{% #limitations %} - Only JFR-based profiling is supported for GraalVM native-image applications. - Wallclock and live heap profiling are not available. {% /section %} ## Configuration{% #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 `:` pairs such as `layer:api, team:intake`). {% section displayed-if="Runtime is JVM" %} This section only applies to users who meet the following criteria: Runtime is JVM For additional configuration options, see the [Configuration reference](https://docs.datadoghq.com/profiler/profiler_troubleshooting/java.md#configuration-reference) in the troubleshooting guide. {% /section %} {% section displayed-if="Runtime is GraalVM Native Image" %} This section only applies to users who meet the following criteria: Runtime is GraalVM Native Image For profile type configuration options, see the [Configuration reference](https://docs.datadoghq.com/profiler/profiler_troubleshooting/java.md#configuration-reference) in the Java profiler troubleshooting guide. {% /section %} {% /section %} {% section displayed-if="Language is Python" %} This section only applies to users who meet the following criteria: Language is Python The profiler is shipped within Datadog SDKs. If you are already using [APM to collect traces](https://docs.datadoghq.com/tracing/trace_collection.md) for your application, you can skip installing the library and go directly to enabling the profiler. ## Requirements{% #requirements-2 %} For a summary of the minimum and recommended runtime and tracer versions across all languages, read [Supported Language and Tracer Versions](https://docs.datadoghq.com/profiler/enabling/supported_versions.md). - Verify your Python and SDK versions are compatible by reviewing the [Python Compatibility Requirements](https://docs.datadoghq.com/tracing/trace_collection/compatibility/python.md). - Some features depend on newer Python versions than the minimum required version for the SDK. For more details, read [Profile Types](https://docs.datadoghq.com/profiler/profile_types.md?tab=python). - The installation requires pip version 18 or above. - Continuous Profiler support is in Preview for some serverless platforms, such as [AWS Lambda](https://docs.datadoghq.com/serverless/aws_lambda/profiling.md). ## Installation{% #installation-2 %} To begin profiling applications: 1. Make sure Datadog Agent v6+ is installed and running. Datadog recommends using [Datadog Agent v7+](https://app.datadoghq.com/account/settings/agent/latest?platform=overview). 1. Install `ddtrace`, which provides both tracing and profiling functionalities: ``` pip install ddtrace ``` If you are using a platform where `ddtrace` binary distribution is not available, first install a development environment. For example, on Alpine Linux: ``` apk install gcc musl-dev linux-headers ``` 1. Enable the profiler and specify your service, environment, and version: ``` DD_PROFILING_ENABLED=true \ DD_ENV=prod \ DD_SERVICE=my-web-app \ DD_VERSION=1.0.3 \ ddtrace-run python app.py ``` To manually control the life cycle of the profiler, use the `ddtrace.profiling.Profiler` object: ``` from ddtrace.profiling import Profiler prof = Profiler( env="prod", # if not specified, falls back to environment variable DD_ENV service="my-web-app", # if not specified, falls back to environment variable DD_SERVICE version="1.0.3", # if not specified, falls back to environment variable DD_VERSION ) prof.start() # Should be as early as possible, eg before other imports, to ensure everything is profiled ``` 1. Optional: Set up [Source Code Integration](https://docs.datadoghq.com/integrations/guide/source-code-integration.md?tab=python) to connect your profiling data with your Git repositories. 1. After a couple of minutes, your profiles appear on the [Datadog APM > Profiler page](https://app.datadoghq.com/profiling). If they do not, see the [Troubleshooting](https://docs.datadoghq.com/profiler/profiler_troubleshooting/python.md) guide. ### Caveats{% #caveats %} When your process forks using `os.fork`, the profiler is automatically restarted in the child process on supported Python versions. No manual restart is required. ## Configuration{% #configuration-2 %} You can configure the profiler using the [environment variables](https://ddtrace.readthedocs.io/en/stable/configuration.html#configuration). ### Code provenance{% #code-provenance %} The Python profiler supports code provenance reporting, which provides insight into the library that is running the code. While this is enabled by default, you can turn it off by setting `DD_PROFILING_ENABLE_CODE_PROVENANCE=0`. {% /section %} {% section displayed-if="Language is Go" %} This section only applies to users who meet the following criteria: Language is Go The profiler is shipped within Datadog SDKs. If you are already using [APM to collect traces](https://docs.datadoghq.com/tracing/trace_collection.md) for your application, you can skip installing the library and go directly to enabling the profiler. ## Requirements{% #requirements-3 %} For a summary of the minimum and recommended runtime and tracer versions across all languages, read [Supported Language and Tracer Versions](https://docs.datadoghq.com/profiler/enabling/supported_versions.md). The Datadog Profiler requires one of the latest two major Go releases. These are the major Go releases [supported by the Go project](https://go.dev/doc/devel/release). For the [Trace to Profiling integration](https://docs.datadoghq.com/profiler/connect_traces_and_profiles.md#identify-code-hotspots-in-slow-traces) and [Endpoint Profiling](https://docs.datadoghq.com/profiler/connect_traces_and_profiles.md#break-down-code-performance-by-api-endpoints), use `dd-trace-go` version 1.51.0+. Continuous Profiler is not supported on serverless platforms, such as AWS Lambda. ## Installation{% #installation-3 %} To begin profiling applications: 1. Make sure Datadog Agent v6+ is installed and running. Datadog recommends using [Datadog Agent v7+](https://app.datadoghq.com/account/settings/agent/latest?platform=overview). 1. Install `dd-trace-go`: ``` go get github.com/DataDog/dd-trace-go/v2/profiler ``` Important alert (level: info): If you are using v1 of the Go tracer, see the [migration guide](https://docs.datadoghq.com/tracing/trace_collection/custom_instrumentation/go/migration.md) to upgrade to v2 and for all future updates and features. 1. Import the [profiler](https://pkg.go.dev/github.com/DataDog/dd-trace-go/v2/profiler#pkg-constants) and start it in your application: ``` import "github.com/DataDog/dd-trace-go/v2/profiler" ``` ``` err := profiler.Start( profiler.WithService(""), profiler.WithEnv(""), profiler.WithVersion(""), profiler.WithTags(":", ":"), profiler.WithProfileTypes( profiler.CPUProfile, profiler.HeapProfile, // The profiles below are disabled by default to keep overhead // low, but can be enabled as needed. // profiler.BlockProfile, // profiler.MutexProfile, // profiler.GoroutineProfile, ), ) if err != nil { log.Fatal(err) } defer profiler.Stop() ``` Optional: Enable the [timeline feature](https://docs.datadoghq.com/profiler/connect_traces_and_profiles.md#span-execution-timeline-view), see [prerequisites](https://docs.datadoghq.com/profiler/connect_traces_and_profiles.md#prerequisites). 1. Optional: Set up [Source Code Integration](https://docs.datadoghq.com/integrations/guide/source-code-integration.md?tab=go) to connect your profiling data with your Git repositories. 1. After a couple of minutes, your profiles appear on the [Datadog APM > Profiler page](https://app.datadoghq.com/profiling). If they do not, see the [Troubleshooting](https://docs.datadoghq.com/profiler/profiler_troubleshooting/go.md) guide. {% alert level="info" %} By default, only the CPU and Heap profiles are enabled. Use [profiler.WithProfileTypes](https://pkg.go.dev/github.com/DataDog/dd-trace-go/v2/profiler#WithProfileTypes) and [profile types](https://pkg.go.dev/github.com/DataDog/dd-trace-go/v2/profiler#ProfileType). For legacy v1 documentation, view [profiler.WithProfileTypes](https://pkg.go.dev/gopkg.in/DataDog/dd-trace-go.v1/profiler#WithProfileTypes) to enable additional [profile types](https://pkg.go.dev/gopkg.in/DataDog/dd-trace-go.v1/profiler#ProfileType). {% /alert %} If you automatically instrument your Go application with [Orchestrion](https://docs.datadoghq.com/tracing/trace_collection/automatic_instrumentation/dd_libraries/go.md), it adds the continuous profiler code to your application. To enable the profiler at runtime, set the environment variable `DD_PROFILING_ENABLED=true`. ## Save up to 14% CPU in production with PGO{% #save-up-to-14-cpu-in-production-with-pgo %} Starting [Go 1.21](https://tip.golang.org/doc/go1.21), the Go compiler supports Profile-Guided Optimization (PGO). PGO enables additional optimizations on code identified as hot by CPU profiles of production workloads. This is compatible with Datadog Go Continuous Profiler and can be used for production builds. Follow [the PGO setup guide](https://docs.datadoghq.com/profiler/guide/save-cpu-in-production-with-go-pgo.md) to set it up. ## Configuration{% #configuration-3 %} You can set profiler parameters in code with these functions: | Function | Type | Description | | ----------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | WithService | String | The Datadog [service](https://docs.datadoghq.com/getting_started/tagging/unified_service_tagging.md) name, for example, `my-web-app`. | | WithEnv | String | The Datadog [environment](https://docs.datadoghq.com/getting_started/tagging/unified_service_tagging.md) name, for example, `production`. | | WithVersion | String | The version of your application. | | WithTags | List of strings | A list of tags to apply to an uploaded profile. Tags must be of the format `:`. | Alternatively you can set profiler configuration using environment variables: | Environment variable | Type | Description | | -------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------- | | `DD_ENV` | String | The [environment](https://docs.datadoghq.com/getting_started/tagging/unified_service_tagging.md) name, for example, `production`. | | `DD_SERVICE` | String | The [service](https://docs.datadoghq.com/getting_started/tagging/unified_service_tagging.md) name, for example, `web-backend`. | | `DD_VERSION` | String | The [version](https://docs.datadoghq.com/getting_started/tagging/unified_service_tagging.md) of your service. | | `DD_TAGS` | String | Tags to apply to an uploaded profile. Must be a list of `:` separated by commas such as: `layer:api,team:intake`. | ### Showing C function calls in CPU profiles{% #showing-c-function-calls-in-cpu-profiles %} By default, Go's CPU profiler only shows detailed information for Go code. If your program calls C code, the time spent running C code is reflected in the profile, but the call stacks only show Go function calls. To add detailed C function call information to CPU profiles, you may opt to use a library such as [ianlancetaylor/cgosymbolizer](https://pkg.go.dev/github.com/ianlancetaylor/cgosymbolizer#pkg-overview). To use this library: 1. Download the package: ``` go get github.com/ianlancetaylor/cgosymbolizer@latest ``` 1. Add the following import anywhere in your program: ``` import _ "github.com/ianlancetaylor/cgosymbolizer" ``` {% alert level="warning" %} This library is considered experimental. It can cause (infrequent) deadlocks in programs that use C++ exceptions, or that use libraries such as `tcmalloc`, which also collect call stacks. {% /alert %} {% /section %} {% section displayed-if="Language is Ruby" %} This section only applies to users who meet the following criteria: Language is Ruby The profiler is shipped within Datadog SDKs. If you are already using [APM to collect traces](https://docs.datadoghq.com/tracing/trace_collection.md) for your application, you can skip installing the library and go directly to enabling the profiler. ## Requirements{% #requirements-4 %} For a summary of the minimum and recommended runtime and tracer versions across all languages, read [Supported Language and Tracer Versions](https://docs.datadoghq.com/profiler/enabling/supported_versions.md). The Datadog Profiler requires Ruby 2.5+ (Ruby 3.2.3+ or later is recommended). JRuby and TruffleRuby are not supported. The following operating systems and architectures are supported: - Linux (GNU libc) x86-64, aarch64 - Alpine Linux (musl libc) x86-64, aarch64 Versions of the `datadog` gem older than 2.30 also need either the [`pkg-config`](https://www.freedesktop.org/wiki/Software/pkg-config/) or the [`pkgconf`](https://github.com/pkgconf/pkgconf) system utility installed. This is no longer needed on modern versions. Continuous Profiler is not supported on serverless platforms, such as AWS Lambda. Additionally, [Single Step APM Instrumentation](https://docs.datadoghq.com/tracing/trace_collection/automatic_instrumentation/single-step-apm.md) cannot be used to set up the Ruby Profiler. ## Installation{% #installation-4 %} To begin profiling applications: 1. Make sure Datadog Agent v6+ is installed and running. Datadog recommends using [Datadog Agent v7+](https://app.datadoghq.com/account/settings/agent/latest?platform=overview). 1. Add the `datadog` gem to your `Gemfile` or `gems.rb` file and install with `bundle install`: ``` gem 'datadog', '~> 2.30' ``` 1. Enable the profiler: {% tab title="Environment variables" %} ``` export DD_PROFILING_ENABLED=true export DD_ENV=prod export DD_SERVICE=my-web-app export DD_VERSION=1.0.3 ``` {% /tab %} {% tab title="In code" %} ``` Datadog.configure do |c| c.profiling.enabled = true c.env = 'prod' c.service = 'my-web-app' c.version = '1.0.3' end ``` Important alert (level: info): For Rails applications, create a `config/initializers/datadog.rb` file with the code configuration above. {% /tab %} 1. Add the `ddprofrb exec` command to your Ruby application start command: ``` bundle exec ddprofrb exec ruby myapp.rb ``` Rails example: ``` bundle exec ddprofrb exec bin/rails s ``` Important alert (level: info): If starting the application with `ddprofrb exec` is not an option (for example, when using the Phusion Passenger web server), you can alternatively start the profiler by adding the following to your application entry point (such as `config.ru`, for a web application): ``` require 'datadog/profiling/preload' ``` 1. Optional: Set up [Source Code Integration](https://docs.datadoghq.com/integrations/guide/source-code-integration.md?tab=ruby) to connect your profiling data with your Git repositories. 1. After a couple of minutes, your profiles appear on the [Datadog APM > Profiler page](https://app.datadoghq.com/profiling). If they do not, see the [Troubleshooting](https://docs.datadoghq.com/profiler/profiler_troubleshooting/ruby.md) guide. ## Configuration{% #configuration-4 %} These settings apply to the latest profiler release. You can configure the profiler using the following environment variables: | Environment variable | Type | Description | | --------------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `DD_PROFILING_ENABLED` | Boolean | If set to `true`, enables the profiler. Defaults to `false`. | | `DD_PROFILING_ALLOCATION_ENABLED` | Boolean | Set to `true` to enable allocation profiling. It requires the profiler to be enabled already. Defaults to `false`. | | `DD_PROFILING_MAX_FRAMES` | Integer | Maximum backtrace (stack) depth gathered by the profiler. Stacks deeper than this value get truncated. Defaults to `400`. | | `DD_PROFILING_EXPERIMENTAL_HEAP_ENABLED` | Boolean | Set to `true` to enable heap live objects profiling. It requires that allocation profiling is enabled as well. Defaults to `false`. | | `DD_PROFILING_EXPERIMENTAL_HEAP_SIZE_ENABLED` | Boolean | Set to `true` to enable heap live size profiling. It requires that heap live objects profiling is enabled as well. Defaults to the same value as `DD_PROFILING_EXPERIMENTAL_HEAP_ENABLED`. | | `DD_PROFILING_NO_SIGNALS_WORKAROUND_ENABLED` | Boolean | Automatically enabled when needed, can be used to force enable or disable this feature. See [Profiler Troubleshooting](https://docs.datadoghq.com/profiler/profiler_troubleshooting/ruby.md#unexpected-failures-or-errors-from-ruby-gems-that-use-native-extensions) for details. | | `DD_PROFILING_PREVIEW_OTEL_CONTEXT_ENABLED` | String | Set to `only` when using profiling directly with `opentelemetry-sdk`, or `true` for auto-detection of the correct context to read from. Defaults to `false`. | | `DD_ENV` | String | The [environment](https://docs.datadoghq.com/getting_started/tagging/unified_service_tagging.md) name, for example: `production`. | | `DD_SERVICE` | String | The [service](https://docs.datadoghq.com/getting_started/tagging/unified_service_tagging.md) name, for example, `web-backend`. | | `DD_VERSION` | String | The [version](https://docs.datadoghq.com/getting_started/tagging/unified_service_tagging.md) of your service. | | `DD_TAGS` | String | Tags to apply to an uploaded profile. Must be a list of `:` separated by commas such as: `layer:api, team:intake`. | Alternatively, you can set profiler parameters in code with these functions, inside a `Datadog.configure` block. Parameters provided in code take precedence over those provided as environment variables. | Environment variable | Type | Description | | ----------------------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `c.profiling.enabled` | Boolean | If set to `true`, enables the profiler. Defaults to `false`. | | `c.profiling.allocation_enabled` | Boolean | Set to `true` to enable allocation profiling. It requires the profiler to be enabled already. Defaults to `false`. | | `c.profiling.advanced.max_frames` | Integer | Maximum backtrace (stack) depth gathered by the profiler. Stacks deeper than this value get truncated. Defaults to `400`. | | `c.profiling.advanced.experimental_heap_enabled` | Boolean | Set to `true` to enable heap live objects profiling. It requires that allocation profiling is enabled as well. Defaults to `false`. | | `c.profiling.advanced.experimental_heap_size_enabled` | Boolean | Set to `true` to enable heap live size profiling. It requires that heap live objects profiling is enabled as well. Defaults to the same value as `experimental_heap_size_enabled`. | | `c.profiling.advanced.no_signals_workaround_enabled` | Boolean | Automatically enabled when needed, can be used to force enable or disable this feature. See [Profiler Troubleshooting](https://docs.datadoghq.com/profiler/profiler_troubleshooting/ruby.md#unexpected-failures-or-errors-from-ruby-gems-that-use-native-extensions) for details. | | `c.profiling.advanced.preview_otel_context_enabled` | String | Set to `only` when using profiling directly with `opentelemetry-sdk`, or `true` for auto-detection of the correct context to read from. Defaults to `false`. | | `c.env` | String | The [environment](https://docs.datadoghq.com/getting_started/tagging/unified_service_tagging.md) name, for example: `production`. | | `c.service` | String | The [service](https://docs.datadoghq.com/getting_started/tagging/unified_service_tagging.md) name, for example, `web-backend`. | | `c.version` | String | The [version](https://docs.datadoghq.com/getting_started/tagging/unified_service_tagging.md) of your service. | | `c.tags` | Hash | Tags to apply to an uploaded profile. | {% /section %} {% section displayed-if="Language is Node.js" %} This section only applies to users who meet the following criteria: Language is Node.js The profiler is shipped within Datadog SDKs. If you are already using [APM to collect traces](https://docs.datadoghq.com/tracing/trace_collection.md) for your application, you can skip installing the library and go directly to enabling the profiler. ## Requirements{% #requirements-5 %} For a summary of the minimum and recommended runtime and tracer versions across all languages, read [Supported Language and Tracer Versions](https://docs.datadoghq.com/profiler/enabling/supported_versions.md). The Datadog Profiler requires at least Node.js 18. Continuous Profiler support is in Preview for some serverless platforms, such as [AWS Lambda](https://docs.datadoghq.com/serverless/aws_lambda/profiling.md). Continuous Profiler support is in Preview for Google Cloud Run. ## Installation{% #installation-5 %} To begin profiling applications: 1. Make sure Datadog Agent v6+ is installed and running. Datadog recommends using [Datadog Agent v7+](https://app.datadoghq.com/account/settings/agent/latest?platform=overview). 1. Install `dd-trace`: ``` npm install --save dd-trace@latest ``` 1. Enable the profiler: {% tab title="Environment variables" %} ``` export DD_PROFILING_ENABLED=true export DD_ENV=prod export DD_SERVICE=my-web-app export DD_VERSION=1.0.3 ``` Important alert (level: info): If you're already using Datadog APM, you are already calling `init` and don't need to do so again. If you are not, make sure the SDK and the profiler are loaded together: ``` node -r dd-trace/init app.js ``` {% /tab %} {% tab title="In code" %} ``` const tracer = require('dd-trace').init({ profiling: true, env: 'prod', service: 'my-web-app', version: '1.0.3' }) ``` Important alert (level: info): If you're already using Datadog APM, you are already calling `init` and don't need to do so again. If you are not, make sure the SDK and the profiler are loaded together: ``` const tracer = require('dd-trace/init') ``` {% /tab %} 1. After a couple of minutes, your profiles appear on the [Datadog APM > Profiler page](https://app.datadoghq.com/profiling). If they do not, see the [Troubleshooting](https://docs.datadoghq.com/profiler/profiler_troubleshooting/nodejs.md) guide. 1. Optional: Set up [Source Code Integration](https://docs.datadoghq.com/integrations/guide/source-code-integration.md?tab=nodejs) to connect your profiling data with your Git repositories. 1. Optional: [Upload Source Maps](https://docs.datadoghq.com/real_user_monitoring/guide/upload-javascript-source-maps.md) (Preview). Join the Preview!: Profiler support for uploaded source maps is in Preview. If you deploy source maps with your application, the profiler reads them and produces mapped locations in profiles. Source maps in `.map` files and inline source maps are both supported. To reduce deployment sizes (for example, in serverless environments), you can choose not to deploy source maps and instead upload them to Datadog. Important alert (level: info): Uploaded source maps require dd-trace version 5.93.0 or newer. Your deployed source files must also contain the `@sourceMappingURL` annotation so the profiler knows to use the uploaded maps. {% /section %} {% section displayed-if="Language is .NET" %} This section only applies to users who meet the following criteria: Language is .NET The profiler is shipped within Datadog SDKs. If you are already using [APM to collect traces](https://docs.datadoghq.com/tracing/trace_collection.md) for your application, you can skip installing the library and go directly to enabling the profiler. ## Requirements{% #requirements-6 %} For a summary of the minimum and recommended runtime and tracer versions across all languages, read [Supported Language and Tracer Versions](https://docs.datadoghq.com/profiler/enabling/supported_versions.md). {% dl %} {% dt %} Supported operating systems for .NET Framework {% /dt %} {% dd %} Windows 10Windows Server starting from version 2012 {% /dd %} {% dt %} Supported operating systems for .NET Core and .NET 5+ {% /dt %} {% dd %} Linux with glibc 2.17+ (for example, CentOS 7+) and musl-based (Alpine)Windows 10Windows Server starting from version 2012 {% /dd %} {% dt %} Serverless {% /dt %} {% dd %} Azure App Service Windows and Linux - Web Apps only, Function Apps are not supported {% /dd %} {% dt %} Supported .NET runtimes (64-bit applications) {% /dt %} {% dd %} .NET Framework 4.6.1+.NET Core 2.1, 3.1.NET 5.NET 6.NET 7.NET 8.NET 9.NET 10 {% /dd %} {% /dl %} {% alert level="danger" %} For containers, **more than one core** is required. Read the [Troubleshooting documentation](https://docs.datadoghq.com/profiler/profiler_troubleshooting/dotnet.md#linux-containers) for more details. {% /alert %} {% dl %} {% dt %} Supported languages {% /dt %} {% dd %} Any language that targets the .NET runtime, such as C#, F#, and Visual Basic. {% /dd %} {% /dl %} The following profiling features are available in the following minimum versions of the `dd-trace-dotnet` library: | Feature | Required `dd-trace-dotnet` version | Required .NET Runtime versions | | ------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- | | Wall time profiling | 2.7.0+ | All supported runtime versions. | | CPU profiling | 2.15.0+ | All supported runtime versions. | | GC CPU consumption | 3.19.0+ | .NET 5+ | | Exceptions profiling | 2.31.0+ | All supported runtime versions. | | Allocations profiling | 3.12.0+ / 3.28.0+ | .NET Framework (requires Datadog Agent 7.51+ and 3.12.0+) / .NET 6+ (requires 2.18.0+ but Datadog recommends .NET10 with 3.28+). | | Lock Contention profiling | 2.49.0+ | .NET Framework (requires Datadog Agent 7.51+) and .NET 5+ | | Live heap profiling | 3.28.0+ | .NET 7+ but Datadog recommends .NET 10+. | | [Trace to Profiling integration](https://docs.datadoghq.com/profiler/connect_traces_and_profiles.md#identify-code-hotspots-in-slow-traces) | 2.30.0+ | All supported runtime versions. | | [Endpoint Profiling](https://docs.datadoghq.com/profiler/connect_traces_and_profiles.md#break-down-code-performance-by-api-endpoints) | 2.15.0+ | All supported runtime versions. | | Timeline | 2.30.0+ (and 3.19.0+ for outgoing HTTP requests longer than 50 ms in beta and thread start/end events) | All supported runtime versions (except .NET 5+ required for garbage collection details and .NET 7+ required for outgoing HTTP requests). | | [Memory Leak investigation](https://docs.datadoghq.com/profiler/guide/solve-memory-leaks.md) | 3.33.0+ | .NET 6+ (in preview) | - Allocations and Lock Contention profiling for .NET Framework requires that the Datadog Agent and the profiled applications are running on the same machine. - Due to a limitation of the .NET Framework, Allocations profiling does not show the size of the allocations. Instead, it only shows the count. - Allocations and Live Heap profiling are available in .NET 10. For other previous versions of .NET, the statistical distribution of allocations sampling might not be accurate, so expect larger objects to be represented more often - Continuous Profiler is not supported for AWS Lambda. - Continuous Profiler does not support ARM64. {% alert level="danger" %} Unlike APM, Continuous Profiler is not activated by default when the APM package is installed. You must explicitly enable it for the applications you want to profile. {% /alert %} ## Installation{% #installation-6 %} Make sure Datadog Agent v6+ is installed and running. Datadog recommends using [Datadog Agent v7+](https://app.datadoghq.com/account/settings/agent/latest?platform=overview). The profiler ships together with the SDK (beginning with v2.8.0), so if you are already using [APM to collect traces](https://docs.datadoghq.com/tracing/trace_collection.md) for your application, you can skip installing the library and go directly to Enabling the Profiler. Otherwise, install the profiler using the following steps, depending on your operating system. {% alert level="danger" %} Datadog's automatic instrumentation relies on the .NET CLR Profiling API. Since this API allows only one subscriber, run only one APM solution in your application environment. {% /alert %} You can install the Datadog .NET Profiler machine-wide so that any services on the machine can be instrumented, or you can install it on a per-application basis to allow developers to manage the instrumentation through the application's dependencies. To see machine-wide installation instructions, click the **Windows** or **Linux** tab. To see per-application installation instructions, click the **NuGet** tab. {% tab title="Linux with Single Step APM Instrumentation" %} 1. With [Single Step APM Instrumentation](https://docs.datadoghq.com/tracing/trace_collection/automatic_instrumentation/single-step-apm.md), there is nothing else to install. Go to Enabling the Profiler to see how to activate the profiler for an application. {% alert level="danger" %} If APM was already manually installed, you must uninstall it by removing the following environment variables: - `CORECLR_ENABLE_PROFILING` - `CORECLR_PROFILER` - `CORECLR_PROFILER_PATH` - The value that points to `Datadog.Linux.ApiWrapper.x64.so` in `LD_PRELOAD` For example, if you are setting these environment variables in your dockerfile for a service, you should remove them to avoid conflicts with Single Step Instrumentation. If these environment variables are still set, the corresponding previously installed version is silently used instead of the one installed with Single Step Instrumentation. {% /alert %} {% /tab %} {% tab title="Linux" %} To install the .NET Profiler machine-wide: 1. Download the latest [.NET Tracer package](https://github.com/DataDog/dd-trace-dotnet/releases) that supports your operating system and architecture. 1. Run one of the following commands to install the package and create the .NET log directory `/var/log/datadog/dotnet` with the appropriate permissions: {% dl %} {% dt %} Debian or Ubuntu {% /dt %} {% dd %} `sudo dpkg -i ./datadog-dotnet-apm__amd64.deb && sudo /opt/datadog/createLogPath.sh` {% /dd %} {% dt %} CentOS 7+ or Fedora {% /dt %} {% dd %} `sudo rpm -Uvh datadog-dotnet-apm-1.x86_64.rpm && sudo /opt/datadog/createLogPath.sh` {% /dd %} {% dt %} Alpine or other musl-based distributions {% /dt %} {% dd %} `sudo tar -C /opt/datadog -xzf datadog-dotnet-apm-musl.tar.gz && sudo sh /opt/datadog/createLogPath.sh` {% /dd %} {% dt %} Other distributions {% /dt %} {% dd %} `sudo tar -C /opt/datadog -xzf datadog-dotnet-apm-.tar.gz && sudo /opt/datadog/createLogPath.sh` {% /dd %} {% /dl %} {% /tab %} {% tab title="Windows" %} To install the .NET Profiler machine-wide: 1. Install or upgrade to the latest version, using the [.NET Monitoring MSI installer](https://github.com/DataDog/dd-trace-dotnet/releases). Continuous Profiler supports 64-bit Windows, so you need the file like `datadog-dotnet-apm--x64.msi`. 1. Run the installer with administrator privileges. {% /tab %} {% tab title="NuGet" %} {% alert level="danger" %} This installation does not instrument applications running in IIS. For applications running in IIS, follow the Windows machine-wide installation process. {% /alert %} To install the .NET Profiler per-application: 1. Add the `Datadog.Trace.Bundle` [NuGet package](https://www.nuget.org/packages/Datadog.Trace.Bundle) to your application. {% /tab %} {% tab title="Azure App Service" %} {% alert level="danger" %} Only Web Apps are supported. Functions are not supported. {% /alert %} To install the .NET Profiler per-webapp: 1. Install the Azure App Service Datadog APM Extension [for Windows](https://docs.datadoghq.com/serverless/azure_app_services/azure_app_services_windows.md?tab=net#installation) or use the [Linux setup](https://docs.datadoghq.com/serverless/azure_app_services/azure_app_services_linux.md?tab=nodenetphppython#setup) for your webapp. {% /tab %} ## Enabling the Profiler{% #enabling-the-profiler %} {% alert level="danger" %} Datadog does not recommend enabling the profiler at machine-level or for all IIS applications. If you have enabled it machine-wide, read the [Troubleshooting documentation](https://docs.datadoghq.com/profiler/profiler_troubleshooting.md?code-lang=dotnet#avoid-enabling-the-profiler-machine-wide) for information about reducing the overhead that is associated with enabling the profiler for all system applications. {% /alert %} {% tab title="Linux with Single Step APM Instrumentation" %} With [Single Step APM Instrumentation](https://docs.datadoghq.com/tracing/trace_collection/automatic_instrumentation/single-step-apm.md), only `DD_PROFILING_ENABLED` must be set to activate the profiler for an application. ``` DD_PROFILING_ENABLED=1 # other optional environment variables DD_ENV=production DD_VERSION=1.2.3 ``` Here are the supported values for `DD_PROFILING_ENABLED` environment variable: | Value | Description | | -------------- | --------------------------------------------------------------------------------------------------------------------- | | `1` or `true` | Activate the profiler. | | `Auto` | Activate the profiler if and only if (1) a trace has been created and (2) the application lasts more than 30 seconds. | | `0` or `false` | Disable the profiler. | {% alert level="info" %} The Auto value is aimed to avoid short lived processes without any trace. This feature is in Preview. {% /alert %} {% /tab %} {% tab title="Linux" %} Set the following required environment variables for automatic instrumentation to attach to your application: ``` CORECLR_ENABLE_PROFILING=1 CORECLR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8} CORECLR_PROFILER_PATH=/opt/datadog/Datadog.Trace.ClrProfiler.Native.so DD_DOTNET_TRACER_HOME=/opt/datadog LD_PRELOAD=/opt/datadog/continuousprofiler/Datadog.Linux.ApiWrapper.x64.so DD_PROFILING_ENABLED=1 # other optional environment variables DD_ENV=production DD_VERSION=1.2.3 ``` For standalone applications, manually restart the application as you normally would. Optional: Set up [Source Code Integration](https://docs.datadoghq.com/integrations/guide/source-code-integration.md?tab=net) to connect your profiling data with your Git repositories. A couple of minutes after you start your application, your profiles appear on the [Datadog APM > Profiler page](https://app.datadoghq.com/profiling). If they do not, see the [Troubleshooting](https://docs.datadoghq.com/profiler/profiler_troubleshooting/dotnet.md) guide. {% /tab %} {% tab title="Internet Information Services (IIS)" %} Set needed environment variables to configure and enable Profiler. To enable the Profiler for IIS applications, it is required to set the `DD_PROFILING_ENABLED` environment variable in the Registry under `HKLM\System\CurrentControlSet\Services\WAS` and `HKLM\System\CurrentControlSet\Services\W3SVC` nodes. {% alert level="info" %} Starting v2.14.0, you don't need to set `CORECLR_PROFILER` or `COR_PROFILER` if you installed the SDK using the MSI. {% /alert %} **With the Registry Editor:** In the Registry Editor, modify the multi-string value called `Environment` in the `HKLM\System\CurrentControlSet\Services\WAS` and `HKLM\System\CurrentControlSet\Services\W3SVC` nodes and set the value data as follows: For .NET Core and .NET 5+: ``` CORECLR_ENABLE_PROFILING=1 CORECLR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8} DD_PROFILING_ENABLED=1 # other optional environment variables DD_ENV=production DD_VERSION=1.2.3 ``` {% image source="https://docs.dd-static.net/images/tracing/setup/dotnet/RegistryEditorCore.607d51e028270e684d9497dd26ad2602.png?auto=format" alt="Using the Registry Editor to create environment variables for a .NET Core application in IIS" /%} For .NET Framework: ``` COR_ENABLE_PROFILING=1 COR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8} DD_PROFILING_ENABLED=1 # other optional environment variables DD_ENV=production DD_VERSION=1.2.3 ``` {% image source="https://docs.dd-static.net/images/tracing/setup/dotnet/RegistryEditorFramework.14a1d349e6a5d85fa5970fe210399182.png?auto=format" alt="Using the Registry Editor to create environment variables for a .NET Framework application in IIS" /%} The environment variables are applied for *all* IIS applications. Starting with IIS 10, you can set environment variables for each IIS application in the [`C:\Windows\System32\inetsrv\config\applicationhost.config` file](https://docs.microsoft.com/en-us/iis/get-started/planning-your-iis-architecture/introduction-to-applicationhostconfig). Read the [Microsoft documentation](https://docs.microsoft.com/en-us/iis/configuration/system.applicationhost/applicationpools/add/environmentvariables/) for more details. Completely stop and start IIS by running the following commands as an administrator: ``` net stop /y was net start w3svc ``` {% alert level="danger" %} Use `stop` and `start` commands. A reset or restart does not always work. {% /alert %} Optional: Set up [Source Code Integration](https://docs.datadoghq.com/integrations/guide/source-code-integration.md?tab=net) to connect your profiling data with your Git repositories. A couple of minutes after you start your application, your profiles appear on the [Datadog APM > Profiler page](https://app.datadoghq.com/profiling). If they do not, see the [Troubleshooting](https://docs.datadoghq.com/profiler/profiler_troubleshooting/dotnet.md) guide. {% /tab %} {% tab title="Windows services" %} Set needed environment variables to configure and enable Profiler. To enable the Profiler for your service, it is required to set the `DD_PROFILING_ENABLED` environment variable in the Registry key associated to the service. If the profiler is running alone (the SDK is deactivated), you can optionally add the `DD_SERVICE`, `DD_ENV` and `DD_VERSION` environment variables. {% alert level="info" %} Starting v2.14.0, you don't need to set `CORECLR_PROFILER` or `COR_PROFILER` if you installed the SDK using the MSI. {% /alert %} **With the Registry Editor:** In the Registry Editor, create a multi-string value called `Environment` in the `HKLM\System\CurrentControlSet\Services\MyService` key and set the value data to: For .NET Core and .NET 5+: ``` CORECLR_ENABLE_PROFILING=1 CORECLR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8} DD_PROFILING_ENABLED=1 DD_SERVICE=MyService # other optional environment variables DD_ENV=production DD_VERSION=1.2.3 ``` {% image source="https://docs.dd-static.net/images/tracing/setup/dotnet/RegistryEditorCore.607d51e028270e684d9497dd26ad2602.png?auto=format" alt="Using the Registry Editor to create environment variables for a Windows service" /%} For .NET Framework: ``` COR_ENABLE_PROFILING=1 COR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8} DD_PROFILING_ENABLED=1 DD_SERVICE=MyService # other optional environment variables DD_ENV=production DD_VERSION=1.2.3 ``` {% image source="https://docs.dd-static.net/images/tracing/setup/dotnet/RegistryEditorFramework.14a1d349e6a5d85fa5970fe210399182.png?auto=format" alt="Using the Registry Editor to create environment variables for a Windows service" /%} **With a PowerShell script:** For .NET Core and .NET 5+: ``` [string[]] $v = @( "CORECLR_ENABLE_PROFILING=1", "CORECLR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8}", "DD_PROFILING_ENABLED=1", "DD_SERVICE=MyService", "DD_ENV=production", "DD_VERSION=1.2.3" ) Set-ItemProperty HKLM:SYSTEM\CurrentControlSet\Services\MyService -Name Environment -Value $v ``` For .NET Framework: ``` [string[]] $v = @( "COR_ENABLE_PROFILING=1", "COR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8}", "DD_PROFILING_ENABLED=1", "DD_SERVICE=MyService", "DD_ENV=production", "DD_VERSION=1.2.3" ) Set-ItemProperty HKLM:SYSTEM\CurrentControlSet\Services\MyService -Name Environment -Value $v ``` Optional: Set up [Source Code Integration](https://docs.datadoghq.com/integrations/guide/source-code-integration.md?tab=net) to connect your profiling data with your Git repositories. A couple of minutes after you start your application, your profiles appear on the [Datadog APM > Profiler page](https://app.datadoghq.com/profiling). If they do not, see the [Troubleshooting](https://docs.datadoghq.com/profiler/profiler_troubleshooting/dotnet.md) guide. {% /tab %} {% tab title="Windows Standalone applications" %} {% alert level="info" %} Starting v2.14.0, you don't need to set `CORECLR_PROFILER` or `COR_PROFILER` if you installed the SDK using the MSI. {% /alert %} Set needed environment variables to configure and enable Profiler for a non-service application, such as console, ASP.NET (Core), Windows Forms, or WPF. To enable the Profiler for Standalone applications, it is required to set the `DD_PROFILING_ENABLED` environment variable. If the profiler is running alone (the SDK is deactivated), you can optionally set the `DD_SERVICE`, `DD_ENV` and `DD_VERSION` environment variables. The recommended approach is to create a batch file that sets these and starts the application, and run your application using the batch file. For .NET Core and .NET 5+: ``` SET CORECLR_ENABLE_PROFILING=1 SET CORECLR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8} SET DD_PROFILING_ENABLED=1 SET DD_SERVICE=MyService REM other optional environment variables SET DD_ENV=production SET DD_VERSION=1.2.3 REM start the application here ``` For .NET Framework: ``` SET COR_ENABLE_PROFILING=1 SET COR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8} SET DD_PROFILING_ENABLED=1 SET DD_SERVICE=MyService REM other optional environment variables SET DD_ENV=production SET DD_VERSION=1.2.3 REM start the application here ``` Optional: Set up [Source Code Integration](https://docs.datadoghq.com/integrations/guide/source-code-integration.md?tab=net) to connect your profiling data with your Git repositories. A couple of minutes after you start your application, your profiles appear on the [Datadog APM > Profiler page](https://app.datadoghq.com/profiling). If they do not, see the [Troubleshooting](https://docs.datadoghq.com/profiler/profiler_troubleshooting/dotnet.md) guide. {% /tab %} {% tab title="NuGet" %} Set the following required environment variables for profiling to attach to your application: ``` CORECLR_ENABLE_PROFILING=1 CORECLR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8} CORECLR_PROFILER_PATH= DD_PROFILING_ENABLED=1 LD_PRELOAD= DD_SERVICE=MyService # other optional environment variables DD_ENV=production DD_VERSION=1.2.3 DD_DOTNET_TRACER_HOME=/datadog ``` The value for the `` placeholder is the path to the directory containing the application's `.dll` files. The value for the `CORECLR_PROFILER_PATH` environment variable varies based on the system where the application is running: | Operating System and Process Architecture | CORECLR_PROFILER_PATH Value | LD_PRELOAD Value | | ----------------------------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------ | | Alpine Linux x64 | `/datadog/linux-musl-x64/Datadog.Trace.ClrProfiler.Native.so` | `/datadog/linux-musl-x64/Datadog.Linux.ApiWrapper.x64.so` | | Linux x64 | `/datadog/linux-x64/Datadog.Trace.ClrProfiler.Native.so` | `/datadog/linux-x64/Datadog.Linux.ApiWrapper.x64.so` | | Linux ARM64 | `/datadog/linux-arm64/Datadog.Trace.ClrProfiler.Native.so` | `/datadog/linux-arm64/Datadog.Linux.ApiWrapper.x64.so` | | Windows x64 | `\datadog\win-x64\Datadog.Trace.ClrProfiler.Native.dll` | N/A | | Windows x86 | `\datadog\win-x86\Datadog.Trace.ClrProfiler.Native.dll` | N/A | For Docker images running on Linux, configure the image to run the `createLogPath.sh` script: ``` RUN //datadog/createLogPath.sh ``` Docker examples are available in the [`dd-trace-dotnet` repository](https://github.com/DataDog/dd-trace-dotnet/tree/master/tracer/samples/NugetDeployment). For standalone applications, manually restart the application. {% /tab %} {% tab title="Azure App Service" %} Follow these installation guidelines ([Windows](https://docs.datadoghq.com/serverless/azure_app_services/azure_app_services_windows.md?tab=net#installation) or [Linux](https://docs.datadoghq.com/serverless/azure_app_services/azure_app_services_linux.md?tab=nodenetphppython#setup)) to set `DD_PROFILING_ENABLED=1` to enable the profiler. {% /tab %} ## Configuration{% #configuration-5 %} You can configure the profiler using the following environment variables. Most of these settings also apply to the Tracer configuration. Restart the application after any of these settings is changed. | Environment variable | Type | Description | | ----------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `DD_ENV` | String | The [environment](https://docs.datadoghq.com/getting_started/tagging/unified_service_tagging.md) name, for example, `production`. If not set, will be `unspecified-environment` | | `DD_SERVICE` | String | The [service](https://docs.datadoghq.com/getting_started/tagging/unified_service_tagging.md) name, for example, `web-backend`. If this is not specified, the .NET Profiler tries to determine the service name automatically from the application name (process entry assembly or process name). | | `DD_VERSION` | String | The [version](https://docs.datadoghq.com/getting_started/tagging/unified_service_tagging.md) of your service. If not set, will be `unspecified-version` | | `DD_TAGS` | String | Tags to apply to an uploaded profile. Must be a list of `:` separated by commas such as: `layer:api,team:intake`. | | `DD_AGENT_HOST` | String | Sets the host where profiles are sent (the host running the Agent). Can be a hostname or an IP address. Ignored if `DD_TRACE_AGENT_URL` is set. Defaults to `localhost`. | | `DD_TRACE_AGENT_PORT` | String | Sets the port where profiles are sent (the port where the Agent is listening for connections). Ignored if `DD_TRACE_AGENT_URL` is set. Defaults to `8126`. | | `DD_TRACE_AGENT_URL` | String | Sets the URL endpoint where profiles are sent. Overrides `DD_AGENT_HOST` and `DD_TRACE_AGENT_PORT` if set. Defaults to `http://:`. | | `DD_TRACE_DEBUG` | Boolean | Enables or disables debug logging (Could help in case of troubleshooting investigation). Valid values are: `true` or `false`. Defaults to `false`. | | `DD_PROFILING_LOG_DIR` | String | Sets the directory for .NET Profiler logs. Defaults to `%ProgramData%\Datadog .NET Tracer\logs\`. (Prior to v2.24, the default directory was `%ProgramData%\Datadog-APM\logs\`) | | `DD_PROFILING_ENABLED` | Boolean | If set to `true`, enables the .NET Profiler. Defaults to `false`. | | `DD_PROFILING_WALLTIME_ENABLED` | Boolean | If set to `false`, disables the Wall time profiling. Defaults to `true`. | | `DD_PROFILING_CPU_ENABLED` | Boolean | If set to `false`, disables the CPU profiling. Defaults to `true`. | | `DD_PROFILING_EXCEPTION_ENABLED` | Boolean | If set to `true`, enables Exception profiling. Defaults to `false`. | | `DD_PROFILING_ALLOCATION_ENABLED` | Boolean | If set to `true`, enables Allocation profiling (in Preview). Defaults to `false`. | | `DD_PROFILING_LOCK_ENABLED` | Boolean | If set to `true`, enables Lock Contention profiling. Defaults to `false`. | | `DD_PROFILING_HEAP_ENABLED` | Boolean | If set to `true`, enables Live Heap profiling (in Preview). Defaults to `false`. | | `DD_PROFILING_GC_ENABLED` | Boolean | If set to `false`, disables Garbage Collection profiling used in Timeline user interface. Defaults to `true`. | | `DD_PROFILING_HTTP_ENABLED` | Boolean | If set to `true`, enables outgoing HTTP request profiling used in Timeline user interface. Defaults to `false`. | | `DD_PROFILING_HEAPSNAPSHOT_ENABLED` | Boolean | If set to `true`, enables the regular generation of a heap snapshot when an increase in memory consumption is detected. This is used in the [Memory Leak user interface](https://docs.datadoghq.com/profiler/guide/solve-memory-leaks.md). Defaults to `false`. | {% alert level="danger" %} For IIS applications, you must set environment variables in the Registry (under `HKLM\System\CurrentControlSet\Services\WAS` and `HKLM\System\CurrentControlSet\Services\W3SVC` nodes) as shown in the Windows Service tab, above. The environment variables are applied for *all* IIS applications. Starting with IIS 10, you can set environment variables for each IIS application in the [`C:\Windows\System32\inetsrv\config\applicationhost.config` file](https://docs.microsoft.com/en-us/iis/get-started/planning-your-iis-architecture/introduction-to-applicationhostconfig). Read the [Microsoft documentation](https://docs.microsoft.com/en-us/iis/configuration/system.applicationhost/applicationpools/add/environmentvariables/) for more details. {% /alert %} {% /section %} {% section displayed-if="Language is PHP" %} This section only applies to users who meet the following criteria: Language is PHP ## Requirements{% #requirements-7 %} For a summary of the minimum and recommended runtime and tracer versions across all languages, read [Supported Language and Tracer Versions](https://docs.datadoghq.com/profiler/enabling/supported_versions.md). The Datadog Profiler requires at least PHP 7.1, on 64-bit Linux. PHP ZTS builds are supported since `dd-trace-php` version 0.99+, while PHP debug builds are **not** supported. {% tab title="GNU C Linux" %} An operating system with glibc 2.17 or newer is required. The following versions or newer meet this requirement: - CentOS 7 - Debian 8 - Ubuntu 14.04 {% alert level="info" %} The operating system versions above have all reached end of life (EOL), Datadog recommends running more recent versions. {% /alert %} {% /tab %} {% tab title="Alpine Linux" %} Version 3.13 or newer of Alpine Linux is required because the profiler is built against musl v1.2. Additionally, you need to install `libgcc_s` with: ``` apk add libgcc ``` {% /tab %} The following profiling features are available in the following minimum versions of the `dd-trace-php` library: | Feature | Required `dd-trace-php` version | | ------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------- | | [Trace to Profiling integration](https://docs.datadoghq.com/profiler/connect_traces_and_profiles.md#identify-code-hotspots-in-slow-traces) | 0.89.0+ | | [Endpoint Profiling](https://docs.datadoghq.com/profiler/connect_traces_and_profiles.md#break-down-code-performance-by-api-endpoints) | 0.79.0+ | | [Timeline](https://docs.datadoghq.com/profiler/profile_visualizations.md#timeline-view) | 0.98.0+ | | [Source Code Integration](https://docs.datadoghq.com/integrations/guide/source-code-integration.md?tab=php) | 1.13.0+ | Continuous Profiler is not supported on serverless platforms, such as AWS Lambda. ## Installation{% #installation-7 %} To begin profiling applications: 1. Make sure Datadog Agent v6+ is installed and running. Datadog recommends using [Datadog Agent v7+](https://app.datadoghq.com/account/settings/agent/latest?platform=overview). 1. Download and run the `datadog-setup.php` installer: ``` curl --proto '=https' --tlsv1.2 -sSfLO \ https://github.com/DataDog/dd-trace-php/releases/latest/download/datadog-setup.php ``` ``` php datadog-setup.php --enable-profiling --php-bin=all ``` This script is interactive and asks which of the detected PHP locations it should install to. At the end of the script, it outputs the non-interactive version of the command arguments for future use. 1. Configure the profiler: ``` php datadog-setup.php config set \ -d datadog.service=app-name \ -d datadog.env=prod \ -d datadog.version=1.3.2 ``` Apache, PHP-FPM, FrankenPHP, and other servers require a restart after changing the INI settings. See the [configuration docs](https://docs.datadoghq.com/tracing/trace_collection/library_config/php.md#environment-variable-configuration) for more INI settings. 1. Validate the profiler extension is loaded by running `php -v` and checking for `datadog-profiling` in the output: ``` PHP 8.4.13 (cli) (built: Sep 5 2025 11:52:54) (ZTS) Copyright (c) The PHP Group Zend Engine v4.4.13, Copyright (c) Zend Technologies with Zend OPcache v8.4.13, Copyright (c), by Zend Technologies with datadog-profiling v1.13.0, Copyright Datadog, by Datadog ``` 1. Optional: Set up [Source Code Integration](https://docs.datadoghq.com/integrations/guide/source-code-integration.md?tab=php) to connect your profiling data with your Git repositories. 1. After a couple of minutes, your profiles appear on the [Datadog APM > Profiler page](https://app.datadoghq.com/profiling). If they do not, see the [Troubleshooting](https://docs.datadoghq.com/profiler/profiler_troubleshooting/php.md) guide. {% /section %} {% section displayed-if="The selected value for Language is included in the given list: 'C, C++, Rust'" %} This section only applies to users who meet the following criteria: The selected value for Language is included in the given list: 'C, C++, Rust' {% alert level="danger" %} `ddprof` is in Preview. Datadog recommends evaluating the profiler in a non-sensitive environment before deploying in production. {% /alert %} The native profiler for compiled languages (`ddprof`) uses OS level APIs to collect profiling data. It is ideally suited for applications written in compiled languages, such as C, C++, or Rust. Profiles sent from `ddprof` show up under the *native* runtime in the Datadog web app. ## Requirements{% #requirements-8 %} For a summary of the minimum and recommended runtime and tracer versions across all languages, read [Supported Language and Tracer Versions](https://docs.datadoghq.com/profiler/enabling/supported_versions.md). {% dl %} {% dt %} Supported operating systems {% /dt %} {% dd %} Linux (glibc or musl) {% /dd %} {% dt %} Supported architecture {% /dt %} {% dd %} `amd64` or `arm64` processors {% /dd %} {% dt %} Serverless {% /dt %} {% dd %} `ddprof` is not supported on serverless platforms, such as AWS Lambda. {% /dd %} {% dt %} OS Settings {% /dt %} {% dd %} `perf_event_paranoid` kernel setting is 2 or less (see [Troubleshooting](https://docs.datadoghq.com/profiler/profiler_troubleshooting.md)) {% /dd %} {% dt %} Debugging information {% /dt %} {% dd %} Symbols should be available. The profiler cannot provide human-readable function names if the symbol table is stripped. {% /dd %} {% /dl %} ## Installation{% #installation-8 %} The profiler can be used either as a standalone executable or as a library. Skip to library installation instructions if you want to use it as a library. ### Standalone{% #standalone %} 1. Download the latest [`ddprof` release](https://github.com/DataDog/ddprof/releases). For example, here is one way to pull the latest release for an `amd64` (also known as `x86_64`) platform: ``` curl -Lo ddprof-linux.tar.xz https://github.com/DataDog/ddprof/releases/latest/download/ddprof-amd64-linux.tar.xz tar xvf ddprof-linux.tar.xz mv ddprof/bin/ddprof INSTALLATION_TARGET ``` Where `INSTALLATION_TARGET` specifies the location you'd like to store the `ddprof` binary. The examples that follow assume `INSTALLATION_TARGET` is set to `./ddprof`. Use `arm64` instead of `amd64` for `aarch64` platform. 1. Modify your service invocation to include the profiler. Your usual command is passed as the last arguments to the `ddprof` executable. {% tab title="Environment variables" %} ``` export DD_ENV=prod export DD_SERVICE=my-web-app export DD_VERSION=1.0.3 ./ddprof myapp --arg1 --arg2 ``` Important alert (level: info): If you usually launch your application using a shell builtin, for example: ``` exec myapp --arg1 --arg2 ``` Then you must invoke `ddprof` with that builtin instead: ``` export DD_ENV=prod export DD_SERVICE=my-web-app export DD_VERSION=1.0.3 exec ./ddprof myapp --arg1 --arg2 ``` {% /tab %} {% tab title="Parameters" %} ``` ./ddprof --environment prod --service my-web-app --service_version 1.0.3 myapp --arg1 --arg2 ``` Important alert (level: info): If you usually launch your application using a shell builtin, for example: ``` exec myapp --arg1 ``` Then you must invoke `ddprof` with that builtin instead: ``` exec ./ddprof --environment prod --service my-web-app --service_version 1.0.3 myapp --arg1 --arg2 ``` {% /tab %} 1. A couple of minutes after you start your application, your profiles appear on the [Datadog APM > Profiler page](https://app.datadoghq.com/profiling). If they do not, see the [Troubleshooting](https://docs.datadoghq.com/profiler/profiler_troubleshooting/ddprof.md) guide. ### Library{% #library %} The library exposes a C API. 1. Download a release of [ddprof](https://github.com/DataDog/ddprof/releases) with library support (v0.8.0 or later) and extract the tarball. For example: ``` curl -Lo ddprof-linux.tar.xz https://github.com/DataDog/ddprof/releases/latest/download/ddprof-amd64-linux.tar.xz tar xvf ddprof-linux.tar.xz --directory /tmp ``` 1. In your code, start the profiler using the `ddprof_start_profiling()` interface, defined in the `_dd_profiling.h_` header provided by the release. The profiler stops automatically when your program closes. To stop the profiler manually, use `ddprof_stop_profiling(ms)` with the `ms` parameter indicating the maximum block time of the function in milliseconds. Here is a standalone example (`profiler_demo.c`) in C: ``` #include #include "dd_profiling.h" int foo(void) { int n = 0; for (int i = 0; i < 1000; i++) { n += 1; } return n; } int main(void) { // Initialize and start the Datadog profiler. Uses agent defaults if not // specified setenv("DD_ENV", "prod", 1); setenv("DD_SERVICE", "c_testservice", 1); setenv("DD_VERSION", "1.0.3", 1); ddprof_start_profiling(); // Do some work for (int i = 0; i < 1e6; i++) { foo(); } return 0; } ``` 1. Pass the `include` and `lib` subdirectories of the extracted directory to your build system and link against `libdd_profiling`. For the above example: ``` gcc -I/tmp/ddprof/include -L/tmp/ddprof/lib profiler_demo.c -o profiler_demo -ldd_profiling ``` ### Deploying the shared library{% #deploying-the-shared-library %} The shared library must be present in the system's library search path. Otherwise, the application will fail to start. Using the example from before: ``` ./profiler_demo ./profiler_demo: error while loading shared libraries: libdd_profiling.so: cannot open shared object file: No such file or directory ``` Avoid this by linking against the static library. #### Installing the library{% #installing-the-library %} Add the library to the search path by copying it to any existing search directory. To find out what your search directories are, on Linux systems, run: ``` ld --verbose | grep SEARCH_DIR | tr -s ' ;' \\n ``` #### Appending a search directory{% #appending-a-search-directory %} Use the `LD_LIBRARY_PATH` environment variable to add additional search paths to the runtime linker. For example, using the directory layout from before: ``` export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/tmp/ddprof/lib ``` ## Configuration{% #configuration-6 %} The `environment`, `service`, and `service_version` settings are recommended, as they are used by the Profiling UI. See the [full list of parameters](https://github.com/DataDog/ddprof/blob/main/docs/Commands.md) or use the command line. ``` ddprof --help ``` ### Logging{% #logging %} You can configure logging to one of several endpoints: - `stdout` prints the logs to standard output stream (the default). - `stderr` prints the logs to the standard error stream. - `syslog` publishes the logs to syslog, attempting to adhere to the specification in RFC 3164. - `disable` disables the logs entirely. - Any other value is treated as a file path, with a leading `/` designating an absolute path. ### Global{% #global %} If you want to instrument all running process, you can try out the `--global` option. Global mode is intended for debug purposes. This requires elevated permissions. Depending on your setup, this can mean running as root, granting `CAP_PERFMON`, `CAP_SYSADMIN`, or setting `perf_event_paranoid` to `-1`. ``` ./ddprof --environment staging --global --service_version full-host-profile ``` For most configurations, this consists of all processes visible within the profiler's PID namespace. {% /section %} ## Not sure what to do next?{% #not-sure-what-to-do-next %} The [Getting Started with Profiler](https://docs.datadoghq.com/getting_started/profiler.md) guide takes a sample service with a performance problem and shows you how to use Continuous Profiler to understand and fix the problem. ## Further reading{% #further-reading %} - [Getting Started with Profiler](https://docs.datadoghq.com/getting_started/profiler.md) - [Learn more about available profile visualizations](https://docs.datadoghq.com/profiler/profile_visualizations.md) - [Fix problems you encounter while using the profiler](https://docs.datadoghq.com/profiler/profiler_troubleshooting.md) {% image source="https://docs.dd-static.net/images/tracing/setup/dotnet/RegistryEditorCore.607d51e028270e684d9497dd26ad2602.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/tracing/setup/dotnet/RegistryEditorCore.607d51e028270e684d9497dd26ad2602.png?auto=format&fit=max&w=850&dpr=2 2x" alt="" /%} {% image source="https://docs.dd-static.net/images/tracing/setup/dotnet/RegistryEditorFramework.14a1d349e6a5d85fa5970fe210399182.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/tracing/setup/dotnet/RegistryEditorFramework.14a1d349e6a5d85fa5970fe210399182.png?auto=format&fit=max&w=850&dpr=2 2x" alt="" /%}