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:

Name Key Versions Supported How to configure Gem source
Active Record active_record >= 3.2, < 5.2 Link Link
AWS aws >= 2.0 Link Link
Dalli dalli >= 2.7 Link Link
Elastic Search elasticsearch >= 6.0 Link Link
Excon excon >= 0.62 Link Link
Faraday faraday >= 0.14 Link Link
gRPC grpc >= 1.10 Link Link
Grape grape >= 1.0 Link Link
GraphQL graphql >= 1.7.9 Link Link
MongoDB mongo >= 2.0, < 2.5 Link Link
Net/HTTP http (Any supported Ruby) Link Link
Racecar racecar >= 0.3.5 Link Link
Rack rack >= 1.4.7 Link Link
Rails rails >= 3.2, < 5.2 Link Link
Rake rake >= 12.0 Link Link
Redis redis >= 3.2, < 4.0 Link Link
Resque resque >= 1.0, < 2.0 Link Link
Sequel sequel >= 3.41 Link Link
Sidekiq sidekiq >= 4.0 Link Link
Sinatra sinatra >= 1.4.5 Link Link
Sucker Punch sucker_punch >= 2.0 Link Link

Further reading