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).
  • Your code does not use the deprecated OpenTracing API.

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.

For more information, read Interoperability of OpenTelemetry API and Datadog instrumented traces.

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 Java トレーシングライブラリ dd-trace-java バージョン 1.10.0 以上。

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

機能サポートノート
OpenTelemetry コンテキスト伝搬デフォルトでは、Datadog 分散ヘッダーフォーマットが代わりに使用されます。
スパンプロセッサー非サポート
スパンエクスポーター非サポート
トレース/スパン ID ジェネレーターID 生成はトレーシングライブラリによって実行され、128 ビットのトレース ID をサポートしています。
MetricsBaggage および Context API非サポート
スパンリンク (ベータ版)dd-trace-java のバージョン 1.24.0 以降が必要です。

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

自動インスツルメンテーションとセットアップの手順をまだ読んでいない場合は、Java セットアップ手順からご覧ください。
  1. OpenTelemetry Java Manual Instrumentation ドキュメントに従って、ご希望の手動 OpenTelemetry インスツルメンテーションを Java コードに追加します。

  2. Datadog トレーシングライブラリを JVM に追加します。ベータ版: ワンステップ APM インスツルメンテーションを使って、オプションでこれを行うことができます。

  3. (OpenTelemetry SDK ではなく) OpenTelemetry API だけに依存していることを確認します。

// OpenTelemetry API
implementation "io.opentelemetry:opentelemetry-api:${opentelemetryVersion}"
<!-- OpenTelemetry API -->
<dependency>
    <groupId>io.opentelemetry</groupId>
    <artifactId>opentelemetry-api</artifactId>
    <version>${io.opentelemetry.version}</version>
</dependency>
  1. システムプロパティ dd.trace.otel.enabled または環境変数 DD_TRACE_OTEL_ENABLEDtrue に設定します。

Datadog は、これらの OpenTelemetry スパンと他の Datadog APM スパンを組み合わせて、アプリケーションの単一のトレースにします。

一般的なユースケース

現在のスパンまたはローカル root スパンにカスタム属性を追加する

// 現在のスパンに属性を追加します
Span currentSpan = Span.current();
currentSpan.setAttributes("some-key", "some-value");

// ローカル root スパンに属性を追加します
ContextKey<OtelSpan> localRootSpanKey = ContextKey.named("opentelemetry-traces-local-root-span");
Span rootSpan = Context.current().get(localRootSpanKey);
rootSpan.setAttributes("some-key", "some-value");

注: 現在のスパンまたはローカル root スパンが存在しない場合、返されるスパンは null ではなく無効であり、属性は設定されません。

アノテーションを使用してカスタムスパンを追加する

まず、opentelemetry-instrumentation-annotations ライブラリに依存関係を追加します。

  // OpenTelemetry インスツルメンテーションアノテーション
  implementation "io.opentelemetry.instrumentation:opentelemetry-instrumentation-annotations:${opentelemetryVersion}"
<!-- OpenTelemetry instrumentation annotations -->
<dependency>
    <groupId>io.opentelemetry.instrumentation</groupId>
    <artifactId>opentelemetry-instrumentation-annotations</artifactId>
    <version>${io.opentelemetry.version}</version>
</dependency>

次に、メソッドに @WithSpan アノテーションを付けて、呼び出しごとに新しいスパンを作成します。呼び出しのパラメーターには、@SpanAttribute アノテーションを付けて、引数を span 属性としてキャプチャすることができます。

@WithSpan
public void myMethod(@SpanAttribute("parameter1") String parameter1,
    @SpanAttribute("parameter2") long parameter2) {
    <...>
}

注: @WithSpan の代わりに @AddingSpanAttributes メソッドアノテーションを使用すると、新しいスパンを作成せずに @SpanAttribute アノテーションを使用してメソッド引数をキャプチャできます。現在のスパンが存在する場合は、キャプチャされた引数で更新されます。

その他の参考資料