Présentation

Les bibliothèques de tracing Datadog permettent d’implémenter l’API OpenTelemetry afin d’instrumenter votre code. Cela signifie que vous pouvez continuer à instrumenter vos services sans dépendre d’un fournisseur, tout en tirant parti des fonctionnalités, des solutions et des capacités d’implémentation natives de Datadog. Configurez l’instrumentation pour générer des spans et traces utilisables par Datadog, les traiter pour votre langage via la bibliothèque de tracing Datadog, et les envoyer à Datadog.

Lorsque vous instrumentez votre code avec l’API OpenTelemetry :

• Votre code ne contient aucun appel d’API propre à un fournisseur.
• Votre code ne dépend pas des bibliothèques de tracing Datadog pendant la compilation (uniquement pendant l’exécution).
• Votre code n’utilise pas l’API OpenTracing obsolète.

Remplacez le SDK OpenTelemetry par la bibliothèque de tracing Datadog dans l’application instrumentée, de manière à ce que les traces générées par votre code exécuté puissent être traitées, analysées et surveillées en même temps que les traces Datadog, y compris dans les solutions propriétaires de Datadog.

Pour en savoir plus, consultez la section Interopérabilité des traces instrumentées par l’API OpenTelemetry et par Datadog.

Lorsque vous appliquez la configuration décrite sur cette page, la bibliothèque de tracing Datadog accepte les spans et traces générées par le code instrumenté par OpenTelemetry, traite les données de télémétrie et les envoient à Datadog. Vous pouvez par exemple utiliser cette approche si votre code a déjà été instrumenté avec l’API OpenTelemetry, ou si vous souhaitez effectuer une instrumentation à l’aide de l’API OpenTelemetry et exploiter les bibliothèques de tracing Datadog sans avoir à modifier votre code.

Si vous cherchez à instrumenter votre code avec OpenTelemetry, puis à envoyer les données de vos spans à Datadog sans passer par la bibliothèque de tracing Datadog, consultez la section OpenTelemetry dans 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 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

   OpenTelemetry configuration can be changed separately, using the OpenTelemetry::SDK.configure block.

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. This method requires a name parameter and optionally accepts attributes and timestamp parameters. The method creates a new span event with the specified properties and associates it with the corresponding span.

• Name [required]: A string representing the event’s name.
• Attributes [optional]: Zero or more key-value pairs with the following properties:
  • The key must be a non-empty string.
  • The value can be either:
    • A primitive type: string, Boolean, or number.
    • A homogeneous array of primitive type values (for example, an array of strings).
  • Nested arrays and arrays containing elements of different data types are not allowed.
• Timestamp [optional]: A UNIX timestamp representing the event’s occurrence time. Expects seconds(Float).

The following examples demonstrate different ways to add events to a span:

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 more information.

Recording exceptions

To record exceptions, use the record_exception API. This method requires an exception parameter and optionally accepts a UNIX timestamp parameter. It creates a new span event that includes standardized exception attributes and associates it with the corresponding span.

The following examples demonstrate different ways to record exceptions:

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

Read the OpenTelemetry specification 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