Ruby Open Standards
Incident Management is now generally available! Incident Management is now generally available!

Ruby Open Standards

OpenTracing

To set up Datadog with OpenTracing, see the Ruby Quickstart for OpenTracing for details.

Configuring Datadog tracer settings

The underlying Datadog tracer can be configured by passing options (which match Datadog::Tracer) when configuring the global tracer:

# Where `options` is a Hash of options provided to Datadog::Tracer
OpenTracing.global_tracer = Datadog::OpenTracer::Tracer.new(options)

It can also be configured by using Datadog.configure as described in the Ruby tracer settings section.

Activating and configuring integrations

By default, configuring OpenTracing with Datadog does not automatically activate any additional instrumentation provided by Datadog. You will only receive spans and traces from OpenTracing instrumentation you have in your application.

However, additional instrumentation provided by Datadog can be activated alongside OpenTracing using Datadog.configure, which can be used to enhance your tracing further. To enable this, see Ruby integration instrumentation for more details.

Supported serialization formats

TypeSupported?Additional information
OpenTracing::FORMAT_TEXT_MAPYes
OpenTracing::FORMAT_RACKYesBecause of the loss of resolution in the Rack format, note that baggage items with names containing either upper case characters or - are be converted to lower case and _ in a round-trip, respectively. Datadog recommends avoiding these characters or accommodating accordingly on the receiving end.
OpenTracing::FORMAT_BINARYNo

OpenTelemetry

OpenTelemetry support is available by using the opentelemetry-exporters-datadog gem to export traces from OpenTelemetry to Datadog.

This feature is currently in beta. Reach out to support if it doesn't work as you expect.

Installation

  • If you use bundler, include the following in your Gemfile:
gem 'opentelemetry-exporters-datadog'
gem 'opentelemetry-api', '~> 0.5'
gem 'opentelemetry-sdk', '~> 0.5'
  • Or install the gems directly using:
gem install opentelemetry-api
gem install opentelemetry-sdk
gem install opentelemetry-exporters-datadog

Usage

Install the Datadog processor and exporter in your application and configure the options. Then use the OpenTelemetry interfaces to produce traces and other information:

require 'opentelemetry/sdk'
require 'opentelemetry-exporters-datadog'

# Configure the SDK with custom export
OpenTelemetry::SDK.configure do |c|
  c.add_span_processor(
    OpenTelemetry::Exporters::Datadog::DatadogSpanProcessor.new(
      OpenTelemetry::Exporters::Datadog::Exporter.new(
        service_name: 'my_service', agent_url: 'http://localhost:8126'
      )
    )
  )
end

# For propagation of Datadog-specific distributed tracing headers,
# set HTTP propagation to the Composite Propagator
OpenTelemetry::Exporters::Datadog::Propagator.auto_configure

# To start a trace, get a Tracer from the TracerProvider
tracer = OpenTelemetry.tracer_provider.tracer('my_app_or_gem', '0.1.0')

# create a span
tracer.in_span('foo') do |span|
  # set an attribute
  span.set_attribute('platform', 'osx')
  # add an event
  span.add_event(name: 'event in bar')
  # create bar as child of foo
  tracer.in_span('bar') do |child_span|
    # inspect the span
    pp child_span
  end
end

Configuration Options

The Datadog Agent URL and span tag values can be configured if necessary or desired based upon your environment and Agent location.

Datadog Agent URL

By default, the OpenTelemetry Datadog Exporter sends traces to http://localhost:8126. Send traces to a different URL by configuring the following environment variables:

  • DD_TRACE_AGENT_URL: The <host>:<port> where Datadog Agent is listening for traces, for example, http://agent-host:8126.

You can override these values at the trace exporter level:

# Configure the SDK with custom export
OpenTelemetry::SDK.configure do |c|
  c.add_span_processor(
    OpenTelemetry::Exporters::Datadog::DatadogSpanProcessor.new(
      OpenTelemetry::Exporters::Datadog::Exporter.new(
        service_name: 'my_service',
        agent_url: 'http://dd-agent:8126',
      )
    )
  )
end

Tagging

Configure the application to automatically tag your Datadog exported traces by setting the following environment variables:

  • DD_ENV: Your application environment, for example production, staging.
  • DD_SERVICE: Your application’s default service name, for example, billing-api.
  • DD_VERSION: Your application version, for example, 2.5, 202003181415, or 1.3-alpha.
  • DD_TAGS: Custom tags in value pairs, separated by commas, for example, layer:api,team:intake.
  • If DD_ENV, DD_SERVICE, or DD_VERSION is set, it will override any corresponding env, service, or version tag defined in DD_TAGS.
  • If DD_ENV, DD_SERVICE and DD_VERSION are not set, you can configure environment, service, and version by using corresponding tags in DD_TAGS.

Tag values can also be overridden at the trace exporter level. This lets you set values on a per-application basis, so you can have multiple applications reporting for different environments on the same host:

# Configure the SDK with custom export
OpenTelemetry::SDK.configure do |c|
  c.add_span_processor(
    OpenTelemetry::Exporters::Datadog::DatadogSpanProcessor.new(
      OpenTelemetry::Exporters::Datadog::Exporter.new(
        service_name: 'my_service',
        agent_url: 'http://localhost:8126',
        env: 'prod',
        version: '1.5-alpha',
        tags: 'team:ops,region:west'
      )
    )
  )
end

Tags that are set directly on individual spans supersede conflicting tags defined at the application level.

  • See rubygems or github for more OpenTelemetry Ruby Datadog Exporter usage.

Further Reading

Additional helpful documentation, links, and articles: