OTEP-0009: メトリクスハンドルAPI仕様
メトリクス計装器を効率的に繰り返し使用するために、メトリクスAPIの「ハンドル」型の挙動を規定します。
動機
仕様では現在この概念を「TimeSeries」と呼んでおり、これは GetOrCreateTimeseries が返す型で、あらかじめ定義されたラベルの集合にメトリクスをバインドして繰り返し使用できるようにするものです。
本提案は、これらをそれぞれ「Handle」と GetHandle に改称し、ハンドルに関するAPI仕様にさらなる詳細を追加します。
解説
TimeSeries は「Handle」と呼ばれます。旧名は実装を示唆するものであり、APIの概念を表すものではないためです。
私たちは、「Handle」の方が意図された用途をより的確に表していると考えています。
同様に、GetOrCreateTimeSeries を GetHandle に、GetDefaultTimeSeries を GetDefaultHandle に改称します。これらの名前も実装を示唆しており、意図された用途を表していませんでした。
アプリケーションは、効率化のためにメトリクスハンドルを再利用することが推奨されます。
ハンドルは、あらかじめ定義されたラベル値の集合を使ってメトリクス計装器（cumulative、gauge、measure）を繰り返し記録する際のコストを削減するのに役立ちます。
GetHandle は、LabelSet を指定して新しいハンドルを取得します。
言語ごとに任意で採用できる機能として、既知の順序でラベルを渡すための 順序付き 形式のAPIを提供してもかまいません。
順序付きラベル値APIは、SDKにとって単純なルックアップを容易にする、（言語ごとに任意の）潜在的な最適化として提供されます。
この順序付き値形式では、GetHandle への引数に不整合がある場合に、APIが例外をスローしたりエラーを返したりすることが許可されていますが、強い型チェックを持たない言語ではこの機能を省略したいと考えるかもしれません。
ラベル値を任意の順序で受け入れる場合、SDKは既存のメトリクスハンドルを見つけるためにラベルを正規化せざるを得ないことがありますが、例外をスローしてはなりません。
GetHandle は任意のラベルの集合をサポートします。
ハンドルを構築するために使用される LabelSet が、メトリクス計装器の推奨される集約キーを網羅している必要はありません。
内部の詳細
それぞれのメトリクスの種類は異なる操作（Add()、Set()、Record()）をサポートするため、論理的に異なる種類のハンドルが存在します。
それぞれのハンドル型の名前は、その計装器の種類を反映したものにするべきです。
これらの名前（Handle、GetHandle など）は、あくまで言語に依存しない推奨にすぎません。
言語ごとのAPIは、その言語のスタイルに配慮しながら、型名やメソッド名を自由に選んでかまいません。
メトリクスの Attachment サポート
OpenCensusには、サンプリングのためにイベントへ関連情報を追加できる、メトリクスのアタッチメントという概念があります。 集約に使用されないラベル値は、OpenTelemetryのスパンコンテキストを含め、サンプルの「アタッチメント」として使用でき、エクスポートされるメトリクスにサンプルのトレースコンテキストを関連付けることができます。