OpenTelemetry共通設定仕様

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

この仕様書の目的は、すべてのOpenTelemetry SDK設定ソースに適用可能な共通のガイダンスを説明することです。

実装は、この仕様書にあるいずれの設定ソースを介した設定も許容するように選択してもかまいません（MAY）が、それは必須ではありません。そうする場合は、本書に記載されたガイダンスにSHOULD従うものとします。

型ごとのガイダンス

数値

数値を受け付ける設定ソースは、以下のサブクラスに分類されます。

Integer
Duration
Timeout

以下のガイダンスはすべての数値型に適用されます。

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

数値を受け付けるソースについて、利用者が設定項目の有効範囲外の値を提供した場合、実装は警告を生成し、その設定を無視して未設定であるかのように扱うべきです（SHOULD）。特に、実装は、負の値が自然に適用されず、明示的に指定された意味を持たない場合に、負の値に対してカスタムの解釈（例えば「バッファをすべて使う」など）をSHOULD NOT割り当てるものとし、他の無効な値と同様に扱うものとします。

例えば、バッファサイズを指定する値は自然に非負でなければなりません。負の値を「すべてをバッファする」として扱うことは、こうした推奨されないカスタム解釈の一例です。代わりにデフォルトのバッファサイズが使われるべきです。

このカスタム解釈がデフォルト値と同一であったとしても差異が生じる可能性がある点に注意してください。これは、他の設定ソースから設定された値をデフォルト値でリセットしてしまうことがあるためです。

Integer

実装が整数値の設定ソースをサポートするように選択した場合、0から2³¹ − 1（両端を含む）の間の非負の値をSHOULDサポートするものとします。個々のSDKは、より大きな範囲の値をサポートするように選択してもかまいません（MAY）。

Duration

durationを表す値は、ミリ秒数を表す整数でなければなりません（MUST）。この値は非負です。負の値が指定された場合、実装は警告を生成し、その設定を無視して、定義されていればデフォルト値を使わなければなりません（MUST）。

例えば、値12000は12000ミリ秒、つまり12秒を示します。

Timeout

Timeoutの値はdurationの値に似ていますが、timeoutのゼロ値をどう解釈するかに違いがあるため（後述参照）、別の型として扱われます。

timeoutを表す値は、ミリ秒数を表す整数でなければなりません（MUST）。この値は非負です。負の値が指定された場合、実装は警告を生成し、その設定を無視して、定義されていればデフォルト値を使わなければなりません（MUST）。

例えば、値12000は12000ミリ秒、つまり12秒を示します。

実装は、timeoutのゼロ値（すなわち0ミリ秒を示す0）を無制限（すなわち無限）としてSHOULD解釈するものとします。実際には、実装は無制限を「非常に長い時間」として扱い、非常に大きなdurationの値（例えば32ビット整数で表現可能な最大ミリ秒数）を代わりに使ってもかまいません（MAY）。

文字列

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

Enum。

通常、文字列の値には、それが実装によってどのように解釈されるかを説明する注記が付きます。

Enum

既知の値の集合から1つを受け付ける設定ソース、すなわちenum値の場合、実装は、ここに列挙されていない値を追加でサポートしてもかまいません（MAY）。

設定エラーを報告する際、実装は、デバッグを支援するために元の利用者提供の値をSHOULD表示するものとします。

null値（空、no-op）が許容される場合、それを表すenum値は"none"でなければなりません（MUST）。