設定データモデル

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

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

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

概要

OpenTelemetryの設定データモデルは、宣言的設定インターフェースの一部です。

このデータモデルは、利用者がOpenTelemetry SDKコンポーネントと計装の意図した設定を指定できるようにするデータ構造を定義します。

このデータモデルは、JSON Schemaを使ってopentelemetry-configurationの中で定義されています。

データモデル自体は抽象であり、複数の組み込み表現を持ちます。

• File-based configuration model
• SDK in-memory configuration model

バージョニング方針と安定性の保証

opentelemetry-configurationのバージョニング方針を参照してください。

File-based configuration model

設定ファイルは、設定データモデルのシリアライズされたファイルベースの表現です。

設定ファイルは、以下のシリアライズ形式のいずれかをSHOULD使用するものとします。

• YAML file format

YAML file format

YAML設定ファイルは、YAML仕様のリビジョン1.2以上にSHOULD従うものとします。

YAML設定ファイルは、v1.2 YAML core schemaを使って解析されるべきです（SHOULD）。

YAML設定ファイルは、拡張子.yamlまたは.ymlをMUST使用するものとします。

Environment variable substitution

設定ファイルは、Augmented Backus-Naur Formを使って定義された参照のための環境変数置換をサポートします。

SUBSTITUTION-REF = "${" [PREFIX ":"] GENERIC-SUBSTITUTION "}"; generic substitution reference

; when PREFIX is absent or "env", GENERIC-SUBSTITUTION MUST conform to ENV-SUBSTITUTION:
ENV-SUBSTITUTION = ENV-NAME [":-" DEFAULT-VALUE]; env var substitution

PREFIX = ALPHA *(ALPHA / DIGIT / "_"); substitution prefix, e.g. "env" (universal) or language-specific
GENERIC-SUBSTITUTION = 1*(VCHAR-WSP-NO-RBRACE); substitution content, interpretation depends on PREFIX
ENV-NAME = (ALPHA / "_") *(ALPHA / DIGIT / "_"); the name of the environment variable to be substituted
DEFAULT-VALUE = *(VCHAR-WSP-NO-RBRACE); any number of VCHAR-WSP-NO-RBRACE
VCHAR-WSP-NO-RBRACE = %x21-7C / "~" / WSP; printable chars and whitespace, except }

ALPHA = %x41-5A / %x61-7A; A-Z / a-z
DIGIT = %x30-39 ; 0-9

SUBSTITUTION-REFは有効な置換参照を定義します。

• ${で始まらなければなりません
• 任意でPREFIX:が続きます。PREFIXはenv（汎用）または言語固有の識別子です
• GENERIC-SUBSTITUTION（}を除く少なくとも1つの表示可能文字または空白）が続かなければなりません
• }が続かなければなりません

PREFIXが存在しない、またはenvである場合、GENERIC-SUBSTITUTIONはENV-SUBSTITUTIONにMUST準拠するものとします。

• 置換対象の環境変数の名前であるENV-NAMEで始まらなければなりません
  • アルファベットまたは_文字で始まらなければなりません
  • 任意の数の英数字または_文字が続かなければなりません
• 任意でデフォルト値が続きます
  • :-で始まらなければなりません
  • }と空白を除く任意の数の表示可能文字であるDEFAULT-VALUEが続かなければなりません

言語の実装は、言語固有の設定ソースへアクセスするために、env:を超える追加のプレフィックスをサポートしてもかまいません（MAY）。GENERIC-SUBSTITUTIONの内容は、PREFIXのスキームに従って解釈されます。例えばJavaの実装では、システムプロパティにアクセスするためにsys:をサポートする場合があります（${sys:otel.service.name}）。言語の実装は、サポートする追加のプレフィックスをSHOULD文書化するものとします。

便宜上、SUBSTITUTION-REFとENV-SUBSTITUTIONは以下でPCRE2の正規表現として表現されています。これらの表現は非規範的であることに注意してください。

// SUBSTITUTION-REF
\$\{(?:(?<PREFIX>[a-zA-Z][a-zA-Z0-9_]*):)?(?<GENERIC_SUBSTITUTION>[^}]+)\}

// ENV-SUBSTITUTION (applied to GENERIC_SUBSTITUTION when PREFIX is absent or "env")
(?<ENV_NAME>[a-zA-Z_][a-zA-Z0-9_]*)(:-(?<DEFAULT_VALUE>[^\n]*))?

例えば、${API_KEY}と${env:API_KEY}は有効な環境変数置換ですが、${1API_KEY}と${API_$KEY}はENV-SUBSTITUTIONに準拠しないため無効です。

環境変数置換は、スカラー値にのみMUST適用されるものとします。マッピングのキーは置換の対象外です。

SUBSTITUTION-REFのDEFAULT-VALUEの部分は、ENV-NAMEがnull、空、または未定義の場合に置換される任意のフォールバック値です。参照された環境変数が定義されておらず、DEFAULT-VALUEも持たない場合、それは空の値へMUST置き換えられるものとします。

$文字はエスケープシーケンスであり、入力中の$$は出力中の単一の$へ変換されます。エスケープシーケンスから解決された$は、入力を環境変数置換の正規表現に対してマッチングする際にMUST NOT考慮されないものとします。例えば、$${API_KEY}は${API_KEY}に解決され、API_KEY環境変数の値は置換されません。より多くの例については下の表を参照してください。実際には、これはパーサーが入力を左から右に消費し、次のエスケープシーケンスを反復的に識別し、直前のエスケープシーケンス以降の内容をSUBSTITUTION-REFに対してマッチングすることを意味します。

例えば、FOO=a, BAR=b, BAZ=cのとき、入力$${FOO} ${BAR} $${BAZ}を処理する疑似コードは以下のようになります。

• インデックス0でエスケープシーケンス$$を識別します。input.substring(0, 0)=""に対して置換を実行すると""になり、これを出力に追加します。$を出力に追加します。現在の出力: "$"。
• インデックス15でエスケープシーケンス$$を識別します。input.substring(0+2, 15)="{FOO} ${BAR} "に対して置換を実行すると"{FOO} b "になり、これを出力に追加します。$を出力に追加します。現在の出力: "${FOO} b $"。
• エスケープシーケンスなしで入力の終端に達します。input.substring(15+2, input.length)="{BAZ}"に対して置換を実行すると"{BAZ}"になります。出力を返します: "${FOO} b ${BAZ}"。

GENERIC-SUBSTITUTIONがそのスキームの検証規則に準拠しないSUBSTITUTION-REFを含む設定ファイル（例えばPREFIXが存在しないかenvである場合にENV-SUBSTITUTIONに準拠しない場合）を解析する際、パーサーは空の結果を返さなければならず（部分的な結果は許容されません）、解析の失敗を説明するエラーを利用者に返さなければなりません（MUST）。

ノードの型は、環境変数置換が行われた後にMUST解釈されるものとします。これにより、ブーリアン、整数、浮動小数点数のプロパティの環境変数文字列表現が、期待される型へ適切に変換されることが保証されます。

環境変数によってYAML構造を注入することがMUST NOT可能であるものとします。例えば、以下のINVALID_MAP_VALUE環境変数への参照を参照してください。

環境変数によって環境変数を注入することがMUST NOT可能であるものとします。例えば、以下のDO_NOT_REPLACE_ME環境変数への参照を参照してください。

以下の表は、さまざまな入力に対する環境変数置換の振る舞いを示しています。これらの例は、環境変数が以下のように設定されていることを前提としています。

export STRING_VALUE="value"
export BOOL_VALUE="true"
export INT_VALUE="1"
export FLOAT_VALUE="1.1"
export HEX_VALUE="0xdeadbeef"                   # A valid integer value (i.e. 3735928559) written in hexadecimal
export INVALID_MAP_VALUE="value\nkey:value"     # An invalid attempt to inject a map key into the YAML
export DO_NOT_REPLACE_ME="Never use this value" # An unused environment variable
export REPLACE_ME='${DO_NOT_REPLACE_ME}'        # A valid replacement text, used verbatim, not replaced with "Never use this value"
export VALUE_WITH_ESCAPE='value$$'              # A valid variable substituted without escaping