dd-trace-rb

Documentation

You can find the latest documentation in the Datadog's private repository

Getting started

Install

Install the Ruby client with the gem command:

gem install ddtrace

If you're using Bundler, just update your Gemfile as follows:

    source 'https://rubygems.org'

    # tracing gem
    gem 'ddtrace'

Quickstart (manual instrumentation)

If you aren't using a supported framework instrumentation, you may want to to manually instrument your code. Adding tracing to your code is very simple. As an example, let’s imagine we have a web server and we want to trace requests to the home page:

    require 'ddtrace'
    require 'sinatra'
    require 'activerecord'

    # a generic tracer that you can use across your application
    tracer = Datadog.tracer

    get '/' do
      tracer.trace('web.request') do |span|
        # set some span metadata
        span.service = 'my-web-site'
        span.resource = '/'
        span.set_tag('http.method', request.request_method)

        # trace the activerecord call
        tracer.trace('posts.fetch') do
          @posts = Posts.order(created_at: :desc).limit(10)
        end

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

Monkey patching

By default, our monkey-patching is not active, you need to explicitly activate it by calling Datadog::Monkey.patch_all or Datadog::Monkey.patch_module

This ultimately allows you to enable or disable tracing on a per-library basis.

The example below shows the Redis case, but any other non-rails library should work the same way:

    require 'redis'
    require 'ddtrace'

    Datadog::Monkey.patch_all # you need to explicitly patch it

    # now do your Redis stuff, eg:
    redis = Redis.new
    redis.set 'foo', 'bar' # traced!

Development

Testing

Configure your environment through:

$ bundle install
$ appraisal install

You can launch tests using the following rake command:

$ rake test:main                                     # tracer tests
$ appraisal rails<version>-<database>rake test:rails # tests Rails matrix
$ appraisal contrib rake test:redis                  # tests Redis integration
$ appraisal contrib rake test:monkey                 # tests monkey patching

Available appraisals are:

• rails{3,4,5}-postgres: Rails with PostgreSQL
• rails{3,4,5}-mysql2: Rails with MySQL
• contrib: Other contrib libraries (Redis, ...)

jRuby includes only Rails 3.x and 4.x because the current implementation of jdbc drivers, don't support ActiveRecord 5.x.

The test suite requires many backing services (PostgreSQL, MySQL, Redis, ...) and we're using docker and docker-compose to start these services in the CI. To launch properly the test matrix, please install docker and docker-compose using the instructions provided by your platform. Then launch them through:

$ docker-compose up -d

We also enforce the Ruby community-driven style guide through Rubocop. Simply launch:

$ rake rubocop