# 計装設定API

> Source: https://www.ymotongpoo.com/works/otel-specs-ja/spec/configuration/api/


**ステータス**: [Mixed](../../document-status/)

## 概要

計装設定APIは、[宣言的設定インターフェース](../#宣言的設定)の一部です。

このAPIは、[計装ライブラリ](/works/otel-specs-ja/spec/glossary/#instrumentation-library)が、初期化中に関連する設定を読み取ることで設定を利用できるようにします。例えば、HTTPクライアント向けの計装ライブラリは、捕捉すべきHTTPリクエスト・レスポンスヘッダーの集合を読み取れます。

このAPIは以下の主要なコンポーネントから構成されます。

* [ConfigProvider](#configprovider)はこのAPIのエントリーポイントです。
* [ConfigProperties](#configproperties)は、設定のマッピングノードのプログラマティックな表現です。

### ConfigProvider

**ステータス**: [Development](../../document-status/)

`ConfigProvider`は、計装に関連する設定プロパティへのアクセスを提供します。

計装ライブラリは初期化中に`ConfigProvider`にアクセスします。`ConfigProvider`は計装ライブラリへの引数として渡されるか、計装ライブラリが中央の場所からアクセスすることがあります。したがって、このAPIは、グローバルなデフォルトの`ConfigProvider`にアクセスし、それを設定・登録する方法をSHOULD提供するものとします。

#### ConfigProviderの操作

`ConfigProvider`は以下の関数をMUST提供するものとします。

* [計装設定の取得](#計装設定の取得)

TODO: APIの使いやすさを向上させるために追加の操作が必要かどうかを決定する

##### 計装設定の取得

計装ライブラリに関連する設定を取得します。

**戻り値:** [`.instrumentation`](https://github.com/open-telemetry/opentelemetry-configuration/blob/670901762dd5cce1eecee423b8660e69f71ef4be/examples/kitchen-sink.yaml#L438-L439)設定マッピングノードを表す[`ConfigProperties`](#configproperties)。

`.instrumentation`ノードが設定されていない場合、計装設定の取得は空の`ConfigProperties`を返すべきです（SHOULD）（`.instrumentation: {}`が設定された場合と同様に）。

### ConfigProperties

**ステータス**: [Stable](../../document-status/)

`ConfigProperties`は、設定マッピングノード（すなわちYAMLマッピングノード）のプログラマティックな表現です。

`ConfigProperties`は、それが表すマッピングノードからすべてのプロパティを読み取るためのアクセサーをMUST提供するものとし、これには以下が含まれます。

* スカラー（文字列、ブーリアン、倍精度浮動小数点数、64ビット整数）
* マッピング。これは`ConfigProperties`として表現されるべきです（SHOULD）
* スカラーのシーケンス
* マッピングのシーケンス。これは`ConfigProperties`として表現されるべきです（SHOULD）
* 存在するプロパティキーの集合

`ConfigProperties`は、言語にとってイディオマティックな方法で、型安全な形でプロパティへのアクセスをSHOULD提供するものとします。

`ConfigProperties`は、プロパティがnull値で存在するのか、それとも設定されていないのかを、呼び出し側が判別できるようにSHOULDするものとします。