設定の補足ガイドライン
この記事は英語の原文を日本語に翻訳したものです。原文: https://opentelemetry.io/docs/specs/otel/configuration/supplementary-guidelines/
翻訳元: open-telemetry/opentelemetry-specification v1.60.0（コミット 29ae8c7）
注記: この文書は仕様書ではありません。宣言的設定のAPIとSDKの仕様書を補助するために提供されるものであり、既存の仕様書に追加の要求事項を加えるものではありません。
設定インターフェースの優先順位とcreate
環境変数による設定インターフェースでは、この仕様書はプログラマティックな設定と環境変数による設定のどちらが優先されるのかという問いに答えられていませんでした。これは、実装間の差異を生み、それが最終的に安定化されてしまったために、事後に解消することが難しくなっていました。
宣言的設定では、設定インターフェースの優先順位に関する曖昧さはありません。
parseは、設定ファイルの内容を解析し、対応するインメモリのデータモデルを返す責任を負います。その過程で、環境変数の置換を実行します。createは、インメモリの設定データモデルを解釈し、SDKコンポーネントを作成する責任を負います。
環境変数による設定インターフェースには優先順位の曖昧さはありません。parseとcreateの言語仕様は責任範囲について明確であり、環境変数置換以外の場面で環境変数をマージするとはどこにも述べていません。
さらに、OTEL_EXPERIMENTAL_CONFIG_FILEは、環境変数による設定スキームが無視されることを明示的に述べています。
プログラマティックな設定インターフェースにも優先順位の曖昧さはありません。createはインメモリの設定データモデルを消費し、SDKコンポーネントを作成します。トレース・メトリクス・ログの各仕様書によれば、SDKは設定の更新をサポートしてもかまいません（MAY）が、宣言的設定はまだ存在しないものとの間で競合を起こしません。ただし、SDKが元々プログラマティックに設定されたSDKコンポーネントに対するプログラマティックな設定の更新を処理する場合、それはここでも当てはまります。SDKがそれをサポートする場合、すべてのプログラマティックな設定の更新は、createがSDKコンポーネントを初期化した後にMUST適用されるものとし、したがって優先されます。どのようなプログラマティックな設定の更新が許容され、それらが既存のSDKコンポーネントとどのようにマージされるかというセマンティクスは、宣言的設定の範囲外です。
プログラマティックなカスタマイズとcreate
createはプログラマティックなカスタマイズのためのオプションの機構を提供しますが、その使用はコードスメルとみなされるべきであり、宣言的設定のデータモデルを改善することで対処されるべきです。
例えば、OTLPエクスポーターの動的な認証の設定を宣言的設定で表現できないという事実は、OpenTelemetryコミュニティがプログラマティックなカスタマイズをより充実させることを促すべきではありません。代わりに、私たちは認証をSDKプラグインコンポーネントとして追加し、宣言的設定でモデル化することを追求すべきです。
厳格なYAML解析
以下に説明する実践は、データモデルで指定されているYAML 1.2 Core Schemaと、YAML処理に関する一般的なセキュリティのベストプラクティスから導出されたものです。
設定ファイルの作者は、言語間での可搬性を最大化し、以下のような一般的なYAMLの落とし穴を避けるために、Core Schemaの最小限の型システム（文字列、整数、浮動小数点数、ブーリアン、null）に自身を制約することが推奨されます。
- 意図しない型変換（例えばYAML 1.1で
NOが文字列"NO"ではなくブーリアンのfalseとして解析されるなど） - 任意コード実行を許容する言語固有のオブジェクトデシリアライズ機能によるセキュリティ脆弱性（例えばPythonの
!!python/objectタグ、Rubyの!ruby/objectタグなど） - 信頼できない入力においてアンカーやエイリアスのような複雑なYAML機能から生じる予期しない振る舞い
実装のYAMLライブラリが「safe」や「strict」なパーサーモード（例えばPythonのyaml.safe_load()、RubyのPsychのsafeモードなど）を提供している場合、それを使うことはこれらの制約を自動的に強制する良い方法です。