# OTLPエクスポーター

> Source: https://www.ymotongpoo.com/works/otel-specs-ja/spec/protocol/exporter/


**ステータス**: [Stable](/works/otel-specs-ja/spec/document-status/)

このドキュメントは、OpenTelemetry Protocol（[OTLP](https://github.com/open-telemetry/oteps/blob/main/text/0035-opentelemetry-protocol.md)）Exporterで利用できる設定オプションと、リトライの挙動を規定します。

## 設定オプション

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

- **Endpoint（OTLP/HTTP）**：エクスポーターがスパン、メトリクス、ログの送信先とするターゲットURL。実装は以下の[URLの構成要素](https://datatracker.ietf.org/doc/html/rfc3986#section-3)をMUST尊重するものとします。
  - スキーム（`http`または`https`）
  - ホスト
  - ポート
  - パス

  実装は、その他のすべてのURLの構成要素を無視してもかまいません（MAY）。

  スキームが`https`であることは、安全な接続を示します。`OTEL_EXPORTER_OTLP_ENDPOINT`を使う場合、エクスポーターは[以下で説明する](#otlphttpのエンドポイントurl)ようにシグナルごとのURLをMUST構築するものとします。シグナルごとのエンドポイント設定オプションは優先され、この挙動を上書きするために使えます（そのオプションを使う場合、URLは変更を加えずそのまま使われます）。詳細は[OTLP Specification][otlphttp-req]を参照してください。
  - デフォルト：`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-grpc-request]と[OTLP/HTTP][otlp-http-request]についてOTLP仕様書で定義されているとおり。
  - デフォルト：67108864（64 MiB = 64*1024*1024）
  - 型：[Integer][]

- **Max Response Size**：エクスポーターが受け入れるレスポンスメッセージの最大サイズ（バイト単位）。[OTLP/gRPC][otlp-grpc-response]と[OTLP/HTTP][otlp-http-response]についてOTLP仕様書で定義されているとおり。
  - デフォルト：4194304（4 MiB = 4*1024*1024）
  - 型：[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構築するものとします。

1. シグナルごとの変数（`OTEL_EXPORTER_OTLP_<signal>_ENDPOINT`）については、URLは変更を加えずそのままMUST使うものとします。唯一の例外は、URLにパス部分が含まれない場合、ルートパス`/`をMUST使うものとする点です（[例2](#例2)を参照）。
2. 前の項目に該当するシグナルごとの設定を持たないシグナルを送信する場合、`OTEL_EXPORTER_OTLP_ENDPOINT`がベースURLとして使われ、シグナルはそのベースURLからの相対パスへ送信されます。

   * トレース：`v1/traces`
   * メトリクス：`v1/metrics`
   * ログ：`v1/logs`

   非規範的には、これはベースURLの末尾がスラッシュで終わることを確認したうえで、相対URLを文字列として追加することで実装できます。

SDKは、上記で規定した以外の方法でURLを変更してはなりません（MUST NOT）。これは、ポートが空または指定されていない場合、通常のスキームの規則（[RFC 7230](https://datatracker.ietf.org/doc/html/rfc7230#section-2.7.1)）に従って、`http`スキームではTCPポート80、`https`スキームではTCPポート443がデフォルトになることも意味します。

#### 例1

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

```bash
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とパスへ送信されます。

```bash
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へ送信します。

```bash
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](https://www.w3.org/TR/baggage/#header-content)の形式、つまり`key1=value1,key2=value2`に一致する形式で表現されることが期待されます。[セミコロンで区切られたメタデータ](https://www.w3.org/TR/baggage/#property)はサポートされません。すべての属性値は文字列としてMUST扱われるものとします。

## リトライ

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

### 一時的なエラー

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

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

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

1. サーバーから受け取った[リトライ可能なHTTPステータスコード][retryable-http-status-codes]の集合。
2. 以下に記載されているシナリオ。[その他すべてのレスポンス](https://github.com/open-telemetry/opentelemetry-proto/blob/main/docs/specification.md#all-other-responses)と[OTLP/HTTP接続](https://github.com/open-telemetry/opentelemetry-proto/blob/main/docs/specification.md#otlphttp-connection)。

## User-Agent

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

```
OTel-OTLP-Exporter-Python/1.2.3
```

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

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

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

[Boolean]: /works/otel-specs-ja/spec/configuration/sdk-environment-variables/#boolean
[Timeout]: /works/otel-specs-ja/spec/configuration/common/#timeout
[String]: /works/otel-specs-ja/spec/configuration/common/#文字列
[Enum]: /works/otel-specs-ja/spec/configuration/common/#enum
[Integer]: /works/otel-specs-ja/spec/configuration/common/#integer

[resource-semconv]: https://github.com/open-telemetry/semantic-conventions/blob/main/docs/resource/README.md#telemetry-sdk
[otlphttp-req]: /works/otel-specs-ja/otlp/specification/#otlphttpリクエスト
[rfc-7231]: https://datatracker.ietf.org/doc/html/rfc7231#section-5.5.3
[protocol-spec]: /works/otel-specs-ja/otlp/specification/
[otlp-grpc]: /works/otel-specs-ja/otlp/specification/#otlpgrpc
[otlp-http]: /works/otel-specs-ja/otlp/specification/#otlphttp
[otlp-grpc-request]: /works/otel-specs-ja/otlp/specification/#otlpgrpcリクエスト
[otlp-grpc-response]: /works/otel-specs-ja/otlp/specification/#otlpgrpcレスポンス
[otlp-http-request]: /works/otel-specs-ja/otlp/specification/#otlphttpリクエスト
[otlp-http-response]: /works/otel-specs-ja/otlp/specification/#otlphttpレスポンス
[retryable-grpc-status-codes]: /works/otel-specs-ja/otlp/specification/#失敗
[retryable-http-status-codes]: /works/otel-specs-ja/otlp/specification/#失敗-1
[opentelemetry-distribution]: https://opentelemetry.io/docs/concepts/distributions/