dd-trace-rb

Documentation

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

Getting started

Install

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

    source 'https://rubygems.org'

    # tracing gem
    gem 'ddtrace', :source => 'http://gems.datadoghq.com/trace/'

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

Development

Testing

Configure your environment through:

$ bundle install
$ appraisal install

You can launch all tests using the following rake command:

$ rake test                     # tracer tests
$ appraisal rake rails          # tests Rails matrix

Available appraisals are:

rails{3,4,5}-postgres: Rails with PostgreSQL
rails{3,4,5}-mysql2: Rails with MySQL

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