OTEP-0008: メトリクスオブザーバー仕様

ステータス: 0072-metric-observerによって完全に置き換えられました

オンデマンドで現在のゲージ計装器の値にコンテキストフリーでアクセスするための、メトリクスの Observer コールバックを提案します。

動機

現在の仕様では、メトリクスコールバックはSDKでメトリクスを生成するための代替手段として説明されており、アプリケーションは監視インフラストラクチャが望む頻度でのみメトリクスを生成できます。 この提案は、コールバックメトリクスについて、（おそらく唯一の重要なケースである）ゲージの Observer コールバックのみをサポートするように制限します。

解説

ゲージメトリクス計装器は通常、測定間隔が任意である、システムによって事前計算されたプロパティを反映するために使用されます。 累積（cumulative）や測定（measure）の種類のメトリクス計装器とは異なり、ゲージを選択する場合、現在の値の計算にかなりの計算コストがかかることがあります。 このような場合、コストを最小化するためにオンデマンドでそれらを計算することに関心を持つのは理解できます。

ゲージは、累積計装器や測定計装器とどう違うのでしょうか。 測定計装器は定義上、個々のイベントに情報を保持しているため、この場合コールバックはSDK以上に最適化することができません。 累積計装器は、読み書きされたバイト数など、容易に入手できる量を記録するためによく使われますが、これが常に真であるとは限らないことを踏まえて、NonDescending ゲージという特殊なケースを思い出してください。

NonDescending ゲージは、計算コストが高いために Observer コールバックでの使用が推奨される非負の累積メトリクスをサポートするというこのケースのために存在します。 たとえば、プロセスが消費した CPU秒 のような非減少（non-descending）の合計を計算するのにシステムコール以上のコストがかかる場合、その計装器には累積の代わりに非減少ゲージの Observer を宣言するべきです（SHOULD）。 これにより、望まれる監視頻度に応じて、メトリクスのコストを削減できます。

明示的に Set() されるゲージとオブザーバーコールバックとの重要な違いの1つは、Set() がコンテキストの内部で発生するのに対し、オブザーバーコールバックはそうではないという点です。

詳細

オブザーバーコールバックは、ゲージメトリクス計装器についてのみサポートされます。 オブザーバーゲージには、言語固有のコンストラクタ（例: metric.NewFloat64Observer()）を使用してください。 オブザーバーゲージは NonDescending オプションをサポートします。

コールバックは、ラベルセット からゲージ値へのマップを返します。 オブザーバーコールバックで宣言されたゲージは、Set することもできません。

コールバックはブロッキングを避けるべきです（SHOULD）。 コールバックが長時間ブロックする場合、実装は計算をキャンセルする必要があるかもしれません。

コールバックは、いかなるOpenTelemetry APIを介しても、アプリケーションコードと同期的に呼び出されてはなりません（MUST NOT）。 この保証を提供できない実装は、オブザーバーコールバックを実装しないことが望ましいです（SHOULD）。

コールバックは、エクスポーターに代わってSDK内で同期的に呼び出されてもかまいません（MAY）。

コールバックはOpenTelemetry APIの呼び出しを避けるべきですが（SHOULD）、これを強制することは不可能かもしれないと私たちは認識しています。

トレードオフと緩和策

コールバックは比較的危険なプログラミングパターンであり、アプリケーションとAPIまたはSDKとの間のデッドロックを避けるために注意が必要になる場合があります。 実装は、これらのインターフェースを完全に安全なものにするために、ランタイムのコールスタックのイントロスペクションを通じてデッドロックを防ぐことを検討してもよいでしょう（MAY）。