# OpenTelemetry環境変数仕様 > Source: https://www.ymotongpoo.com/works/otel-specs-ja/spec/configuration/sdk-environment-variables/ **ステータス**: [安定（Stable）](../../document-status/)（別途明記されている箇所を除く） この仕様書の目的は、異なるOpenTelemetryの実装間で環境変数名と値の解析を統一することです。 実装は、この仕様書にある環境変数を介した設定を許容するように選択してもかまいません（MAY）が、それは必須ではありません。 そうする場合は、本書で指定されている名前と値の解析の振る舞いをSHOULD使用するものとします。 また、[共通設定仕様](../common/)にSHOULD従うものとします。 ## 実装ガイドライン 環境変数は、コンポーネントによって直接、SDKの中で、あるいは別のコンポーネント（例えば環境変数ベースの自動設定コンポーネント）の中で処理（実装）されてもかまいません（MAY）。 環境変数ベースの設定には、対応するコード上の設定と同等の手段がMUST存在するものとします。 ## 空の値の解析 SDKは、環境変数の空の値を、その変数が未設定である場合と同じ方法でMUST解釈するものとします。 ## 型ごとのガイダンス ### Boolean ブーリアンを表す値は、大文字小文字を区別しない文字列`"true"`（すなわち`"True"`や`"TRUE"`も受け付けられます）によってのみtrueにMUST設定されるものとします。実装は、この定義を拡張し、trueと解釈される値を追加でMUST NOT定義するものとします。ここでtrueの値として明示的に定義されていない値は、未設定や空の値を含めてすべてfalseとMUST解釈されるものとします。true値、大文字小文字を区別しない文字列`"false"`、空、または未設定のいずれでもない値が使われた場合、falseへのフォールバックが適用されたことを利用者に知らせる警告がSHOULDログに記録されるものとします。すべてのブーリアン環境変数は、falseが期待される安全なデフォルトの振る舞いとなるようにSHOULD名付け・定義されるものとします。 名前の変更やデフォルト値の変更は、メジャーバージョンのアップグレードなしにMUST NOT行われないものとします。 ### 数値 以下のガイダンスはすべての数値型に適用され、[共通設定仕様の「数値」に関するガイダンス](../common/#数値)を拡張します。 > 以下の段落は安定化の後に追加されたものであり、実装が破壊的変更を避けられるようにするため、要求事項は「SHOULD」として限定されています。 > 新しい実装については、これらをMUSTの要求事項として扱うべきです。 数値を受け付ける変数について、利用者が実装が解析できない値を提供した場合、実装は警告を生成し、その設定を無視して未設定であるかのように扱うべきです（SHOULD）。 ### 文字列 文字列の値は、以下のサブクラスに分類されます。 * [Enum][]。 #### Enum 以下のガイダンスは、[共通設定仕様の「Enum」に関するガイダンス](../common/#enum)を拡張します。 Enumの値は、大文字小文字を区別しない方法でSHOULD解釈されるものとします。 enumの値を受け付けるソースについて、利用者が実装が認識しない値を提供した場合、実装は警告をMUST生成するものとし、その設定を無視してMUST受け流すものとします。 ## 一般的なSDK設定 | 名前 | 説明 | デフォルト | 型 | 注記 | |--------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | OTEL_SDK_DISABLED | すべてのシグナルについてSDKを無効化する | false | [Boolean][] | "true"の場合、すべてのテレメトリーシグナルに対してno-opのSDK実装が使われます。それ以外の値、または変数が存在しない場合は効果がなく、SDKは有効なままです。この設定は、OTEL_PROPAGATORS変数を通じて設定されるプロパゲーターには影響しません。 | | OTEL_ENTITIES | リソースに関連付けられるエンティティ情報 | | [String][] | 詳細は[Entities SDK](/works/otel-specs-ja/spec/entities/entity-propagation/#環境変数によるentity情報の指定)を参照してください。 | | OTEL_RESOURCE_ATTRIBUTES | リソース属性として使われるキーと値の組 | 詳細は[Resourceのセマンティック規約](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/resource/README.md#semantic-attributes-with-dedicated-environment-variable)を参照してください。 | [String][] | 詳細は[Resource SDK](/works/otel-specs-ja/spec/resource/sdk/#環境変数によるリソース情報の指定)を参照してください。 | | OTEL_SERVICE_NAME | [`service.name`](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/resource/README.md#service)リソース属性の値を設定する | | [String][] | `service.name`が`OTEL_RESOURCE_ATTRIBUTES`でも提供されている場合、`OTEL_SERVICE_NAME`が優先されます。 | | OTEL_LOG_LEVEL | [SDK内部ロガー](/works/otel-specs-ja/spec/error-handling/#自己診断)によって使われるログレベル | "info" | [Enum][] | | | OTEL_PROPAGATORS | カンマ区切りのリストとして使われるプロパゲーター | "tracecontext,baggage" | [Enum][] | `Propagator`が1回だけ登録されるように、値は重複を除去されなければなりません（MUST）。 | | OTEL_TRACES_SAMPLER | トレースに使われるSampler | "parentbased_always_on" | [Enum][] | [サンプリング](/works/otel-specs-ja/spec/trace/sdk/#サンプリング)を参照してください | | OTEL_TRACES_SAMPLER_ARG | Samplerの引数として使われる値 | | 脚注を参照 | 指定された値は、OTEL_TRACES_SAMPLERが設定されている場合にのみ使われます。各Sampler種別は、入力があればそれぞれ独自の期待する入力を定義します。無効な値や認識されない値はMUSTログに記録されるものとし、それ以外の点ではMUST無視されるものとします。すなわち、実装はOTEL_TRACES_SAMPLER_ARGが設定されていないかのようにMUST振る舞うものとします。 | `OTEL_PROPAGATORS`の既知の値は以下の通りです。 - `"tracecontext"`: [W3C Trace Context](https://www.w3.org/TR/trace-context/) - `"baggage"`: [W3C Baggage](https://www.w3.org/TR/baggage/) - `"b3"`: [B3 Single](/works/otel-specs-ja/spec/context/api-propagators/#configuration) - `"b3multi"`: [B3 Multi](/works/otel-specs-ja/spec/context/api-propagators/#configuration) - `"jaeger"`: [Jaeger](https://www.jaegertracing.io/sdk-migration/#propagation-format) - **ステータス**: [Deprecated](../../document-status/) - `"xray"`: [AWS X-Ray](https://docs.aws.amazon.com/xray/latest/devguide/xray-concepts.html#xray-concepts-tracingheader)（_サードパーティー_） - `"ottrace"`: [OT Trace](https://github.com/opentracing?q=basic&type=&language=)（_サードパーティー_） - **ステータス**: [Deprecated](../../document-status/) - `"none"`: プロパゲーターを自動的に設定しません。 `OTEL_TRACES_SAMPLER`の既知の値は以下の通りです。 - `"always_on"`: `AlwaysOnSampler` - `"always_off"`: `AlwaysOffSampler` - `"traceidratio"`: `TraceIdRatioBased` - `"parentbased_always_on"`: `ParentBased(root=AlwaysOnSampler)` - `"parentbased_always_off"`: `ParentBased(root=AlwaysOffSampler)` - `"parentbased_traceidratio"`: `ParentBased(root=TraceIdRatioBased)` - `"parentbased_jaeger_remote"`: `ParentBased(root=JaegerRemoteSampler)` - `"jaeger_remote"`: `JaegerRemoteSampler` - `"xray"`: [AWS X-Ray Centralized Sampling](https://docs.aws.amazon.com/xray/latest/devguide/xray-console-sampling.html)（_サードパーティー_） `OTEL_TRACES_SAMPLER`の値に応じて、`OTEL_TRACES_SAMPLER_ARG`は以下のように設定される場合があります。 - `traceidratio`と`parentbased_traceidratio`のSamplerの場合: サンプリング確率。`[0..1]`の範囲の数値、例えば"0.25"。未設定の場合のデフォルトは1.0です。 - `jaeger_remote`と`parentbased_jaeger_remote`の場合: 値はカンマ区切りのリストです。 - `endpoint`: サービス向けのサンプリング戦略を提供するgRPCサーバーの`scheme://host:port`という形式のエンドポイント（[sampling.proto](https://github.com/jaegertracing/jaeger-idl/blob/main/proto/api_v2/sampling.proto)）。 - `pollingIntervalMs`: サンプラーがサンプリング戦略の更新をバックエンドにポーリングする頻度をミリ秒で示します。 - `initialSamplingRate`: `[0..1]`の範囲の値で、バックエンドに到達できずサンプリング戦略を取得できない場合にサンプリング確率として使われます。この値は、サンプリング戦略が正常に取得された後は効果を持たなくなります。取得に成功すると、新しい更新が取得されるまでリモートの戦略が使われるためです。 - 例: `endpoint=http://localhost:14250,pollingIntervalMs=5000,initialSamplingRate=0.25` ## Batch Span Processor | 名前 | 説明 | デフォルト | 型 | 注記 | |--------------------------------|------------------------------------------------------------------|---------|--------------|-----------------------------------------------------------------------------------| | OTEL_BSP_SCHEDULE_DELAY | 2回の連続したエクスポートの間の遅延（ミリ秒） | 5000 | [Duration][] | | | OTEL_BSP_EXPORT_TIMEOUT | データのエクスポートに許容される最大時間（ミリ秒） | 30000 | [Timeout][] | | | OTEL_BSP_MAX_QUEUE_SIZE | 最大キューサイズ | 2048 | [Integer][] | 有効な値は正の値です。 | | OTEL_BSP_MAX_EXPORT_BATCH_SIZE | 最大バッチサイズ | 512 | [Integer][] | OTEL_BSP_MAX_QUEUE_SIZE以下でなければなりません（MUST）。有効な値は正の値です。 | ## Batch LogRecord Processor | 名前 | 説明 | デフォルト | 型 | 注記 | |---------------------------------|------------------------------------------------------------------|---------|--------------|------------------------------------------------------------------------------------| | OTEL_BLRP_SCHEDULE_DELAY | 2回の連続したエクスポートの間の遅延（ミリ秒） | 1000 | [Duration][] | | | OTEL_BLRP_EXPORT_TIMEOUT | データのエクスポートに許容される最大時間（ミリ秒） | 30000 | [Timeout][] | | | OTEL_BLRP_MAX_QUEUE_SIZE | 最大キューサイズ | 2048 | [Integer][] | 有効な値は正の値です。 | | OTEL_BLRP_MAX_EXPORT_BATCH_SIZE | 最大バッチサイズ | 512 | [Integer][] | OTEL_BLRP_MAX_QUEUE_SIZE以下でなければなりません（MUST）。有効な値は正の値です。 | ## 属性の上限 実装は、SDKが切り詰め機構を実装している属性の型についてのみ、環境変数をSHOULD提供するものとします。 この上限の定義については、SDKの[属性の上限](/works/otel-specs-ja/spec/common/#attribute-limits)の節を参照してください。 | 名前 | 説明 | デフォルト | 型 | 注記 | |-----------------------------------|--------------------------------------|----------|-------------|--------------------------------| | OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT | 許容される属性値の最大サイズ | 上限なし | [Integer][] | 有効な値は非負の値です。 | | OTEL_ATTRIBUTE_COUNT_LIMIT | 許容される属性数の最大値 | 128 | [Integer][] | 有効な値は非負の値です。 | ## Spanの上限 この上限の定義については、SDKの[Spanの上限](/works/otel-specs-ja/spec/trace/sdk/#spanの上限)の節を参照してください。 | 名前 | 説明 | デフォルト | 型 | 注記 | |----------------------------------------|------------------------------------------------|----------|-------------|--------------------------------| | OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT | 許容される属性値の最大サイズ | 上限なし | [Integer][] | 有効な値は非負の値です。 | | OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT | 許容されるSpan属性数の最大値 | 128 | [Integer][] | 有効な値は非負の値です。 | | OTEL_SPAN_EVENT_COUNT_LIMIT | 許容されるSpanイベント数の最大値 | 128 | [Integer][] | 有効な値は非負の値です。 | | OTEL_SPAN_LINK_COUNT_LIMIT | 許容されるSpanリンク数の最大値 | 128 | [Integer][] | 有効な値は非負の値です。 | | OTEL_EVENT_ATTRIBUTE_COUNT_LIMIT | Spanイベントごとに許容される属性数の最大値 | 128 | [Integer][] | 有効な値は非負の値です。 | | OTEL_LINK_ATTRIBUTE_COUNT_LIMIT | Spanリンクごとに許容される属性数の最大値 | 128 | [Integer][] | 有効な値は非負の値です。 | ## LogRecordの上限 この上限の定義については、SDKの[LogRecordの制限](/works/otel-specs-ja/spec/logs/sdk/#logrecordの制限)の節を参照してください。 | 名前 | 説明 | デフォルト | 型 | 注記 | |---------------------------------------------|--------------------------------------------|----------|-------------|--------------------------------| | OTEL_LOGRECORD_ATTRIBUTE_VALUE_LENGTH_LIMIT | 許容される属性値の最大サイズ | 上限なし | [Integer][] | 有効な値は非負の値です。 | | OTEL_LOGRECORD_ATTRIBUTE_COUNT_LIMIT | 許容されるログレコード属性数の最大値 | 128 | [Integer][] | 有効な値は非負の値です。 | ## OTLPエクスポーター [OpenTelemetry Protocol Exporter Configuration Options](/works/otel-specs-ja/spec/protocol/exporter/)を参照してください。 ## Zipkinエクスポーター **ステータス**: [Deprecated](../../document-status/) | 名前 | 説明 | デフォルト | 型 | |-------------------------------|-------------------------------------------------------------------------------------|--------------------------------------|-------------| | OTEL_EXPORTER_ZIPKIN_ENDPOINT | Zipkinトレース向けのエンドポイント | `http://localhost:9411/api/v2/spans` | [String][] | | OTEL_EXPORTER_ZIPKIN_TIMEOUT | Zipkinエクスポーターが各バッチのエクスポートを待機する最大時間（ミリ秒） | 10000 | [Timeout][] | さらに、以下の環境変数はZipkinエクスポーターの設定における将来の使用のために予約されています。 - `OTEL_EXPORTER_ZIPKIN_PROTOCOL` これは、エクスポーターがv1形式かv2形式か、JSON、thrift、protobufのいずれを使うかを指定するために使われます。この仕様書の1.0時点では、デフォルトや環境変数による設定は_指定されていません_。 ## Prometheusエクスポーター **ステータス**: [Development](../../document-status/) | 名前 | 説明 | デフォルト | 型 | |-------------------------------|--------------------------------------|-------------|-------------| | OTEL_EXPORTER_PROMETHEUS_HOST | Prometheusエクスポーターが使うホスト | "localhost" | [String][] | | OTEL_EXPORTER_PROMETHEUS_PORT | Prometheusエクスポーターが使うポート | 9464 | [Integer][] | ## エクスポーターの選択 シグナルごとに1つ以上のエクスポーターを設定するための環境変数を定義します。 | 名前 | 説明 | デフォルト | 型 | |-----------------------|-----------------------------|---------|----------| | OTEL_TRACES_EXPORTER | 使用するトレースエクスポーター | `otlp` | [Enum][] | | OTEL_METRICS_EXPORTER | 使用するメトリクスエクスポーター | `otlp` | [Enum][] | | OTEL_LOGS_EXPORTER | 使用するログエクスポーター | `otlp` | [Enum][] | 実装は、複数のエクスポーターを有効にできるようカンマ区切りのリストを受け付けてもかまいません（MAY）。 `OTEL_TRACES_EXPORTER`の既知の値は以下の通りです。 - `"otlp"`: [OTLP](https://opentelemetry.io/docs/specs/otlp/) - `"zipkin"`: [Zipkin](https://zipkin.io/zipkin-api/)（デフォルトは[protobuf](https://github.com/openzipkin/zipkin-api/blob/master/zipkin.proto)形式） - `"console"`: [標準出力](/works/otel-specs-ja/spec/trace/sdk_exporters/stdout/) - `"logging"`: [標準出力](/works/otel-specs-ja/spec/trace/sdk_exporters/stdout/)。後方互換性のために残された非推奨の値です。新しい実装ではSHOULD NOTサポートしないものとします。 - `"none"`: トレース向けのエクスポーターを自動的に設定しません。 `OTEL_METRICS_EXPORTER`の既知の値は以下の通りです。 - `"otlp"`: [OTLP](https://opentelemetry.io/docs/specs/otlp/) - `"prometheus"`: [Prometheus](https://github.com/prometheus/docs/blob/main/docs/instrumenting/exposition_formats.md) - `"console"`: [標準出力](/works/otel-specs-ja/spec/metrics/sdk_exporters/stdout/) - `"logging"`: [標準出力](/works/otel-specs-ja/spec/metrics/sdk_exporters/stdout/)。後方互換性のために残された非推奨の値です。新しい実装ではSHOULD NOTサポートしないものとします。 - `"none"`: メトリクス向けのエクスポーターを自動的に設定しません。 `OTEL_LOGS_EXPORTER`の既知の値は以下の通りです。 - `"otlp"`: [OTLP](https://opentelemetry.io/docs/specs/otlp/) - `"console"`: [標準出力](/works/otel-specs-ja/spec/logs/sdk_exporters/stdout/) - `"logging"`: [標準出力](/works/otel-specs-ja/spec/logs/sdk_exporters/stdout/)。後方互換性のために残された非推奨の値です。新しい実装ではSHOULD NOTサポートしないものとします。 - `"none"`: ログ向けのエクスポーターを自動的に設定しません。 ### 開発中のエクスポーター選択 **ステータス**: [Development](../../document-status/) 上記に加えて、開発中のエクスポーター選択のために以下の環境変数が追加されています。 `OTEL_TRACES_EXPORTER`の追加の既知の値は以下の通りです。 - `"otlp/stdout"`: 標準出力へ書き出す[OTLP File](/works/otel-specs-ja/spec/protocol/file-exporter/) `OTEL_METRICS_EXPORTER`の追加の既知の値は以下の通りです。 - `"otlp/stdout"`: 標準出力へ書き出す[OTLP File](/works/otel-specs-ja/spec/protocol/file-exporter/) `OTEL_LOGS_EXPORTER`の追加の既知の値は以下の通りです。 - `"otlp/stdout"`: 標準出力へ書き出す[OTLP File](/works/otel-specs-ja/spec/protocol/file-exporter/) ## メトリクスSDKの設定 ### Exemplar | 名前 | 説明 | デフォルト | 型 | |--------------------------------|-----------------------------------------------------|-----------------|----------| | `OTEL_METRICS_EXEMPLAR_FILTER` | 測定値がExemplarになれるかどうかのフィルター。 | `"trace_based"` | [Enum][] | `OTEL_METRICS_EXEMPLAR_FILTER`の既知の値は以下の通りです。 - `"always_on"`: [AlwaysOn](/works/otel-specs-ja/spec/metrics/sdk/#alwayson) - `"always_off"`: [AlwaysOff](/works/otel-specs-ja/spec/metrics/sdk/#alwaysoff) - `"trace_based"`: [TraceBased](/works/otel-specs-ja/spec/metrics/sdk/#tracebased) ### Periodic exporting MetricReader [periodic exporting MetricReader](/works/otel-specs-ja/spec/metrics/sdk/#periodic-exporting-metricreader)を使うpushメトリクスエクスポーター（OTLP、stdout、in-memory）に特有の環境変数です。 | 名前 | 説明 | デフォルト | 型 | |-------------------------------|-------------------------------------------------------------------------------|---------|--------------| | `OTEL_METRIC_EXPORT_INTERVAL` | 2回のエクスポート試行の開始の間の時間間隔（ミリ秒）。 | 60000 | [Duration][] | | `OTEL_METRIC_EXPORT_TIMEOUT` | データのエクスポートに許容される最大時間（ミリ秒）。 | 30000 | [Timeout][] | ## 宣言的設定 [宣言的設定](../#宣言的設定)に関連する環境変数です。 | 名前 | 説明 | デフォルト | 型 | 注記 | |---------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------|------------|--------------------------------------------------| | `OTEL_EXPERIMENTAL_CONFIG_FILE` | SDKを設定するために使われる設定ファイルのパス。設定されている場合、このファイル内の設定は他のすべてのSDK設定用環境変数よりも優先されます。 | | [String][] | **非推奨**。代わりに`OTEL_CONFIG_FILE`を使ってください。 | | `OTEL_CONFIG_FILE` | SDKを設定するために使われる設定ファイルのパス。設定されている場合、このファイル内の設定は他のすべてのSDK設定用環境変数よりも優先されます。 | | [String][] | 下記参照 | `OTEL_CONFIG_FILE`が設定されている場合、指定されたパスのファイルが[Parse](../sdk/#parse)の呼び出しに使われます。 その結果得られる[設定モデル](../sdk/#in-memory-configuration-model)は、完全に設定されたSDKコンポーネントを生成するために[Create](../sdk/#create)の呼び出しに使われます。 `OTEL_CONFIG_FILE`が設定されている場合、[環境変数の置換](../data-model/#environment-variable-substitution)のために設定ファイル内で参照されているもの以外の他のすべての環境変数はMUST無視されるものとします。環境変数を無視することが必要な理由は、すべてのケースにおいてフラットな環境変数のスキームと構造化されたファイル設定のスキームをマージする直感的な方法が存在しないためです。複数の設定ソースをマージする必要がある利用者は、`Create`が呼び出される前に`Parse`から返される設定モデルをカスタマイズすることが推奨されます。例えば、利用者は複数のファイルに対して`Parse`を呼び出し、結果として得られる設定モデルをマージするロジックを定義したり、環境変数からの値を設定モデルの上に重ねたりする場合があります。実装は、`OTEL_CONFIG_FILE`から解析された設定モデルをカスタマイズする仕組みを提供してもかまいません（MAY）。 利用者は、`OTEL_CONFIG_FILE`の出発点として[`otel-sdk-migration-config.yaml`](https://github.com/open-telemetry/opentelemetry-configuration/blob/main/examples/otel-sdk-migration-config.yaml)を使うことが推奨されます。このファイルは一般的なSDK設定のシナリオを表しており、それ以外の場合は無視される環境変数への環境変数置換の参照を含みます。 あるいは、[`otel-sdk-config.yaml`](https://github.com/open-telemetry/opentelemetry-configuration/blob/main/examples/otel-sdk-config.yaml)は、環境変数置換の参照を伴わない、一般的なSDK設定の出発点を提供します。 TODO: 互換性のない環境変数を非推奨にする（[#3967](https://github.com/open-telemetry/opentelemetry-specification/issues/3967)） ## 言語固有の環境変数 プロジェクト間で一貫した命名を確保するため、この仕様書は、言語固有の環境変数を以下の規則を使って形成することを推奨します。 ``` OTEL_{LANGUAGE}_{FEATURE} ``` [Boolean]: #boolean [Integer]: ../common/#integer [Duration]: ../common/#duration [Timeout]: ../common/#timeout [String]: ../common/#文字列 [Enum]: ../common/#enum