--- title: Enabling the Ruby Profiler description: Datadog, the leading service for cloud-scale monitoring. breadcrumbs: >- Docs > Continuous Profiler > Enabling the Profiler > Enabling the Ruby Profiler --- # Enabling the Ruby Profiler The profiler is shipped within Datadog tracing libraries. If you are already using [APM to collect traces](https://docs.datadoghq.com/tracing/trace_collection/) 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/). 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/) cannot be used to set up the Ruby Profiler. ## Installation{% #installation %} To begin profiling applications: 1. Ensure 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: ```ruby gem 'datadog', '~> 2.30' ``` 1. Install the gems with `bundle install`. 1. Enable the profiler using **one** of the following approaches: {% tab title="Environment variables" %} ```shell 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" %} ```ruby 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. {% /tab %} 1. Add the `ddprofrb exec` command to your Ruby application start command: ```shell bundle exec ddprofrb exec ruby myapp.rb ``` Rails example: ```shell bundle exec ddprofrb exec bin/rails s ``` **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): ```ruby require 'datadog/profiling/preload' ``` 1. Optional: Set up [Source Code Integration](https://docs.datadoghq.com/integrations/guide/source-code-integration/?tab=ruby) to connect your profiling data with your Git repositories. 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, refer to the [Troubleshooting](https://docs.datadoghq.com/profiler/profiler_troubleshooting/ruby/) guide. ## Configuration{% #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_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/#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) name, for example: `production`. | | `DD_SERVICE` | String | The [service](https://docs.datadoghq.com/getting_started/tagging/unified_service_tagging) name, for example, `web-backend`. | | `DD_VERSION` | String | The [version](https://docs.datadoghq.com/getting_started/tagging/unified_service_tagging) 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. Note that 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/#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) name, for example: `production`. | | `c.service` | String | The [service](https://docs.datadoghq.com/getting_started/tagging/unified_service_tagging) name, for example, `web-backend`. | | `c.version` | String | The [version](https://docs.datadoghq.com/getting_started/tagging/unified_service_tagging) of your service. | | `c.tags` | Hash | Tags to apply to an uploaded profile. | ## Not sure what to do next?{% #not-sure-what-to-do-next %} The [Getting Started with Profiler](https://docs.datadoghq.com/getting_started/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{% #further-reading %} - [Getting Started with Profiler](https://docs.datadoghq.com/getting_started/profiler) - [Learn more about available profile visualizations](https://docs.datadoghq.com/profiler/profile_visualizations) - [Fix problems you encounter while using the profiler](https://docs.datadoghq.com/profiler/profiler_troubleshooting/ruby) - [Analyze Ruby code performance with Datadog Continuous Profiler](https://www.datadoghq.com/blog/ruby-profiling-datadog-continuous-profiler/)