---
title: Enable Dynamic Instrumentation for Ruby
description: >-
  Set up Dynamic Instrumentation for Ruby applications to add probes and capture
  data without code changes.
breadcrumbs: >-
  Docs > APM > Application Instrumentation > Dynamic Instrumentation > Enabling
  Dynamic Instrumentation > Enable Dynamic Instrumentation for Ruby
---

# Enable Dynamic Instrumentation for Ruby

{% callout %}
# Important note for users on the following Datadog sites: app.ddog-gov.com

{% alert level="danger" %}
This product is not supported for your selected [Datadog site](https://docs.datadoghq.com/getting_started/site). ().
{% /alert %}

{% /callout %}

{% callout %}
##### Limited Availability

Dynamic Instrumentation for Ruby is in Limited Availability and may not be available for your organization. Request access to join the waiting list.Note: Some limitations apply.

[Request Access](https://www.datadoghq.com/product-preview/live-debugger/)
{% /callout %}

Dynamic Instrumentation is a feature of the Datadog tracing library that lets you add instrumentation to your application at runtime without code changes or redeployments. Follow these instructions to set up Dynamic Instrumentation for Ruby.

## Prerequisites{% #prerequisites %}

Before you begin, review the [Dynamic Instrumentation prerequisites](https://docs.datadoghq.com/dynamic_instrumentation/#prerequisites). Ruby applications also require:

- **Tracing library**: [`ddtrace`](https://github.com/DataDog/dd-trace-rb) version 2.9.0 or higher. See the [installation instructions](https://docs.datadoghq.com/tracing/trace_collection/dd_libraries/ruby/) for setup details.
- **Ruby version**: Ruby 2.6 or higher.
- **Ruby implementation**: Only MRI (CRuby) is supported. JRuby and other Ruby implementations are not supported.
- **Web framework**: Only Rack-based applications are supported (including Rails, Sinatra, and other Rack-compatible frameworks). Background processes and jobs (including Sidekiq, Resque, etc.) are not supported.
- **Environment**: `RAILS_ENV` or `RACK_ENV` must be set to `production`. Development environments are not supported.

## Installation{% #installation %}

1. If you don't already have APM enabled, in your Agent configuration, set the `DD_APM_ENABLED` environment variable to `true` and listening to the port `8126/TCP`.
1. Run your service with Dynamic Instrumentation enabled by setting the `DD_DYNAMIC_INSTRUMENTATION_ENABLED` environment variable to `true`. Specify `DD_SERVICE`, `DD_ENV`, and `DD_VERSION` Unified Service Tags so you can filter and group your instrumentations and target active clients across these dimensions.
1. After starting your service with Dynamic Instrumentation enabled, you can start using Dynamic Instrumentation on the [APM > Dynamic Instrumentation page](https://app.datadoghq.com/dynamic-instrumentation).

**Note**: Dynamic Instrumentation initializes when the application processes its first HTTP request. Ensure your application receives at least one request after startup before creating probes.

## Configuration{% #configuration %}

Configure Dynamic Instrumentation using the following environment variables:

| Environment variable                 | Type    | Description                                                                                                                    |
| ------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `DD_DYNAMIC_INSTRUMENTATION_ENABLED` | Boolean | Set to `true` to enable Dynamic Instrumentation.                                                                               |
| `DD_SERVICE`                         | String  | The [service](https://docs.datadoghq.com/getting_started/tagging/unified_service_tagging) name, for example, `web-backend`.    |
| `DD_ENV`                             | String  | The [environment](https://docs.datadoghq.com/getting_started/tagging/unified_service_tagging) name, for example, `production`. |
| `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 produced data. Must be a list of `<key>:<value>` separated by commas such as: `layer:api,team:intake`.        |

## What to do next{% #what-to-do-next %}

See [Dynamic Instrumentation](https://docs.datadoghq.com/dynamic_instrumentation/) for information about adding instrumentations and browsing and indexing the data.

## Ruby-specific considerations{% #ruby-specific-considerations %}

### Instrumentable code{% #instrumentable-code %}

Line probes can only be placed on executable lines of code. The following example shows which lines can be targeted:

```ruby
def example_method(param)    # Cannot instrument (method definition)
  if param == 1              # Can instrument
    result = "yes"           # Can instrument
  else                       # Cannot instrument
    result = "no"            # Can instrument
  end                        # Cannot instrument
  result                     # Can instrument
end                          # Can instrument (method exit)
```

Lines that cannot be instrumented include method definition lines (`def`), `else`/`elsif` clauses, most `end` keywords (except the final `end` of a method), comment-only lines, and empty lines.

### Expression language instance variable conflicts{% #expression-language-instance-variable-conflicts %}

Ruby's use of `@` for instance variables creates conflicts with Dynamic Instrumentation's expression language special variables. The following variable names are reserved and cannot be accessed if used as instance variables in your Ruby code:

- `@return` - The return value of the method
- `@duration` - Method execution duration
- `@exception` - Any exception raised by the method
- `@it` - Current item in collection operations
- `@key` - Current key in hash operations
- `@value` - Current value in hash operations

If your code uses instance variables with these names, rename them to use Dynamic Instrumentation expressions that reference them.

### Code loading timing{% #code-loading-timing %}

Dynamic Instrumentation tracks code as it loads. For line probes to work correctly:

- Files must be loaded **after** the Datadog tracer initializes
- Code loaded before the tracer starts cannot be instrumented with line probes
- Method probes can still work for classes defined before tracking starts
- Best practice: Ensure the tracer initializes early in your application boot process

## Supported features{% #supported-features %}

- [Dynamic Logs](https://docs.datadoghq.com/dynamic_instrumentation/#creating-log-probes) (log probes)
- Line probes (capture variables at a specific line)
- Method probes (capture method entry and exit)
- Probe conditions using [Expression Language](https://docs.datadoghq.com/dynamic_instrumentation/expression-language/)
- Message templates using [Expression Language](https://docs.datadoghq.com/dynamic_instrumentation/expression-language/)
- [PII redaction](https://docs.datadoghq.com/dynamic_instrumentation/sensitive-data-scrubbing/#custom-identifier-redaction)
- [Source code integration](https://docs.datadoghq.com/integrations/guide/source-code-integration/?tab=ruby)

## Limitations{% #limitations %}

The following features available in other languages are not supported for Ruby:

- Dynamic Metrics
- Dynamic Spans
- Dynamic Span Tags
- Local variable capture for method probes (use line probes inside the method as a workaround)

## Further reading{% #further-reading %}

- [Getting Started with Datadog Agent](https://docs.datadoghq.com/agent)