Overview

There are a few reasons to manually instrument your applications with the OpenTelemetry API:

• You are not using Datadog supported library instrumentation.
• You want to extend the Datadog SDK’s functionality.
• You need finer control over instrumenting your applications.

The Datadog SDK provides several techniques to help you achieve these goals. The following sections demonstrate how to use the OpenTelemetry API for custom instrumentation to use with 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 datadog gem to your Gemfile:

   source 'https://rubygems.org'
   gem 'datadog' # For dd-trace-rb v1.x, use the `ddtrace` gem.
   

3. Install the gem by running bundle install.

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

   require 'opentelemetry/sdk'
   require 'datadog/opentelemetry'
   

5. Add a configuration block to your application:

   Datadog.configure do |c|
     ...
   end
   

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.

Adding span events

You can add span events using the add_event API:

span.add_event('Event With No Attributes')
span.add_event(
  'Event With All Attributes',
  attributes: { 'int_val' => 1, 'string_val' => 'two', 'int_array' => [3, 4], 'string_array' => ['5', '6'], 'bool_array' => [false, true]}
)

Read the OpenTelemetry specification for adding events for more information.

Recording exceptions

To record exceptions, use the record_exception API:

span.record_exception(
  StandardError.new('Error Message')
)
span.record_exception(
  StandardError.new('Error Message'),
  attributes: { 'status' => 'failed' }
)

Read the OpenTelemetry specification for recording exceptions for more information.

Further reading

Documentation, liens et articles supplémentaires utiles:

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