The profiler is shipped within Datadog SDKs. 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.

• Verify your Python and SDK versions are compatible by reviewing the Python Compatibility Requirements.
• Some features depend on newer Python versions than the minimum required version for the SDK. For more details, read Profile Types.
• The installation requires pip version 18 or above.
• Continuous Profiler support is in Preview for some serverless platforms, such as AWS Lambda.

Installation

To begin profiling applications:

1. Make sure Datadog Agent v6+ is installed and running. Datadog recommends using Datadog Agent v7+.

2. Install ddtrace, which provides both tracing and profiling functionalities:

   Copy

   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:

   Copy

   apk install gcc musl-dev linux-headers
   

3. Enable the profiler and specify your service, environment, and version:

   Copy

   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:

   Copy

   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
   

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

5. After a couple of minutes, your profiles appear on the Datadog APM > Profiler page. If they do not, see the Troubleshooting guide.

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

You can configure the profiler using the environment variables.

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.

The profiler is shipped within Datadog SDKs. 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.

The Datadog Profiler requires one of the latest two major Go releases. These are the major Go releases supported by the Go project.

For the Trace to Profiling integration and Endpoint Profiling, use dd-trace-go version 1.51.0+.

Continuous Profiler is not supported on serverless platforms, such as AWS Lambda.

Installation

To begin profiling applications:

1. Make sure Datadog Agent v6+ is installed and running. Datadog recommends using Datadog Agent v7+.

2. Install dd-trace-go:

   Copy

   go get github.com/DataDog/dd-trace-go/v2/profiler
   

   If you are using v1 of the Go tracer, see the migration guide to upgrade to v2 and for all future updates and features.

3. Import the profiler and start it in your application:

   Copy

   import "github.com/DataDog/dd-trace-go/v2/profiler"
   

   Copy

   err := profiler.Start(
       profiler.WithService("<SERVICE_NAME>"),
       profiler.WithEnv("<ENVIRONMENT>"),
       profiler.WithVersion("<APPLICATION_VERSION>"),
       profiler.WithTags("<KEY1>:<VALUE1>", "<KEY2>:<VALUE2>"),
       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, see prerequisites.

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

5. After a couple of minutes, your profiles appear on the Datadog APM > Profiler page. If they do not, see the Troubleshooting guide.

If you automatically instrument your Go application with Orchestrion, 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

Starting Go 1.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 to set it up.

Configuration

You can set profiler parameters in code with these functions:

Alternatively you can set profiler configuration using environment variables:

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. To use this library:

1. Download the package:

   Copy

   go get github.com/ianlancetaylor/cgosymbolizer@latest
   

2. Add the following import anywhere in your program:

   Copy

   import _ "github.com/ianlancetaylor/cgosymbolizer"
   

The profiler is shipped within Datadog SDKs. 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.

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 or the 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 cannot be used to set up the Ruby Profiler.

Installation

To begin profiling applications:

1. Make sure Datadog Agent v6+ is installed and running. Datadog recommends using Datadog Agent v7+.

2. Add the datadog gem to your Gemfile or gems.rb file and install with bundle install:

   Copy

   gem 'datadog', '~> 2.30'
   

3. Enable the profiler:

   Copy

   export DD_PROFILING_ENABLED=true
   export DD_ENV=prod
   export DD_SERVICE=my-web-app
   export DD_VERSION=1.0.3
   

   Copy

   Datadog.configure do |c|
     c.profiling.enabled = true
     c.env = 'prod'
     c.service = 'my-web-app'
     c.version = '1.0.3'
   end
   

   For Rails applications, create a config/initializers/datadog.rb file with the code configuration above.

4. Add the ddprofrb exec command to your Ruby application start command:

   Copy

   bundle exec ddprofrb exec ruby myapp.rb
   

   Rails example:

   Copy

   bundle exec ddprofrb exec bin/rails s
   

   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):

   Copy

   require 'datadog/profiling/preload'
   

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

6. After a couple of minutes, your profiles appear on the Datadog APM > Profiler page. If they do not, see the Troubleshooting guide.

Configuration

These settings apply to the latest profiler release.

You can configure the profiler using the following environment variables:

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.

The profiler is shipped within Datadog SDKs. 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.

The Datadog Profiler requires at least Node.js 18.

Continuous Profiler support is in Preview for some serverless platforms, such as AWS Lambda.

Continuous Profiler support is in Preview for Google Cloud Run.

Installation

To begin profiling applications:

1. Make sure Datadog Agent v6+ is installed and running. Datadog recommends using Datadog Agent v7+.

2. Install dd-trace:

   Copy

   npm install --save dd-trace@latest
   

3. Enable the profiler:

   Copy

   export DD_PROFILING_ENABLED=true
   export DD_ENV=prod
   export DD_SERVICE=my-web-app
   export DD_VERSION=1.0.3
   

   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:

   Copy

   node -r dd-trace/init app.js
   

   Copy

   const tracer = require('dd-trace').init({
     profiling: true,
     env: 'prod',
     service: 'my-web-app',
     version: '1.0.3'
   })
   

   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:

   Copy

   const tracer = require('dd-trace/init')
   

4. After a couple of minutes, your profiles appear on the Datadog APM > Profiler page. If they do not, see the Troubleshooting guide.

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

6. Optional: Upload Source Maps (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.

   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.

The profiler is shipped within Datadog SDKs. 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.

Supported operating systems for .NET Framework

Windows 10
Windows Server starting from version 2012

Supported operating systems for .NET Core and .NET 5+

Linux with glibc 2.17+ (for example, CentOS 7+) and musl-based (Alpine)
Windows 10
Windows Server starting from version 2012

Serverless

Azure App Service Windows and Linux - Web Apps only, Function Apps are not supported

Supported .NET runtimes (64-bit applications)

.NET Framework 4.6.1+
.NET Core 2.1, 3.1
.NET 5
.NET 6
.NET 7
.NET 8
.NET 9
.NET 10

Supported languages

Any language that targets the .NET runtime, such as C#, F#, and Visual Basic.

The following profiling features are available in the following minimum versions of the dd-trace-dotnet library:

• 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.

Installation

Make sure Datadog Agent v6+ is installed and running. Datadog recommends using Datadog Agent v7+. The profiler ships together with the SDK (beginning with v2.8.0), so 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.

Otherwise, install the profiler using the following steps, depending on your operating system.

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.

Enabling the Profiler

With Single Step APM Instrumentation, only DD_PROFILING_ENABLED must be set to activate the profiler for an application.

Copy

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.

The Auto value is aimed to avoid short lived processes without any trace. This feature is in Preview.

Set the following required environment variables for automatic instrumentation to attach to your application:

Copy

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 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. If they do not, see the Troubleshooting guide.

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.

Starting v2.14.0, you don't need to set CORECLR_PROFILER or COR_PROFILER if you installed the SDK using the MSI.

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+:

Copy

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

For .NET Framework:

Copy

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

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. Read the Microsoft documentation for more details.

Completely stop and start IIS by running the following commands as an administrator:

Copy

net stop /y was
net start w3svc

Use stop and start commands. A reset or restart does not always work.

Optional: Set up Source Code Integration 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. If they do not, see the Troubleshooting guide.

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.

Starting v2.14.0, you don't need to set CORECLR_PROFILER or COR_PROFILER if you installed the SDK using the MSI.

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+:

Copy

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

For .NET Framework:

Copy

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

With a PowerShell script:

For .NET Core and .NET 5+:

Copy

[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:

Copy

[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 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. If they do not, see the Troubleshooting guide.

Starting v2.14.0, you don't need to set CORECLR_PROFILER or COR_PROFILER if you installed the SDK using the MSI.

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+:

Copy

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:

Copy

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 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. If they do not, see the Troubleshooting guide.

Set the following required environment variables for profiling to attach to your application:

Copy

CORECLR_ENABLE_PROFILING=1
CORECLR_PROFILER={846F5F1C-F9AE-4B07-969E-05C26BC060D8}
CORECLR_PROFILER_PATH=<System-dependent path>
DD_PROFILING_ENABLED=1
LD_PRELOAD=<System-dependent path>
DD_SERVICE=MyService

# other optional environment variables
DD_ENV=production
DD_VERSION=1.2.3
DD_DOTNET_TRACER_HOME=<APP_DIRECTORY>/datadog

The value for the <APP_DIRECTORY> 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	<APP_DIRECTORY>/datadog/linux-musl-x64/Datadog.Trace.ClrProfiler.Native.so	<APP_DIRECTORY>/datadog/linux-musl-x64/Datadog.Linux.ApiWrapper.x64.so
Linux x64	<APP_DIRECTORY>/datadog/linux-x64/Datadog.Trace.ClrProfiler.Native.so	<APP_DIRECTORY>/datadog/linux-x64/Datadog.Linux.ApiWrapper.x64.so
Linux ARM64	<APP_DIRECTORY>/datadog/linux-arm64/Datadog.Trace.ClrProfiler.Native.so	<APP_DIRECTORY>/datadog/linux-arm64/Datadog.Linux.ApiWrapper.x64.so
Windows x64	<APP_DIRECTORY>\datadog\win-x64\Datadog.Trace.ClrProfiler.Native.dll	N/A
Windows x86	<APP_DIRECTORY>\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:

Copy

RUN /<APP_DIRECTORY>/datadog/createLogPath.sh

Docker examples are available in the dd-trace-dotnet repository.

For standalone applications, manually restart the application.

Follow these installation guidelines (Windows or Linux) to set DD_PROFILING_ENABLED=1 to enable the profiler.

Configuration

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.

Requirements

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

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.

apk add libgcc

The following profiling features are available in the following minimum versions of the dd-trace-php library:

Continuous Profiler is not supported on serverless platforms, such as AWS Lambda.

Installation

To begin profiling applications:

1. Make sure Datadog Agent v6+ is installed and running. Datadog recommends using Datadog Agent v7+.

2. Download and run the datadog-setup.php installer:

   Copy

   curl --proto '=https' --tlsv1.2 -sSfLO \
     https://github.com/DataDog/dd-trace-php/releases/latest/download/datadog-setup.php
   

   Copy

   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.

3. Configure the profiler:

   Copy

   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 for more INI settings.

4. Validate the profiler extension is loaded by running php -v and checking for datadog-profiling in the output:

   Copy

   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
   

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

6. After a couple of minutes, your profiles appear on the Datadog APM > Profiler page. If they do not, see the Troubleshooting guide.

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

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

Supported operating systems

Linux (glibc or musl)

Supported architecture

amd64 or arm64 processors

Serverless

ddprof is not supported on serverless platforms, such as AWS Lambda.

OS Settings

perf_event_paranoid kernel setting is 2 or less (see Troubleshooting)

Debugging information

Symbols should be available. The profiler cannot provide human-readable function names if the symbol table is stripped.

Installation

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

1. Download the latest ddprof release. For example, here is one way to pull the latest release for an amd64 (also known as x86_64) platform:

   Copy

   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.

2. Modify your service invocation to include the profiler. Your usual command is passed as the last arguments to the ddprof executable.

   Copy

   export DD_ENV=prod
   export DD_SERVICE=my-web-app
   export DD_VERSION=1.0.3
   ./ddprof myapp --arg1 --arg2
   

   If you usually launch your application using a shell builtin, for example:

   Copy

   exec myapp --arg1 --arg2
   

   Then you must invoke ddprof with that builtin instead:

   Copy

   export DD_ENV=prod
   export DD_SERVICE=my-web-app
   export DD_VERSION=1.0.3
   exec ./ddprof myapp --arg1 --arg2
   

   Copy

   ./ddprof --environment prod --service my-web-app --service_version 1.0.3 myapp --arg1 --arg2
   

   If you usually launch your application using a shell builtin, for example:

   Copy

   exec myapp --arg1
   

   Then you must invoke ddprof with that builtin instead:

   Copy

   exec ./ddprof --environment prod --service my-web-app --service_version 1.0.3 myapp --arg1 --arg2
   

3. A couple of minutes after you start your application, your profiles appear on the Datadog APM > Profiler page. If they do not, see the Troubleshooting guide.

Library

The library exposes a C API.

1. Download a release of ddprof with library support (v0.8.0 or later) and extract the tarball. For example:

   Copy

   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
   

2. 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:

   Copy

   #include <stdlib.h>
   #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;
   }
   

3. Pass the include and lib subdirectories of the extracted directory to your build system and link against libdd_profiling. For the above example:

   Copy

   gcc -I/tmp/ddprof/include -L/tmp/ddprof/lib profiler_demo.c -o profiler_demo -ldd_profiling
   

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

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

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

The environment, service, and service_version settings are recommended, as they are used by the Profiling UI.

See the full list of parameters or use the command line.

ddprof --help

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

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.