> Source: https://www.ymotongpoo.com/works/oteps/entities/otep-4665/


# OTEP-4665: SDKにおける複数のリソース

SDKごとに複数の`Resource`インスタンスを許可します。

## 動機 {#motivation}

OpenTelemetryは2つの基本的な問題に対処する必要があります。

- 「可変」または「変化する」エンティティに対してデータを報告することです。
  現在、SDKには単一の`Resource`のみが許可されており、そのライフタイムはSDK自体のライフタイムと一致しなければなりません。
- 真のマルチテナント機能を提供することです。
  例えば、あるテナントに関するメトリクスは、別のテナントに関するメトリクスから暗黙的に分離されます。

最初の問題については、（未採択の）[OTEP 4316](https://github.com/open-telemetry/opentelemetry-specification/pull/4316)で詳しく説明されています。
基本的に、不変のアイデンティティが必要である一方で、現実には、今日のOpenTelemetryの利用における`Resource`は、主要なユースケースを支えるには十分な強さを持っていません。
例えば、Node.js環境のOpenTelemetry JSでは、Resourceのすべての識別属性がSDKの起動前に検出されることを保証できず、Specificationで対処すべき「eventual identity」という状況につながっています。
さらに、私たちのClient/Browser SIGは、SDK自体よりもはるかに短いライフスパンを持つ「User Session」という概念をモデル化しようとしてきました。
そのため、不変でありながらSDKのライフタイムと一致する単一のアイデンティティを要求することは、ユーザーセッションを報告するための優れたメカニズムを妨げてしまいます。

しかし、[OTEP 4316](https://github.com/open-telemetry/opentelemetry-specification/pull/4316)では、新しいメカニズムを提供する代わりに、不変性の制約を緩和する方向を検討しています。
プロトタイピングの当初は、これは簡単に実現できるように見えました。
しかし、SDKの安定したアイデンティティが望まれるOpAMPとの相互作用と、Metrics SDKの設計の両方で大きな問題に直面しました。
Metrics SDKの設計では、Resourceの変更が動的で分岐したストレージ戦略を意味しますが、そのリソースの変更がメトリクスに関連するものかどうかを事前に知る術がありません。

さらに、今日では、1つの「プロセス」から複数のリソースに関するデータを報告しようとすると、複数のSDKをインスタンス化し、それぞれのSDKで異なるリソースを定義するという方法しか取れません。
この絶対的な分離は、「ビルトイン」の計装という概念にとって大きな問題となり得ます。
たとえば、gRPCのようなライブラリにはOpenTelemetryのサポートがすぐに使える状態で組み込まれていますが、複数のSDKが存在する状況で、この計装が正しく使われることをどう保証すればよいのかが明確ではありません。

## 説明 {#explanation}

私たちはOpenTelemetryに次の新しい基本的な概念を提案します。

- `Resource`は*不変のまま*である。
  - [OTEP 264](0264-resource-and-entities.md)を土台として、識別属性は今後Resourceの中で明確に定義されるようになり、Resourceの属性の実世界での曖昧な使われ方（[例えばOpAMPにおける識別属性](https://github.com/open-telemetry/opamp-spec/blob/main/specification.md#agentdescriptionidentifying_attributes)）に対処します。
  - SDKには、`Resource`が完全な状態ではない明示的な初期化ステージが与えられ、非同期のリソース検出をめぐるOpenTelemetry JSの懸念に対処します。
- SDKは、SDKの起動時に提供される単一の`Resource`によって識別されます。
  - [OTEP 264](0264-resource-and-entities.md)で説明されているように、ResourceDetectionが拡張されます。
  - SDKの初期化に関する明示的なセクションが新設されます。
- SDK内のSignal Providerは、デフォルトのSDKリソースの「特殊化」を可能にします。
  既存のプロバイダーに新しい`Entity`を与えることで、新しい`{Signal}Provider`インスタンスを作成します。
  - これにより、そのプロバイダー専用の新しい`Resource`が構築されます。
  - 新しいプロバイダーは、ベースのプロバイダーで定義されたすべての設定（例えばエクスポートパイプライン）を再利用します。

## 内部の詳細 {#internal-details}

この提案は、計装向けのAPIと、SDKにおけるそのAPIに求められる振る舞いとに分かれています。

### APIの詳細 {#api-details}

これまで、すべての`{Signal}Provider` APIは単一の`Get a {Signal}`操作を定義していました。
これらは新しい`For Entity`操作によって拡張され、特定の`Entity`に対して報告するための新しい`{SignalProvider}` APIコンポーネントを構築します。

#### For Entity {#for-entity}

このAPIは以下のパラメータを受け付けなければなりません（MUST）。

* `entities`: 送出されるテレメトリーに関連付ける`Entity`の集合を指定します。

SDKの`Resource`にすでに提供されているエンティティと競合する`entities`が渡された場合、それはアイデンティティの*上書き*を表します。
SDKは、致命的なエラーを発生させることなく、この競合を解決しなければなりません（MUST）。

これらの操作に渡される`Entity`の集合には、`type`ごとに1つの`Entity`だけを含めなければなりません（MUST）。

#### エンティティ {#entity}

`Entity`は以下の値の集合です。

- `type`: エンティティのクラスを記述する文字列です。
- `id`: エンティティのインスタンスを識別する属性の集合です。
- (オプション) `description`: エンティティのインスタンスを記述する属性の集合です。
- (オプション) `schema_url`: このエンティティについて記録されるべきスキーマURLを指定します。

`Entity`は、その`type`と`id`の組み合わせによって一意に識別されます。

`schema_url`は、`Entity`を記述するために使われるスキーマのバージョンを定義します。
同じアイデンティティを持ちながら異なる`schema_url`を持つ2つのエンティティが存在する場合、それらは互いに競合しているとみなさなければなりません（MUST）。

### SDKの詳細 {#sdk-details}

`For Entity`操作がプロバイダーによって受け取られると、同じ型を持つ新しい子`Entity Bound Provider`が、以下の制約とともに作成され、返されなければなりません（MUST）。

- `Entity Bound Provider`は、新しく作成された`Resource`と関連付けられなければなりません（MUST）。
  この`Resource`は、渡された`Entity`の集合を、既存の`Resource`のマージアルゴリズムに従って元の`Provider`のリソースにマージした結果です。
  親によって作成されるテレメトリーは、変更されていない元のリソースと引き続き関連付けられなければなりません（MUST）。
- `Bound Provider`は、親とエクスポートパイプラインを共有しなければなりません（MUST）。
  エクスポートコンポーネント（`SpanProcessor`、`MetricReader`、`LogsProcessor`など）は、`Bound Provider`によって`Shutdown`されてはなりません（MUST not）。
  これは、`Shutdown`の呼び出しを無視するか、それを`Force Flush`に変換するプロキシコンポーネントでエクスポートコンポーネントをラップすることで実現してもよいです（MAY）。
- `Bound Provider`は、親とまったく同じ設定でなければなりません（MUST）。
  親`Provider`での設定変更は、そのすべての子`Entity Bound Provider`に反映されなければなりません（MUST）。
  これは、`Provider`間で設定オブジェクトを直接共有することで実現してもよいです（MAY）。
- `Bound Provider`は直接設定可能であってはなりません（MUST NOT）。
  すべての設定は親から取得されます。
- `Provider`に対して`ForceFlush`または`Shutdown`が呼び出された場合、そのすべての子`Entity Bound Provider`もフラッシュしなければなりません（MUST）。
- `Bound Provider`に対して`Shutdown`が呼び出された場合、それは`Force Flush`として扱わなければなりません（MUST）。
  それは自身のエクスポートパイプラインをシャットダウンしてはなりません（MUST NOT）。

## トレードオフと緩和策 {#trade-offs-and-mitigations}

ここでの主なトレードオフは、「破壊的変更」と、Entityを利用するコードと利用しないコードとの間で生成されるテレメトリーの微妙な違いに関するものです。
私たちは、OTLPの利用者（ベンダー、データベース、Collector）に対して、これらの新しいセマンティクスを理解しないと正しく解釈できないデータが現れる前に、Entityの新しいセマンティクスをサポートするための時間的な余地を与える必要があります。
そのため、主に次のことが言えます。

- OTLPで定義される`Entity`は、オプトインの構成要素です。
  `Resource`は、`Entity`とは独立したアイデンティティとして利用できるべきです。
- 利用者は今後、SDKが同じバッチの中で複数のリソースを報告することを想定しておくべきです。
  理論的には、OTLPが任意の時点でのデータの集約・バッチ処理を許可するよう設計されているため、これはすでにサポートされているはずです（SHOULD）。

## 先行技術と代替案 {#prior-art-and-alternatives}

OpenCensusはかつて、コンテキストタグを動的に指定し、メトリクスの測定値が報告されるあらゆる場所で使用できるようにしていました。
その上でユーザーは、「View」の定義を通じて、それらのうちどれが自分にとって有用かを選択する必要がありました。
OpenTelemetryは、すべてのメトリクスが暗黙のView定義を持つという、よりシンプルな解決策を目指してきました。
そして私たちは、メトリクスの報告時に自然に使われる属性を送信できるようにするために、metric adviceを活用します。

説明で述べたとおり、[OTEP 4316](https://github.com/open-telemetry/opentelemetry-specification/pull/4316)は、リソースを完全に可変にすることを提案していますが、これには独自のトレードオフが伴います。

今日、Semantic Conventionsはすでに`Entity`を定義しており、`Resource`の属性を一貫してグループ化し報告するためにそれを利用しています。
さらに、Semantic Conventionは「エンティティの関連付け」のみをモデル化しています。
これは、シグナル（メトリクス、イベント、スパンなど）をエンティティに紐付けることを要求するものです。
例えば、`system.cpu.time`メトリクスは`host`エンティティに関連付けられることが期待されています。
この関連付けは、それが`Resource`を通じてなされるのか、それとも他のメカニズムによるものなのかについて何も前提を置いていません。
そのため、`InstrumentationScope`に基づくエンティティをサポートするように拡張することができます。

## 未解決の問題 {#open-questions}

InstrumentationScopeにエンティティを追加することには、解決すべき多くの影響があります。

### 高カーディナリティのエンティティに対するSDKの安全策とは何か {#what-are-the-sdk-safeguards-against-high-cardinality-entities}

[Issue #3062](https://github.com/open-telemetry/opentelemetry-specification/issues/3062)で見られるように、複数のテナントを観測するシステムは、ごく短時間しか観測されないテナントが、長期間にわたってリソース（特にメモリ）を消費し続けないようにする必要があります。
新しい「Scope with Entity」の作成を許可するにあたっては、（直接的あるいは暗黙的な）何らかのレベルの制御が必要です。

### エンティティがすでにResource内に存在する場合はどうなるか {#what-happens-when-an-entity-already-exists-within-resource}

これを失敗と考えるべきか、それとも機能と考えるべきでしょうか。

現時点では、これを機能とみなしています。
競合が発生した場合、新しい`{SignalProvider}`に対して報告される結果の`Resource`には、*新しい*Entityが使用されます。

SDKには自身のために何らかの形の安定したアイデンティティが必要ですが、テレメトリーを報告する際には、他のシステムに代わってデータを記録している場合があります。

### Resourceの記述的属性は変更を許可されるか {#are-descriptive-attributes-allowed-to-change-for-resource}

リソースの不変性がどのように保たれるのか、あるいは不変とは何を意味するのかは明確ではありません。
最初のエクスポートで送出されるリソースは、プロセスのライフタイム全体を通して送出されるものと同じになるのでしょうか。
リソースに紐付けられたエンティティの記述的属性は、依然として変更が許可されるのでしょうか。
そのリソースに新しいエンティティを紐付けることについてはどうでしょうか。

現時点では、次のように考えます。

- Resourceに報告されるエンティティの集合はロックされます。
  すべての識別属性も同様にロックされます。
- 記述的属性の変更を許可したいかどうかについては、今後決定するか、時間をかけて発展させていくことができます。
  OTLPを取り巻くエコシステムがResourceに対するEntityの「アイデンティティ」属性を活用するようになるまでは、記述的属性の変更を許可するべきではありません。

### Collectorコンポーネントへの影響はどの程度と想定されるか {#what-is-the-expected-impact-on-collector-components}

[OTEP 4316](https://github.com/open-telemetry/opentelemetry-specification/pull/4316)で定義されているもの以外に、Collectorコンポーネントへの影響は*ない*はずです。

### `For Entity`をいつ使うべきか、開発者にどのようにガイドするか {#how-do-we-guide-developers-on-when-to-use-for-entity}

`For Entity`メソッドについて、明確なガイダンスを用意する予定です。

## プロトタイプ {#prototypes}

- Java: https://github.com/open-telemetry/opentelemetry-java/compare/main...jsuereth:opentelemetry-java:wip-entity-and-providers
- TypeScript: https://github.com/open-telemetry/opentelemetry-js/pull/5620

## 将来の可能性 {#future-possibilities}

この提案は、OpenTelemetry SDKに強力なマルチテナント機能をもたらします。
1つの可能性としては、動的な`Context`とシグナルとの間の相互作用を改善することが挙げられます。
例えば、`Context`と属性・エンティティとの間である程度の相互作用を許可することです。

例えば、レキシカルスコープの代わりに次のようにする方法です。

```js
const myMeterProvider = globalMeterProvider.forEntity(getCurrentSession())
doSomething(myMeterProvider)
```

実行時スコープを許可することもできるでしょう。

```js
const ctx = api.context.active();
api.context.with(ctx.setValue(CURRENT_ENTITY_KEY, getCurrentSession()))
doSomething()
```