OTEP-0070: メトリクスインストゥルメントのHandleを「バインド済みインストゥルメント」に改名

OpenTelemetryメトリクスAPI仕様は、「メトリクスハンドル」として知られる概念に言及しています。これは LabelSet にバインドされたメトリクスインストゥルメントのことです。本OTEPは、より一般的すぎる用語である「ハンドル」を避けるために、この用語を「バインド済みインストゥルメント」に変更することを提案します。

バインド済みインストゥルメントを作成するための対応するメソッドは、「GetHandle」ではなく「Bind」に改名されます。

動機

「Handle」という用語は、メトリクスAPIにおける目的に対して一般的すぎると広く見なされています。この概念のために広く使われている名詞を再利用するのではなく、私たちはメトリクスの「instrument」という名詞を再利用し、それが LabelSet にバインドされたことを伝えるために「bound」という形容詞を適用します。

解説

「Handle」は当初から紛らわしいものでした。とはいえ、それ以前にも紛らわしい可能性のある用語（たとえば「TimeSeries」や「Entry」）がありました。「Bound instrument」という用語は、当初こちらで提案され、広く受け入れられました。

内部の詳細

これは単純な改名です。仕様における「handle」の使用箇所はすべて「bound instrument」に置き換えられます。 GetHandle メソッドの使用箇所はすべて Bind になります。

「bound instrument」というフレーズは、ユーザー向けAPIに直接現れないかもしれませんし、現れる必要もない点に注意してください。一方、GetHandle はメトリクスインストゥルメントで規定されたメソッドです。

新しく命名された Bind() メソッドは、バインド済みインストゥルメント型を返します。返される型の名前は、単純にそのインストゥルメントの名前に接頭辞 Bound を付けたものにしてもかまいません。たとえば、Int64Counter インストゥルメントの Bind() メソッドは、BoundInt64Counter 型を返すべきです。

通常どおり、これらの名前の綴りや大文字・小文字の使い分けは単なる推奨事項にすぎず、各言語の委員会が、自分たちの言語や既存のAPIスタイルに適した名前を選ぶべきです。

トレードオフと緩和策

これは非公式な議論に基づき、改善であると広く見なされています。

先行技術と代替技術

OpenCensusライブラリは、この概念を「Entries」と名付け、GetEntry メソッドを持っていました。これらは、いわばマップの一種のエントリーだったからです。

OpenTelemetryにおけるもっとも初期の登場では、この概念は「TimeSeries」と改名され、状況の改善が期待されていました。しかし、「TimeSeries」は、集約後のバインド済みインストゥルメントの出力を指すことの方が一般的です。「Handle」は、2019年8月のメトリクスに関するワーキンググループで決定されました。

Prometheusライブラリは、未バインドのインストゥルメントを「Vectors」と呼び、ラベルをベクトルにバインドしてバインド済みインストゥルメントを得るための、さまざまな「With」メソッドをサポートしています。