Ruby で OpenTelemetry API を使用したカスタム インスツルメンテーション

概要

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 をご覧ください。

要件と制限

  • 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