概要

Datadog トレーシングライブラリは、コードのインスツルメンテーション用に OpenTelemetry API の実装を提供します。これは、Datadog のネイティブな実装、機能、製品を利用しながら、すべてのサービスのインスツルメンテーションをベンダーニュートラルに維持できることを意味します。Datadog スタイルのスパンやトレースを生成して、お使いの言語の Datadog のトレーシングライブラリで処理し、Datadog に送信するように構成することができます。

OpenTelemetry API でコードをインスツルメントすることによって

• コードは、ベンダー固有の API 呼び出しから自由になります。
• コードはコンパイル時には Datadog トレーシングライブラリに依存せず、ランタイム時のみになります。
• コードは、非推奨の OpenTracing API を使用しません。

インスツルメントされたアプリケーションで OpenTelemetry SDK を Datadog トレーシングライブラリに置き換えた場合、実行中のコードによって生成されるトレースを Datadog のトレースや Datadog 独自の製品で処理、分析、監視することが可能です。

詳細は、OpenTelemetry API と Datadog でインスツルメントされたトレースの相互運用性を参照してください。

Datadog トレーシングライブラリは、ここで説明するように構成すると、 OpenTelemetry でインスツルメントされたコードによって生成されたスパンとトレースを受け入れ、 テレメトリーを処理して Datadog に送信します。例えば、コードがすでに OpenTelemetry API でインスツルメントされている場合や、OpenTelemetry API を使ってインスツルメントしたいが、コードを変更することなく Datadog トレーシングライブラリを使用するメリットを得たい場合に、このアプローチを使用することができます。

OpenTelemetry を使ってコードをインスツルメントし、 Datadog トレーシングライブラリを介さずに Datadog にスパンデータを送信する方法を探している場合は、Datadog の OpenTelemetry をご覧ください。

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

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

お役に立つドキュメント、リンクや記事:

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