New announcements for Serverless, Network, RUM, and more from Dash!

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 the additional documentation for tracing Docker applications or Kubernetes 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:

    require 'ddtrace'
    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.

Change Agent Hostname

Configure your application level tracers to submit traces to a custom Agent hostname:

The Ruby Tracing Module automatically looks for and initializes with the ENV variables DD_AGENT_HOST and DD_TRACE_AGENT_PORT

Datadog.configure do |c|
  c.tracer hostname: ENV['DD_AGENT_HOST'],
           port: ENV['DD_TRACE_AGENT_PORT']
end

Compatibility

Integrations

Interpreter Compatibility

Ruby APM includes support for the following Ruby interpreters:

TypeVersionSupport type
MRI1.9.1Deprecated
1.9.3Deprecated
2.0Fully Supported
2.1Fully Supported
2.2Fully Supported
2.3Fully Supported
2.4Fully Supported
2.5Fully Supported
JRuby9.1.5Experimental

Web Server Compatibility

Ruby APM includes support for the following web servers:

TypeVersionSupport type
Puma2.16+ / 3.6+Fully Supported
Unicorn4.8+ / 5.1+Fully Supported
Passenger5.0+Fully Supported

Library Compatibility

Ruby APM includes support for the following libraries and frameworks:

NameVersions SupportedSupport typeHow to configure
Active Model Serializers>= 0.9Fully SupportedLink
Active Record>= 3.2, < 6.0Fully SupportedLink
AWS>= 2.0Fully SupportedLink
Concurrent Ruby>= 0.9Fully SupportedLink
Dalli>= 2.7Fully SupportedLink
DelayedJob>= 4.1Fully SupportedLink
Elastic Search>= 6.0Fully SupportedLink
Excon>= 0.62Fully SupportedLink
Faraday>= 0.14Fully SupportedLink
Grape>= 1.0Fully SupportedLink
GraphQL>= 1.7.9Fully SupportedLink
gRPC>= 1.10Fully SupportedLink
MongoDB>= 2.0Fully SupportedLink
MySQL2>= 0.3.10Fully SupportedLink
Net/HTTP(Any Supported Ruby)Fully SupportedLink
Racecar>= 0.3.5Fully SupportedLink
Rack>= 1.4.7Fully SupportedLink
Rails>= 3.2, < 6.0Fully SupportedLink
Rake>= 12.0Fully SupportedLink
Redis>= 3.2, < 4.0Fully SupportedLink
Resque>= 1.0, < 2.0Fully SupportedLink
RestClient>= 1.8Fully SupportedLink
Sequel>= 3.41Fully SupportedLink
Shoryuken>= 4.0.2Fully SupportedLink
Sidekiq>= 4.0Fully SupportedLink
Sinatra>= 1.4.5Fully SupportedLink
Sucker Punch>= 2.0Fully SupportedLink

Fully Supported support indicates all tracer features are available.

Experimental indicates most features should be available, but unverified.

Deprecated indicates support will be removed in a future release.

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