Custom Instrumentation of Ruby Applications with the OpenTelemetry API

Overview

Datadog tracing libraries provide an implementation of the OpenTelemetry API for instrumenting your code. This means you can maintain vendor-neutral instrumentation of all your services, while still taking advantage of Datadog’s native implementation, features, and products. You can configure it to generate Datadog-style spans and traces to be processed by the Datadog tracing library for your language, and send those to Datadog.

By instrumenting your code with OpenTelemetry API:

• Your code remains free of vendor-specific API calls.
• Your code does not depend on Datadog tracing libraries at compile time (only runtime).
• Your code does not use the deprecated OpenTracing API.

Replace the OpenTelemetry SDK with the Datadog tracing library in the instrumented application, and the traces produced by your running code can be processed, analyzed, and monitored alongside Datadog traces and in Datadog proprietary products.

For more information, read Interoperability of OpenTelemetry API and Datadog instrumented traces.

The Datadog tracing library, when configured as described here, accepts the spans and traces generated by OpenTelemetry-instrumented code, processes the telemetry, and sends it to Datadog. You can use this approach, for example, if your code has already been instrumented with the OpenTelemetry API, or if you want to instrument using the OpenTelemetry API, and you want to gain the benefits of using the Datadog tracing libraries without changing your code.

If you’re looking for a way to instrument your code with OpenTelemetry and then send span data to Datadog without going through the Datadog tracing library, see OpenTelemetry in Datadog.

Requirements and limitations

• Datadog Ruby tracing library dd-trace-rb version 1.9.0 or greater.
• Gem version support 1.1.0 or greater.

The following OpenTelemetry features implemented in the Datadog library as noted:

Configuring OpenTelemetry to use the Datadog tracing library

1. Add your desired manual OpenTelemetry instrumentation to your Ruby code following the OpenTelemetry Ruby Manual Instrumentation documentation. Important! Where those instructions indicate that your code should call the OpenTelemetry SDK, call the Datadog tracing library instead.

2. Add the ddtrace gem to your Gemfile:

   source 'https://rubygems.org'
   gem 'ddtrace'
   

3. Install the gem by running bundle install.

4. Add the following lines to your OpenTelemetry configuration file:

   require 'opentelemetry'
   require 'datadog/opentelemetry'
   

5. Add a configuration block to your application where you can activate integrations and change tracer settings. Without additional configuration here, only code you have instrumented with OpenTelemetry is traced:

   Datadog.configure do |c|
     ...
   end
   

   Using this block you can:

   • Add additional Datadog configuration settings
   • Activate or reconfigure Datadog instrumentation

Datadog combines these OpenTelemetry spans with other Datadog APM spans into a single trace of your application. It supports integration instrumentation and OpenTelemetry Automatic instrumentation also.

Further Reading

Additional helpful documentation, links, and articles:

Explore your services, resources, and tracesDOCUMENTATION Interoperability of OpenTelemetry API and Datadog instrumented tracesDOCUMENTATION