Logging is here!

Tracing Ruby Applications

Getting started

For configuration instructions, and details about using the API, check out our 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.

Installation

The following steps will help you quickly start tracing your Ruby application.

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.

Configuration

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

Manual instrumentation

If you aren’t using supported library instrumentation (see Library compatibility), you may want to to manually instrument your code. Adding tracing to your code is easy using the Datadog.tracer.trace method, which you can wrap around any Ruby code.

Example

get '/posts' do
  Datadog.tracer.trace('web.request', service: 'my-blog', resource: 'GET /posts') do |span|
    # Trace the activerecord call
    Datadog.tracer.trace('posts.fetch') do
      @posts = Posts.order(created_at: :desc).limit(10)
    end

    # Add some APM tags
    span.set_tag('http.method', request.request_method)
    span.set_tag('posts.count', @posts.length)

    # Trace the template rendering
    Datadog.tracer.trace('template.render') do
      erb :index
    end
  end
end

For more details about manual instrumentation, check out the API documentation.

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

Debug mode

Debug mode is disabled by default. To enable:

Datadog.configure do |c|
  c.tracer debug: true
end

For more tracer settings, check out the API documentation.

Priority sampling

Priority sampling allows you to configure which traces are most important and should be kept after sampling.

Priority sampling is disabled by default. For more details about how to activate and configure priority sampling, check out the API documentation.

Distributed tracing

Distributed tracing allows you to propagate a single trace across multiple services, so you can see performance end-to-end.

Distributed tracing is disabled by default. For more details about how to activate and configure distributed tracing, 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.

Compatibility

Interpreter Compatibility

Ruby APM includes support for the following Ruby interpreters:


Type Documentation Version Support type
MRI https://www.ruby-lang.org/ 1.9.1 Experimental
1.9.3 Full
2.0 Full
2.1 Full
2.2 Full
2.3 Full
2.4 Full
JRuby http://jruby.org/ 9.1.5 Experimental

Full support indicates all tracer features are available.

Experimental indicates most features should be available, but unverified.

Web server compatibility

Ruby APM includes support for the following web servers:


Type Documentation Version Support type
Puma http://puma.io/ 2.16+ / 3.6+ Full
Unicorn https://bogomips.org/unicorn/ 4.8+ / 5.1+ Full
Passenger https://www.phusionpassenger.com/ 5.0+ Full

Library compatibility

Ruby APM includes support for the following libraries and frameworks:


Library Library Documentation Datadog Instrumentation Documentation
ActiveRecord https://github.com/rails/rails/tree/master/activerecord https://github.com/DataDog/dd-trace-rb/blob/master/docs/GettingStarted.md#active-record
AWS https://aws.amazon.com/sdk-for-ruby/ https://github.com/DataDog/dd-trace-rb/blob/master/docs/GettingStarted.md#aws
Dalli https://github.com/petergoldstein/dalli https://github.com/DataDog/dd-trace-rb/blob/master/docs/GettingStarted.md#dalli
Elasticsearch https://www.elastic.co/products/elasticsearch https://github.com/DataDog/dd-trace-rb/blob/master/docs/GettingStarted.md#elastic-search
Faraday https://github.com/lostisland/faraday https://github.com/DataDog/dd-trace-rb/blob/master/docs/GettingStarted.md#faraday
Grape http://www.ruby-grape.org/ https://github.com/DataDog/dd-trace-rb/blob/master/docs/GettingStarted.md#grape
GraphQL https://github.com/rmosolgo/graphql-ruby https://github.com/DataDog/dd-trace-rb/blob/master/docs/GettingStarted.md#graphql
MongoDB http://api.mongodb.com/ruby/current/ https://github.com/DataDog/dd-trace-rb/blob/master/docs/GettingStarted.md#mongodb
Net/HTTP https://ruby-doc.org/stdlib-2.4.0/libdoc/net/http/rdoc/Net/HTTP.html https://github.com/DataDog/dd-trace-rb/blob/master/docs/GettingStarted.md#nethttp
Racecar https://github.com/zendesk/racecar https://github.com/DataDog/dd-trace-rb/blob/master/docs/GettingStarted.md#racecar
Rack https://rack.github.io/ https://github.com/DataDog/dd-trace-rb/blob/master/docs/GettingStarted.md#rack
Rails http://rubyonrails.org/ https://github.com/DataDog/dd-trace-rb/blob/master/docs/GettingStarted.md#rails
Redis https://github.com/redis/redis-rb https://github.com/DataDog/dd-trace-rb/blob/master/docs/GettingStarted.md#redis
Resque https://github.com/resque/resque https://github.com/DataDog/dd-trace-rb/blob/master/docs/GettingStarted.md#resque
Sidekiq https://sidekiq.org/ https://github.com/DataDog/dd-trace-rb/blob/master/docs/GettingStarted.md#sidekiq
Sinatra http://www.sinatrarb.com/ https://github.com/DataDog/dd-trace-rb/blob/master/docs/GettingStarted.md#sinatra
SuckerPunch https://github.com/brandonhilkert/sucker_punch https://github.com/DataDog/dd-trace-rb/blob/master/docs/GettingStarted.md#sucker-punch

Further reading