Ruby で 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).

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.

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.

要件と制限

  • Datadog Ruby トレーシングライブラリ dd-trace-rb バージョン 1.9.0 以上。
  • Gem バージョンサポート 1.1.0 以上。

特記されている通り、Datadog のライブラリに実装されている以下の OpenTelemetry 機能:

機能サポートノート
OpenTelemetry コンテキスト伝搬Datadog と W3C Trace Context のヘッダーフォーマットはデフォルトで有効になっています。
スパンプロセッサー非サポート
スパンエクスポーター非サポート
OpenTelemetry.loggerOpenTelemetry.logger は Datadog.logger と同じオブジェクトに設定されています。カスタムロギングから構成します。
トレース/スパン ID ジェネレーターID 生成はトレーシングライブラリによって実行され、128 ビットのトレース ID をサポートしています。

Datadog トレーシングライブラリを使用するための OpenTelemetry の構成

  1. OpenTelemetry Ruby Manual Instrumentation のドキュメント に従って、必要な手動の OpenTelemetry インスツルメンテーションを Ruby コードに追加します。重要! その手順で OpenTelemetry SDK を呼び出すように示されている箇所では、代わりに Datadog トレース ライブラリを呼び出してください。

  2. datadog gem を Gemfile に追加します。

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

  3. bundle install を実行して gem をインストールします。

  4. OpenTelemetry のコンフィギュレーションファイルに以下の行を追加します。

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

  5. インテグレーションを有効にし、トレーサー設定を変更できる構成ブロックをアプリケーションに追加します。ここで追加の構成を行わないと、OpenTelemetry でインスツルメンテーションを行ったコードのみがトレースされます。

    Datadog.configure do |c|
  ...
end

    このブロックを使うと、以下のことができます。

    OpenTelemetry の設定は、OpenTelemetry::SDK.configure ブロック を使用して、個別に変更できます。

Datadog は、これらの OpenTelemetry スパンと他の Datadog APM スパンを組み合わせて、アプリケーションの単一のトレースにします。また、インテグレーションインスツルメンテーションと OpenTelemetry 自動インスツルメンテーションもサポートしています。

Adding span events

スパン イベントを追加するには、SDK バージョン 2.3.0 以上が必要です。

add_event API を使用してスパン イベントを追加できます。このメソッドには必須パラメーター name があり、オプションで attributes と timestamp を受け取ります。メソッドは指定されたプロパティを持つ新しいスパン イベントを作成し、対象のスパンに関連付けます。

  • 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 [オプション]: イベントが発生した時刻を表す UNIX タイムスタンプ。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]}
)

詳細は OpenTelemetry 仕様を参照してください。

Recording exceptions

例外を記録するには record_exception API を使用します。このメソッドには必須パラメーター exception があり、オプションで UNIX timestamp を受け取ります。標準化された例外属性を含む新しいスパン イベントを作成し、対象のスパンに関連付けます。

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' }
)

詳細は OpenTelemetry 仕様 を参照してください。

その他の参考資料

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

サービス、リソース、トレースの詳細ドキュメント more more OpenTelemetry API と Datadog でインスツルメントされたトレースの相互運用性ドキュメント more more