The Service Map for APM is here!

Tracing Ruby Applications

Installation and Getting Started

For configuration instructions, and details about using the API, check out Datadog’s API documentation and gem documentation.

For descriptions of terminology used in APM, take a look at the official documentation.

For details about contributing, check out the development guide.

Setup the Datadog Agent

The Ruby APM tracer sends trace data through the Datadog Agent.

Install and configure the Datadog Agent, see additional documentation for tracing Docker applications.

Quickstart for Rails applications

  1. Add the ddtrace gem to your Gemfile:

    source 'https://rubygems.org'
    gem 'ddtrace'
  2. Install the gem with bundle install

  3. Create a config/initializers/datadog.rb file containing:

    Datadog.configure do |c|
      # This will activate auto-instrumentation for Rails
      c.use :rails
    end

    You can also activate additional integrations here (see Integration instrumentation)

Quickstart for other Ruby applications

  1. Install the gem with gem install ddtrace
  2. Add a configuration block to your Ruby application:

    require 'ddtrace'
    Datadog.configure do |c|
      # Configure the tracer here.
      # Activate integrations, change tracer settings, etc...
      # By default without additional configuration, nothing will be traced.
    end
  3. Add or activate instrumentation by doing either of the following:

    1. Activate integration instrumentation (see Integration instrumentation)
    2. Add manual instrumentation around your code (see Manual instrumentation)

Final steps for installation

After setting up, your services will appear on the APM services page within a few minutes. Learn more about using the APM UI.

Compatibility

Integrations

Interpreter Compatibility

Ruby APM includes support for the following Ruby interpreters:

Type Version Support type
MRI 1.9.1 Experimental
1.9.3 Fully Supported
2.0 Fully Supported
2.1 Fully Supported
2.2 Fully Supported
2.3 Fully Supported
2.4 Fully Supported
2.5 Fully Supported
JRuby 9.1.5 Experimental

Web Server Compatibility

Ruby APM includes support for the following web servers:

Type Version Support type
Puma 2.16+ / 3.6+ Fully Supported
Unicorn 4.8+ / 5.1+ Fully Supported
Passenger 5.0+ Fully Supported

Library Compatibility

Ruby APM includes support for the following libraries and frameworks:

Name Versions Supported Support type How to configure
Active Record >= 3.2, < 6.0 Fully Supported Link
AWS >= 2.0 Fully Supported Link
Dalli >= 2.7 Fully Supported Link
DelayedJob >= 4.1 Fully Supported Link
Elastic Search >= 6.0 Fully Supported Link
Excon >= 0.62 Fully Supported Link
Faraday >= 0.14 Fully Supported Link
gRPC >= 1.10 Fully Supported Link
Grape >= 1.0 Fully Supported Link
GraphQL >= 1.7.9 Fully Supported Link
MongoDB >= 2.0, < 2.5 Fully Supported Link
MySQL2 >= 0.5 Fully Supported Link
Net/HTTP (Any Supported Ruby) Fully Supported Link
Racecar >= 0.3.5 Fully Supported Link
Rack >= 1.4.7 Fully Supported Link
Rails >= 3.2, < 6.0 Fully Supported Link
Rake >= 12.0 Fully Supported Link
Redis >= 3.2, < 4.0 Fully Supported Link
Resque >= 1.0, < 2.0 Fully Supported Link
RestClient >= 1.8 Fully Supported Link
Sequel >= 3.41 Fully Supported Link
Sidekiq >= 4.0 Fully Supported Link
Sinatra >= 1.4.5 Fully Supported Link
Sucker Punch >= 2.0 Fully Supported Link

Fully Supported support indicates all tracer features are available.

Experimental indicates most features should be available, but unverified.

Configuration

To activate more advanced features, change tracer behavior, or trace additional code, you must add additional configuration.

Integration instrumentation

APM provides out-of-the-box support for many popular integrations. Although none are active by default, you can easily activate them in Datadog.configure.

Example

require 'ddtrace'
require 'sinatra'
require 'active_record'

Datadog.configure do |c|
  c.use :sinatra
  c.use :active_record
end

# Now write your code naturally, it's traced automatically.
get '/home' do
  @posts = Posts.order(created_at: :desc).limit(10)
  erb :index
end

For list of available integrations, see Library compatibility.

Tracer settings

Enabling/disabling

Tracing is enabled by default. To disable it (i.e. in a test environment):

Datadog.configure do |c|
  c.tracer enabled: false
end

For more tracer settings, check out the API documentation.

Processing pipeline

The processing pipeline allows you to modify traces before they are sent to the Agent. This can be useful for customizing trace content or removing unwanted traces.

It provides filtering for removing spans that match certain criteria, and processing for modifying spans.

For more details about how to activate and configure the processing pipeline, check out the API documentation.

Further reading