Datadog CI Visibility for Ruby

Datadog's Ruby Library for instrumenting your test and continuous integration pipeline. Learn more on our official website and check out our documentation for this library.

Installation

Add to your Gemfile.

group :test do
  gem "datadog-ci"
end

Upgrade from ddtrace v1.x

If you used test visibility for Ruby with ddtrace gem, check out our upgrade guide.

Usage

RSpec

To activate RSpec integration, add this to the spec_helper.rb file:

require 'rspec'
require 'datadog/ci'

# Only activates test instrumentation on CI
if ENV["DD_ENV"] == "ci"
  Datadog.configure do |c|
    # The name of the service or library under test
    c.service = 'my-ruby-app'
    c.ci.enabled = true
    c.ci.instrument :rspec
  end
end

Minitest

The Minitest integration will trace all executions of tests when using minitest test framework.

To activate your integration, use the Datadog.configure method:

require 'minitest'
require 'datadog/ci'

# Only activates test instrumentation on CI
if ENV["DD_ENV"] == "ci"
# Configure default Minitest integration
  Datadog.configure do |c|
    # The name of the service or library under test
    c.service = 'my-ruby-app'
    c.ci.enabled = true
    c.ci.instrument :minitest
  end
end

Important

When using minitest/autorun the order of requires matters: datadog/ci must be always required before minitest/autorun.

Example using minitest/autorun

require 'datadog/ci'
require 'minitest/autorun'

if ENV["DD_ENV"] == "ci"
  Datadog.configure do |c|
    c.service = 'my-ruby-app'
    c.ci.enabled = true
    c.ci.instrument :minitest
  end
end

Cucumber

Activate Cucumber integration with configuration

require 'cucumber'
require 'datadog/ci'

# Only activates test instrumentation on CI
if ENV["DD_ENV"] == "ci"
  Datadog.configure do |c|
    # The name of the service or library under test
    c.service = 'my-ruby-app'
    c.ci.enabled = true
    c.ci.instrument :cucumber
  end
end

Instrumentation options

Configuration ci.instrument accepts the following optional parameters:

• enabled (default: true) - defines whether tests should be traced (useful for temporarily disabling tracing)
• service_name - name of the service or library under test (when you want it to be different for a test framework)

Example usage:

  Datadog.configure do |c|
    c.service = 'my-ruby-app'
    c.ci.enabled = true
    c.ci.instrument :cucumber, service_name: 'my-cucumber-features', enabled: true
    c.ci.instrument :minitest, service_name: 'my-unit-tests', enabled: false
  end

Agentless mode

If you are using a cloud CI provider without access to the underlying worker nodes, such as GitHub Actions or CircleCI, configure the library to use the Agentless mode. For this, set the following environment variables: DD_CIVISIBILITY_AGENTLESS_ENABLED=true (Required) and DD_API_KEY=your_secret_api_key (Required).

Additionally, configure which Datadog site you want to send data to: DD_SITE=your.datadoghq.com (datadoghq.com by default).

Agentless mode can also be enabled via Datadog.configure (but don't forget to set DD_API_KEY environment variable):

Datadog.configure { |c| c.ci.agentless_mode_enabled = true }

Additional configuration

Add tracing instrumentations

It can be useful to have rich tracing information about your tests that includes time spent performing database operations or other external calls like here:

To achieve this, add Datadog tracing instrumentations in your Datadog.configure block:

Datadog.configure do |c|
  #  ... ci configs and instrumentation here ...
  c.tracing.instrument :redis
  c.tracing.instrument :pg
end

...or enable auto instrumentation in your test_helper/spec_helper:

require "datadog/auto_instrument"

Note: in CI mode these traces are going to be submitted to CI Visibility, they will not show up in Datadog APM.

For the full list of available instrumentations see datadog documentation

WebMock

WebMock is a popular Ruby library that stubs HTTP requests when running tests. By default it fails when used together with datadog-ci as traces are being sent to Datadog via HTTP calls.

In order to allow HTTP connections for Datadog backend you would need to configure Webmock accordingly.

# when using agentless mode
WebMock.disable_net_connect!(:allow => /datadoghq/)

# when using agent
WebMock.disable_net_connect!(:allow_localhost => true)

# or for more granular setting set your agent URL
WebMock.disable_net_connect!(:allow => "localhost:8126")

VCR

VCR is another popular testing library for HTTP interactions.

It requires additional configuration to correctly work with datadog-ci:

VCR.configure do |config|
  # ... your usual configuration here ...

  # when using agent
  config.ignore_hosts "127.0.0.1", "localhost"

  # when using agentless mode
  config.ignore_request do |request|
    # ignore all requests to datadoghq hosts
    request.uri =~ /datadoghq/
  end
end

Disabling startup logs

Startup logs produce a report of tracing state when the application is initially configured. These logs are activated by default in test mode, if you don't want them you can disable this via DD_TRACE_STARTUP_LOGS=0 or in the Datadog.configure block:

Datadog.configure { |c| c.diagnostics.startup_logs.enabled = false }

Enabling debug mode

Switching the library into debug mode will produce verbose, detailed logs about tracing activity, including any suppressed errors. This output can be helpful in identifying errors, confirming trace output, or catching HTTP transport issues.

You can enable this via DD_TRACE_DEBUG=1 or in the Datadog.configure block:

Datadog.configure { |c| c.diagnostics.debug = true }

Contributing

See development guide, static typing guide and contributing guidelines.

Code of Conduct

Everyone interacting in the Datadog::CI project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.