OTLPエクスポーター

この記事は英語の原文を日本語に翻訳したものです。原文: https://opentelemetry.io/docs/specs/otel/protocol/exporter/

翻訳元: open-telemetry/opentelemetry-specification v1.60.0（コミット 29ae8c7）

ステータス: Stable

このドキュメントは、OpenTelemetry Protocol（OTLP）Exporterで利用できる設定オプションと、リトライの挙動を規定します。

設定オプション

以下の設定オプションは、OTLPエクスポーターの設定にMUST利用できるようにするものとします。各設定オプションは、シグナルごとのオプションによってMUST上書き可能にするものとします。

Endpoint（OTLP/HTTP）：エクスポーターがスパン、メトリクス、ログの送信先とするターゲットURL。実装は以下のURLの構成要素をMUST尊重するものとします。
- スキーム（httpまたはhttps）
- ホスト
- ポート
- パス
実装は、その他のすべてのURLの構成要素を無視してもかまいません（MAY）。
スキームがhttpsであることは、安全な接続を示します。OTEL_EXPORTER_OTLP_ENDPOINTを使う場合、エクスポーターは以下で説明するようにシグナルごとのURLをMUST構築するものとします。シグナルごとのエンドポイント設定オプションは優先され、この挙動を上書きするために使えます（そのオプションを使う場合、URLは変更を加えずそのまま使われます）。詳細はOTLP Specificationを参照してください。
- デフォルト：http://localhost:4318 [1]
- 環境変数：OTEL_EXPORTER_OTLP_ENDPOINT OTEL_EXPORTER_OTLP_TRACES_ENDPOINT OTEL_EXPORTER_OTLP_METRICS_ENDPOINT OTEL_EXPORTER_OTLP_LOGS_ENDPOINT
- 型：String
Endpoint（OTLP/gRPC）：エクスポーターがスパン、メトリクス、ログの送信先とするターゲット。このオプションは、基盤となるgRPCクライアント実装が許容する任意の形式をSHOULD受け付けるものとします。加えて、このオプションはhttpまたはhttpsのスキームを持つURLをMUST受け付けるものとします。スキームがhttpsであることは安全な接続を示し、insecure設定より優先されます。スキームがhttpであることは安全でない接続を示し、insecure設定より優先されます。gRPCクライアント実装がhttpまたはhttpsのスキームを持つエンドポイントをサポートしない場合、エンドポイントはその実装にとって最も適切な形式にSHOULD変換されるものとします。
- デフォルト：http://localhost:4317 [1]
- 環境変数：OTEL_EXPORTER_OTLP_ENDPOINT OTEL_EXPORTER_OTLP_TRACES_ENDPOINT OTEL_EXPORTER_OTLP_METRICS_ENDPOINT OTEL_EXPORTER_OTLP_LOGS_ENDPOINT
- 型：String
Insecure：エクスポーターのgRPC接続についてクライアントのトランスポートセキュリティを有効にするかどうか。このオプションは、httpまたはhttpsのスキームなしでエンドポイントが指定されたOTLP/gRPCにのみ適用されます。OTLP/HTTPは、常にendpointに指定されたスキームを使います。実装は、基盤となるgRPCクライアント実装で必要とされない、あるいはサポートされない場合、insecureオプションを実装しなくてもかまいません（MAY）。
- デフォルト：false
- 環境変数：OTEL_EXPORTER_OTLP_INSECURE OTEL_EXPORTER_OTLP_TRACES_INSECURE OTEL_EXPORTER_OTLP_METRICS_INSECURE OTEL_EXPORTER_OTLP_LOGS_INSECURE [2]
- 型：Boolean
Certificate File：サーバーのTLS証明情報を検証する際に使う信頼された証明書。安全な接続にのみ使うべきです（SHOULD）。
- デフォルト：なし
- 環境変数：OTEL_EXPORTER_OTLP_CERTIFICATE OTEL_EXPORTER_OTLP_TRACES_CERTIFICATE OTEL_EXPORTER_OTLP_METRICS_CERTIFICATE OTEL_EXPORTER_OTLP_LOGS_CERTIFICATE
- 型：String
Client key file：mTLS通信でPEM形式で使うクライアントの秘密鍵。
- デフォルト：なし
- 環境変数：OTEL_EXPORTER_OTLP_CLIENT_KEY OTEL_EXPORTER_OTLP_TRACES_CLIENT_KEY OTEL_EXPORTER_OTLP_METRICS_CLIENT_KEY OTEL_EXPORTER_OTLP_LOGS_CLIENT_KEY
- 型：String
Client certificate file：mTLS通信でPEM形式で使うクライアントの秘密鍵に対応するクライアント証明書・証明書チェインの信頼情報。
- デフォルト：なし
- 環境変数：OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE OTEL_EXPORTER_OTLP_TRACES_CLIENT_CERTIFICATE OTEL_EXPORTER_OTLP_METRICS_CLIENT_CERTIFICATE OTEL_EXPORTER_OTLP_LOGS_CLIENT_CERTIFICATE
- 型：String
Headers：gRPCまたはHTTPリクエストに関連付けるヘッダーとして使うキーと値の組。詳細は環境変数によるヘッダーの指定を参照してください。
- デフォルト：なし
- 環境変数：OTEL_EXPORTER_OTLP_HEADERS OTEL_EXPORTER_OTLP_TRACES_HEADERS OTEL_EXPORTER_OTLP_METRICS_HEADERS OTEL_EXPORTER_OTLP_LOGS_HEADERS
- 型：String
Compression：サポートされる圧縮タイプの圧縮キー。サポートされる圧縮：gzip。
- デフォルト：値なし [3]
- 環境変数：OTEL_EXPORTER_OTLP_COMPRESSION OTEL_EXPORTER_OTLP_TRACES_COMPRESSION OTEL_EXPORTER_OTLP_METRICS_COMPRESSION OTEL_EXPORTER_OTLP_LOGS_COMPRESSION
- 型：Enum
Timeout：OTLPエクスポーターがバッチのエクスポートごとに待機する最大時間。
- デフォルト：10秒
- 環境変数：OTEL_EXPORTER_OTLP_TIMEOUT OTEL_EXPORTER_OTLP_TRACES_TIMEOUT OTEL_EXPORTER_OTLP_METRICS_TIMEOUT OTEL_EXPORTER_OTLP_LOGS_TIMEOUT
- 型：Timeout
Max Request Size：エクスポーターが送信するリクエストメッセージの最大サイズ（バイト単位）。OTLP/gRPCとOTLP/HTTPについてOTLP仕様書で定義されているとおり。
- デフォルト：67108864（64 MiB = 6410241024）
- 型：Integer
Max Response Size：エクスポーターが受け入れるレスポンスメッセージの最大サイズ（バイト単位）。OTLP/gRPCとOTLP/HTTPについてOTLP仕様書で定義されているとおり。
- デフォルト：4194304（4 MiB = 410241024）
- 型：Integer
Protocol：トランスポートプロトコル。オプションはgrpc、http/protobuf、http/jsonのいずれかでなければなりません（MUST）。詳細はプロトコルの指定を参照してください。
- デフォルト：http/protobuf [4]
- 環境変数：OTEL_EXPORTER_OTLP_PROTOCOL OTEL_EXPORTER_OTLP_TRACES_PROTOCOL OTEL_EXPORTER_OTLP_METRICS_PROTOCOL OTEL_EXPORTER_OTLP_LOGS_PROTOCOL
- 型：Enum

[1]：SDKは、（安定版SDKリリースにおける後方互換性の理由などで）デフォルトとしてhttpsスキームを選ぶ十分な理由がない限り、エンドポイント変数のデフォルトのスキームとしてhttpをSHOULD使うものとします。

[2]：環境変数OTEL_EXPORTER_OTLP_SPAN_INSECUREとOTEL_EXPORTER_OTLP_METRIC_INSECUREは、他の環境変数の共通の命名規則に従っていないため廃止されています。ただし、これらがすでに実装されている場合、仕様書の安定版リリースの一部であったため、サポートがSHOULD継続されるものとします。

[3]：圧縮の値が明示的に指定されない場合、SIGはサポートされる選択肢の中から最も有用と判断する値をデフォルトにしてもかまいません（MAY）。これは、モバイルデバイスからバックエンドサーバーへ直接テレメトリーデータを送信する場合など、技術的な制約がある状況では特に重要です。

[4]：デフォルトのプロトコルは、SDKがgrpcをデフォルトとして選ぶ強い理由がない限り、http/protobufにSHOULDすべきです。例えば、安定版SDKリリースで以前からgrpcがデフォルトとして確立されている場合、後方互換性を維持するためにgrpcをデフォルトのままにする必要があるかもしれません。

OTEL_EXPORTER_OTLP_*COMPRESSIONオプションについて認識される値は以下のとおりです。

圧縮が無効な場合はnone。
現時点で唯一指定されている圧縮方式はgzip。

OTLP/HTTPのエンドポイントURL

上記の環境変数に基づいて、OTLP/HTTPエクスポーターは、以下のようにして各シグナルのURLをMUST構築するものとします。

シグナルごとの変数（OTEL_EXPORTER_OTLP_<signal>_ENDPOINT）については、URLは変更を加えずそのままMUST使うものとします。唯一の例外は、URLにパス部分が含まれない場合、ルートパス/をMUST使うものとする点です（例2を参照）。
前の項目に該当するシグナルごとの設定を持たないシグナルを送信する場合、OTEL_EXPORTER_OTLP_ENDPOINTがベースURLとして使われ、シグナルはそのベースURLからの相対パスへ送信されます。
- トレース：v1/traces
- メトリクス：v1/metrics
- ログ：v1/logs
非規範的には、これはベースURLの末尾がスラッシュで終わることを確認したうえで、相対URLを文字列として追加することで実装できます。

SDKは、上記で規定した以外の方法でURLを変更してはなりません（MUST NOT）。これは、ポートが空または指定されていない場合、通常のスキームの規則（RFC 7230）に従って、httpスキームではTCPポート80、httpsスキームではTCPポート443がデフォルトになることも意味します。

例1

以下の設定は、すべてのシグナルを同じCollectorへ送信します。

export OTEL_EXPORTER_OTLP_ENDPOINT=http://collector:4318

トレースはhttp://collector:4318/v1/tracesへ、メトリクスはhttp://collector:4318/v1/metricsへ、ログはhttp://collector:4318/v1/logsへ送信されます。

例2

トレースとメトリクスは異なるCollectorとパスへ送信されます。

export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://collector:4318
export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=https://collector.example.com/v1/metrics

これにより、トレースはルートパスhttp://collector:4318/へ直接送信され（/v1/tracesは、シグナルごとでない環境変数を使う場合にのみ自動的に追加されます）、メトリクスはデフォルトのhttpsポート（443）を使ってhttps://collector.example.com/v1/metricsへ送信されます。

例3

以下の設定は、メトリクスを除くすべてのシグナルを同じCollectorへ送信します。

export OTEL_EXPORTER_OTLP_ENDPOINT=http://collector:4318/mycollector/
export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=https://collector.example.com/v1/metrics/

トレースはhttp://collector:4318/mycollector/v1/tracesへ、ログはhttp://collector:4318/mycollector/v1/logsへ送信され、メトリクスはデフォルトのhttpsポート（443）を使ってhttps://collector.example.com/v1/metrics/へ送信されます。他のシグナル（存在する場合）は、http://collector:4318/mycollector/からの相対パスである、それぞれ固有のパスへ送信されます。

プロトコルの指定

OTEL_EXPORTER_OTLP_PROTOCOL、OTEL_EXPORTER_OTLP_TRACES_PROTOCOL、OTEL_EXPORTER_OTLP_METRICS_PROTOCOL、OTEL_EXPORTER_OTLP_LOGS_PROTOCOLの各環境変数は、OTLPのトランスポートプロトコルを指定します。サポートされる値は以下のとおりです。

grpc：HTTP/2接続上のgRPCワイヤー形式を使ったprotobufエンコードデータ用
http/protobuf：HTTP接続上のprotobufエンコードデータ用
http/json：HTTP接続上のJSONエンコードデータ用

SDKはgrpcとhttp/protobufの両方のトランスポートをSHOULDサポートするものとし、少なくとも一方をMUSTサポートするものとします。一方のみをサポートする場合、それはhttp/protobufにSHOULDすべきです。SDKはhttp/jsonもサポートしてもかまいません（MAY）。

設定が提供されない場合、デフォルトのトランスポートは、（grpcが安定版SDKリリースですでにデフォルトだった場合の後方互換性の理由などで）SDKがgrpcをデフォルトとして選ぶ十分な理由がない限り、http/protobufにSHOULDすべきです。

環境変数によるヘッダーの指定

OTEL_EXPORTER_OTLP_HEADERS、OTEL_EXPORTER_OTLP_TRACES_HEADERS、OTEL_EXPORTER_OTLP_METRICS_HEADERS、OTEL_EXPORTER_OTLP_LOGS_HEADERSの各環境変数には、キーと値の組の一覧が入り、W3C Baggageの形式、つまりkey1=value1,key2=value2に一致する形式で表現されることが期待されます。セミコロンで区切られたメタデータはサポートされません。すべての属性値は文字列としてMUST扱われるものとします。

リトライ

一時的なエラーは、リトライ戦略でMUST処理されるものとします。このリトライ戦略は、ネットワークが復旧するかデスティネーションが回復するまで宛先に負荷をかけすぎないよう、ジッターを伴う指数バックオフをMUST実装するものとします。

一時的なエラー

一時的なエラーは、OTLPプロトコル仕様書で定義されています。

OTLP/gRPCについては、一時的なエラーはリトライ可能なgRPCステータスコードの集合によって定義されます。

OTLP/HTTPについては、一時的なエラーは以下によって定義されます。

サーバーから受け取ったリトライ可能なHTTPステータスコードの集合。
以下に記載されているシナリオ。その他すべてのレスポンスとOTLP/HTTP接続。

User-Agent

OpenTelemetryのプロトコルエクスポーターは、少なくともエクスポーター、その実装言語、エクスポーターのバージョンを識別するために、User-AgentヘッダーをSHOULD送出するものとします。例えば、Python版OTLPエクスポーターのバージョン1.2.3は、以下を報告します。

OTel-OTLP-Exporter-Python/1.2.3

ヘッダーの形式はRFC 7231にSHOULD従うものとします。OpenTelemetry SDKの言語とバージョンを指定するための規約は、Resourceのセマンティック規約で利用できます。

エクスポーターは、User-Agentヘッダーに製品識別子を追加するための設定オプションを公開してもかまいません（MAY）。結果として生成されるUser-Agentには、エクスポーターのデフォルトのUser-Agent文字列がSHOULD含まれるものとします。これは、OpenTelemetry SDK/Agentのディストリビューションの識別子をサポートすることを意図しています。通常、エクスポーターは指定された識別子を自身の識別子の前に付加します。例えば、

MyDistribution/x.y.z OTel-OTLP-Exporter-Python/1.2.3