OpenTelemetry環境変数仕様

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

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

ステータス: 安定（Stable）（別途明記されている箇所を除く）

この仕様書の目的は、異なるOpenTelemetryの実装間で環境変数名と値の解析を統一することです。

実装は、この仕様書にある環境変数を介した設定を許容するように選択してもかまいません（MAY）が、それは必須ではありません。 そうする場合は、本書で指定されている名前と値の解析の振る舞いをSHOULD使用するものとします。 また、共通設定仕様に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行われないものとします。

数値

以下のガイダンスはすべての数値型に適用され、共通設定仕様の「数値」に関するガイダンスを拡張します。

以下の段落は安定化の後に追加されたものであり、実装が破壊的変更を避けられるようにするため、要求事項は「SHOULD」として限定されています。 新しい実装については、これらをMUSTの要求事項として扱うべきです。

数値を受け付ける変数について、利用者が実装が解析できない値を提供した場合、実装は警告を生成し、その設定を無視して未設定であるかのように扱うべきです（SHOULD）。

文字列

文字列の値は、以下のサブクラスに分類されます。

• Enum。

Enum

以下のガイダンスは、共通設定仕様の「Enum」に関するガイダンスを拡張します。

Enumの値は、大文字小文字を区別しない方法でSHOULD解釈されるものとします。

enumの値を受け付けるソースについて、利用者が実装が認識しない値を提供した場合、実装は警告をMUST生成するものとし、その設定を無視してMUST受け流すものとします。

一般的なSDK設定

OTEL_PROPAGATORSの既知の値は以下の通りです。

• "tracecontext": W3C Trace Context
• "baggage": W3C Baggage
• "b3": B3 Single
• "b3multi": B3 Multi
• "jaeger": Jaeger - ステータス: Deprecated
• "xray": AWS X-Ray（サードパーティー）
• "ottrace": OT Trace（サードパーティー） - ステータス: Deprecated
• "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（サードパーティー）

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）。
  • pollingIntervalMs: サンプラーがサンプリング戦略の更新をバックエンドにポーリングする頻度をミリ秒で示します。
  • initialSamplingRate: [0..1]の範囲の値で、バックエンドに到達できずサンプリング戦略を取得できない場合にサンプリング確率として使われます。この値は、サンプリング戦略が正常に取得された後は効果を持たなくなります。取得に成功すると、新しい更新が取得されるまでリモートの戦略が使われるためです。
  • 例: endpoint=http://localhost:14250,pollingIntervalMs=5000,initialSamplingRate=0.25

Batch Span Processor

Batch LogRecord Processor

属性の上限

実装は、SDKが切り詰め機構を実装している属性の型についてのみ、環境変数をSHOULD提供するものとします。

この上限の定義については、SDKの属性の上限の節を参照してください。

Spanの上限

この上限の定義については、SDKのSpanの上限の節を参照してください。

LogRecordの上限

この上限の定義については、SDKのLogRecordの制限の節を参照してください。

OTLPエクスポーター

OpenTelemetry Protocol Exporter Configuration Optionsを参照してください。

Zipkinエクスポーター

ステータス: Deprecated

さらに、以下の環境変数はZipkinエクスポーターの設定における将来の使用のために予約されています。

• OTEL_EXPORTER_ZIPKIN_PROTOCOL

これは、エクスポーターがv1形式かv2形式か、JSON、thrift、protobufのいずれを使うかを指定するために使われます。この仕様書の1.0時点では、デフォルトや環境変数による設定は_指定されていません_。

Prometheusエクスポーター

ステータス: Development

エクスポーターの選択

シグナルごとに1つ以上のエクスポーターを設定するための環境変数を定義します。

実装は、複数のエクスポーターを有効にできるようカンマ区切りのリストを受け付けてもかまいません（MAY）。

OTEL_TRACES_EXPORTERの既知の値は以下の通りです。

• "otlp": OTLP
• "zipkin": Zipkin（デフォルトはprotobuf形式）
• "console": 標準出力
• "logging": 標準出力。後方互換性のために残された非推奨の値です。新しい実装ではSHOULD NOTサポートしないものとします。
• "none": トレース向けのエクスポーターを自動的に設定しません。

OTEL_METRICS_EXPORTERの既知の値は以下の通りです。

• "otlp": OTLP
• "prometheus": Prometheus
• "console": 標準出力
• "logging": 標準出力。後方互換性のために残された非推奨の値です。新しい実装ではSHOULD NOTサポートしないものとします。
• "none": メトリクス向けのエクスポーターを自動的に設定しません。

OTEL_LOGS_EXPORTERの既知の値は以下の通りです。

• "otlp": OTLP
• "console": 標準出力
• "logging": 標準出力。後方互換性のために残された非推奨の値です。新しい実装ではSHOULD NOTサポートしないものとします。
• "none": ログ向けのエクスポーターを自動的に設定しません。

開発中のエクスポーター選択

ステータス: Development

上記に加えて、開発中のエクスポーター選択のために以下の環境変数が追加されています。

OTEL_TRACES_EXPORTERの追加の既知の値は以下の通りです。

• "otlp/stdout": 標準出力へ書き出すOTLP File

OTEL_METRICS_EXPORTERの追加の既知の値は以下の通りです。

• "otlp/stdout": 標準出力へ書き出すOTLP File

OTEL_LOGS_EXPORTERの追加の既知の値は以下の通りです。

• "otlp/stdout": 標準出力へ書き出すOTLP File

メトリクスSDKの設定

Exemplar

OTEL_METRICS_EXEMPLAR_FILTERの既知の値は以下の通りです。

• "always_on": AlwaysOn
• "always_off": AlwaysOff
• "trace_based": TraceBased

Periodic exporting MetricReader

periodic exporting MetricReaderを使うpushメトリクスエクスポーター（OTLP、stdout、in-memory）に特有の環境変数です。

宣言的設定

宣言的設定に関連する環境変数です。

OTEL_CONFIG_FILEが設定されている場合、指定されたパスのファイルがParseの呼び出しに使われます。 その結果得られる設定モデルは、完全に設定されたSDKコンポーネントを生成するためにCreateの呼び出しに使われます。

OTEL_CONFIG_FILEが設定されている場合、環境変数の置換のために設定ファイル内で参照されているもの以外の他のすべての環境変数はMUST無視されるものとします。環境変数を無視することが必要な理由は、すべてのケースにおいてフラットな環境変数のスキームと構造化されたファイル設定のスキームをマージする直感的な方法が存在しないためです。複数の設定ソースをマージする必要がある利用者は、Createが呼び出される前にParseから返される設定モデルをカスタマイズすることが推奨されます。例えば、利用者は複数のファイルに対してParseを呼び出し、結果として得られる設定モデルをマージするロジックを定義したり、環境変数からの値を設定モデルの上に重ねたりする場合があります。実装は、OTEL_CONFIG_FILEから解析された設定モデルをカスタマイズする仕組みを提供してもかまいません（MAY）。

利用者は、OTEL_CONFIG_FILEの出発点としてotel-sdk-migration-config.yamlを使うことが推奨されます。このファイルは一般的なSDK設定のシナリオを表しており、それ以外の場合は無視される環境変数への環境変数置換の参照を含みます。 あるいは、otel-sdk-config.yamlは、環境変数置換の参照を伴わない、一般的なSDK設定の出発点を提供します。

TODO: 互換性のない環境変数を非推奨にする（#3967）

言語固有の環境変数

プロジェクト間で一貫した命名を確保するため、この仕様書は、言語固有の環境変数を以下の規則を使って形成することを推奨します。

OTEL_{LANGUAGE}_{FEATURE}