Enabling the Ruby Profiler
The profiler is shipped within Datadog tracing libraries. If you are already using APM to collect traces for your application, you can skip installing the library and go directly to enabling the profiler.
Requirements
For a summary of the minimum and recommended runtime and tracer versions across all languages, read Supported Language and Tracer Versions.
The Datadog Profiler requires Ruby 2.5+ (Ruby 3.1+ 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
You also need either the pkg-config
or the pkgconf
system utility installed.
This utility is available on the software repositories of most Linux distributions. For example:
- The
pkg-config
package is available for Homebrew, and Debian- and Ubuntu-based Linux - The
pkgconf
package is available for Arch- and Alpine-based Linux - The
pkgconf-pkg-config
package is available for Fedora- and Red-Hat-based Linux
Continuous Profiler is not supported on serverless platforms, such as AWS Lambda.
Installation
To begin profiling applications:
Ensure Datadog Agent v6+ is installed and running. Datadog recommends using Datadog Agent v7+.
Add the datadog
gem to your Gemfile
or gems.rb
file:
Install the gems with bundle install
.
Enable the profiler:
export DD_PROFILING_ENABLED=true
export DD_ENV=prod
export DD_SERVICE=my-web-app
export DD_VERSION=1.0.3
Datadog.configure do |c|
c.profiling.enabled = true
c.env = 'prod'
c.service = 'my-web-app'
c.version = '1.0.3'
end
Note: For Rails applications, create a config/initializers/datadog.rb
file with the code configuration above.
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
If you’re running a version of the gem older than 1.21.0, replace ddprofrb exec
with ddtracerb exec
.
Note
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'
Optional: Set up Source Code Integration to connect your profiling data with your Git repositories.
A minute or two after starting your Ruby application, your profiles will show up on the Datadog APM > Profiler page.
Configuration
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_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 false . |
DD_PROFILING_NO_SIGNALS_WORKAROUND_ENABLED | Boolean | Automatically enabled when needed, can be used to force enable or disable this feature. See Profiler Troubleshooting 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 name, for example: production . |
DD_SERVICE | String | The service name, for example, web-backend . |
DD_VERSION | String | The version of your service. |
DD_TAGS | String | Tags to apply to an uploaded profile. Must be a list of <key>:<value> 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:
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.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 false . |
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 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 name, for example: production . |
c.service | String | The service name, for example, web-backend . |
c.version | String | The version of your service. |
c.tags | Hash | Tags to apply to an uploaded profile. |
Not sure what to do next?
The Getting Started with Profiler guide takes a sample service with a performance problem and shows you how to use Continuous Profiler to understand and fix the problem.
Further Reading
Additional helpful documentation, links, and articles: