概要

Datadog の OpenTelemetry Protocol (OTLP) トレースインテーク API エンドポイントを使用すると、アプリケーション、マネージドプラットフォーム、および OpenTelemetry Collector から OTLP HTTP 経由で Datadog にトレースを送信できます。

Datadog Agent や OpenTelemetry Collector を使用せずにトレースを送信する必要がある場合は、このページの直接構成を使用してください。本番環境の Collector デプロイメントについては、OpenTelemetry Collector のセットアップ を参照してください。

サーバーレスワークロードについては、Serverless の OTLP インテーク を参照してください。Cloudflare、Vercel、Heroku などのマネージドプラットフォームについては、マネージドプラットフォームの OTLP インテーク を参照してください。

構成

OTLP データを Datadog OTLP トレースインテークエンドポイントにエクスポートするには、以下の手順を実行します。

1. OTLP HTTP Protobuf エクスポーターを構成します。
   • Datadog OTLP トレースインテークエンドポイントを設定します。
   • 必要な HTTP ヘッダーを構成します。
2. (オプション) dd-otel-span-mapping HTTP ヘッダーを設定して、スパンのマッピングおよびフィルタリングを行います。

エクスポーターを構成する

Datadog OTLP トレースインテークエンドポイントに OTLP データを送信するには、OTLP HTTP Protobuf エクスポーターを使用する必要があります。OpenTelemetry の自動インスツルメンテーションと手動インスツルメンテーションのどちらを使用しているかによってプロセスが異なります。

トレースメトリクス は、Datadog OTLP トレースインテークエンドポイントに直接送信されたトレースに対してはデフォルトで計算されません。以下の例には、トレースメトリクスを有効にするための compute_stats=true が含まれています。

自動インスツルメンテーション

OpenTelemetry 自動インスツルメンテーション を使用している場合は、次の環境変数を設定してください。

export OTEL_EXPORTER_OTLP_TRACES_PROTOCOL="http/protobuf"
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=""
export OTEL_EXPORTER_OTLP_TRACES_HEADERS="dd-api-key=${DD_API_KEY},compute_stats=true"

手動インスツルメンテーション

OpenTelemetry SDK で手動インスツルメンテーションを使用している場合は、OTLP HTTP Protobuf エクスポーターをプログラムで構成してください。

const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-proto');  // OTLP http/protobuf exporter

const exporter = new OTLPTraceExporter({
  url: '${YOUR_ENDPOINT}', // Replace this with the correct endpoint
  headers: {
    'dd-api-key': process.env.DD_API_KEY,
    'dd-otel-span-mapping': '{span_name_as_resource_name: true}',
    'compute_stats': 'true',
  },
});

import io.opentelemetry.exporter.otlp.http.trace.OtlpHttpSpanExporter;

OtlpHttpSpanExporter exporter = OtlpHttpSpanExporter.builder()
    .setEndpoint("${YOUR_ENDPOINT}") // Replace this with the correct endpoint
    .addHeader("dd-api-key", System.getenv("DD_API_KEY"))
    .addHeader("dd-otel-span-mapping", "{span_name_as_resource_name: true}")
    .addHeader("compute_stats", "true")
    .build();

import "go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp"

traceExporter, err := otlptracehttp.New(
	ctx,
	otlptracehttp.WithEndpoint("${YOUR_ENDPOINT}"), // Replace this with the correct endpoint
	otlptracehttp.WithURLPath("/v1/traces"),
	otlptracehttp.WithHeaders(
		map[string]string{
			"dd-api-key": os.Getenv("DD_API_KEY"),
			"dd-otel-span-mapping": "{span_name_as_resource_name: true}",
			"compute_stats": "true",
		}),
)

from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter

exporter = OTLPSpanExporter(
    endpoint="${YOUR_ENDPOINT}", # Replace this with the correct endpoint
    headers={
        "dd-api-key": os.environ.get("DD_API_KEY"),
        "dd-otel-span-mapping": "{span_name_as_resource_name: true}",
        "compute_stats": "true",
    },
)

(オプション) スパン名をマッピングまたはフィルタリングする

dd-otel-span-mapping ヘッダーを使用して、スパンのマッピングとフィルタリングを構成します。JSON ヘッダーには、次のフィールドが含まれます。

• ignore_resources: リソース名に基づいてトレースを無効にするための正規表現のリスト。
• span_name_remappings: Datadog スパン名から任意の名前へのマッピング。
• span_name_as_resource_name: OpenTelemetry スパン名を Datadog スパンのオペレーション名として使用するかどうかを指定します (デフォルト: true)。false の場合、オペレーション名はインスツルメンテーションスコープ名とスパン種別の組み合わせから派生します。

例:

{
  "span_name_as_resource_name":false,
  "span_name_remappings":{
    "io.opentelemetry.javaagent.spring.client":"spring.client"
  },
  "ignore_resources":[
    "io.opentelemetry.javaagent.spring.internal"
  ]
}

OpenTelemetry Collector

推奨される OpenTelemetry Collector のセットアップ を構成して、トレースがこのエンドポイントにエクスポートし、サンプリング前に APM トレースメトリクスを生成します。

トラブルシューティング

エラー: 403 Forbidden

Datadog OTLP トレースインテークエンドポイントへトレースを送信した際に 403 Forbidden エラーが発生する場合は、エンドポイントが Datadog サイトと一致していることを確認してください。ご利用のサイトは です。 エンドポイントを使用してください。

エラー: 413 Request Entity Too Large

Datadog OTLP トレースインテークエンドポイントへトレースを送信した際に 413 Request Entity Too Large エラーが発生する場合は、OTLP エクスポーターが送信するペイロードのサイズが Datadog トレースインテークエンドポイントの上限の 15 MiB (非圧縮) を超えています。

このエラーは通常、OpenTelemetry SDK が単一のリクエストペイロードに大量のテレメトリデータをまとめて送信した場合に発生します。

解決策: SDK のバッチスパンプロセッサーのエクスポートバッチサイズを減らしてください。OpenTelemetry Java SDK で BatchSpanProcessorBuilder を変更する方法の例を以下に示します。

CopyBatchSpanProcessor batchSpanProcessor =
    BatchSpanProcessor
        .builder(exporter)
        .setMaxExportBatchSize(10)  // Default is 512
        .build();

setMaxExportBatchSize の値は必要に応じて調整してください。値を小さくすると、より頻繁に小さいペイロードでエクスポートされるようになり、15 MiB の制限を超える可能性が低くなります。

警告: "traces export: failed … 202 Accepted" in Go

OpenTelemetry Go SDK を使用していて、traces export: failed … 202 Accepted のような警告メッセージが表示される場合は、OpenTelemetry Go OTLP HTTP エクスポーターに存在する既知の問題が原因です。

OpenTelemetry Go OTLP HTTP エクスポーターは、エクスポートが成功しても 200 以外の HTTP ステータスコードをエラーとして扱います (Issue 3706)。一方、他の OpenTelemetry SDK では 200 以上 300 未満のステータスコードを成功と見なします。Datadog OTLP トレースインテークエンドポイントは、エクスポートが成功した場合に ``202 Accepted` を返します。

OpenTelemetry コミュニティでは、他の 2xx ステータスコードを成功として扱うべきかどうかについて、まだ議論が続いています (Issue 3203)。

解決策: OpenTelemetry Go SDK と Datadog OTLP トレースインテークエンドポイントを組み合わせて使用している場合は、この警告メッセージを無視しても問題ありません。警告が出ていても、トレースは正しくエクスポートされています。

問題: 予期しないスパンのオペレーション名

Datadog OTLP トレースインテークエンドポイントを使用していると、Datadog Agent や OpenTelemetry Collector を使用した場合とは異なるスパンのオペレーション名が生成されることがあります。

Datadog OTLP トレースインテークエンドポイントでは、デフォルトで span_name_as_resource_name オプションが true に設定されています。つまり、Datadog は OpenTelemetry スパン名をオペレーション名として使用します。対照的に、Datadog Agent と OpenTelemetry Collector では、このオプションがデフォルトで false に設定されています。

span_name_as_resource_name が false に設定されている場合、オペレーション名はインスツルメンテーションスコープ名とスパン種別の組み合わせから派生します。たとえば、オペレーション名は opentelemetry.client と表示される場合があります。

解決策: Datadog OTLP トレースインテークエンドポイントで span_name_as_resource_name オプションを無効にし、Datadog Agent や OpenTelemetry Collector と同じ動作に合わせたい場合は、以下の手順を実行してください。

1. このドキュメントのスパン名をマッピングまたはフィルタリングするを参照してください。
2. dd-otel-span-mapping ヘッダーで span_name_as_resource_name オプションを false に設定します。

例:

jsonCopy{
  "span_name_as_resource_name": false,
  ...
}

これにより、Datadog OTLP トレースインテークエンドポイント、Datadog Agent、OpenTelemetry Collector でスパンのオペレーション名が一致するようになります。

参考資料

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

一般的な OpenTelemetry SDK の構成外部サイト OpenTelemetry の環境変数の仕様外部サイト OpenTelemetry Protocol エクスポーター外部サイト