> Source: https://www.ymotongpoo.com/works/oteps/metrics/otep-0009/


# OTEP-0009: メトリクスハンドルAPI仕様

メトリクス計装器を効率的に繰り返し使用するために、メトリクスAPIの「ハンドル」型の挙動を規定します。

## 動機 {#motivation}

仕様では現在この概念を「TimeSeries」と呼んでおり、これは `GetOrCreateTimeseries` が返す型で、あらかじめ定義されたラベルの集合にメトリクスをバインドして繰り返し使用できるようにするものです。
本提案は、これらをそれぞれ「Handle」と `GetHandle` に改称し、ハンドルに関するAPI仕様にさらなる詳細を追加します。

## 解説 {#explanation}

`TimeSeries` は「Handle」と呼ばれます。旧名は実装を示唆するものであり、APIの概念を表すものではないためです。
私たちは、「Handle」の方が意図された用途をより的確に表していると考えています。
同様に、`GetOrCreateTimeSeries` を `GetHandle` に、`GetDefaultTimeSeries` を `GetDefaultHandle` に改称します。これらの名前も実装を示唆しており、意図された用途を表していませんでした。

アプリケーションは、効率化のためにメトリクスハンドルを再利用することが推奨されます。

ハンドルは、あらかじめ定義されたラベル値の集合を使ってメトリクス計装器（cumulative、gauge、measure）を繰り返し記録する際のコストを削減するのに役立ちます。

`GetHandle` は、[`LabelSet`](./0049-metric-label-set.md) を指定して新しいハンドルを取得します。

言語ごとに任意で採用できる機能として、既知の順序でラベルを渡すための _順序付き_ 形式のAPIを提供してもかまいません。
順序付きラベル値APIは、SDKにとって単純なルックアップを容易にする、（言語ごとに任意の）潜在的な最適化として提供されます。
この順序付き値形式では、`GetHandle` への引数に不整合がある場合に、APIが例外をスローしたりエラーを返したりすることが許可されていますが、強い型チェックを持たない言語ではこの機能を省略したいと考えるかもしれません。
ラベル値を任意の順序で受け入れる場合、SDKは既存のメトリクスハンドルを見つけるためにラベルを正規化せざるを得ないことがありますが、例外をスローしてはなりません。

`GetHandle` は任意のラベルの集合をサポートします。
ハンドルを構築するために使用される LabelSet が、メトリクス計装器の推奨される集約キーを網羅している必要はありません。

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

それぞれのメトリクスの種類は異なる操作（`Add()`、`Set()`、`Record()`）をサポートするため、論理的に異なる種類のハンドルが存在します。
それぞれのハンドル型の名前は、その計装器の種類を反映したものにするべきです。

これらの名前（`Handle`、`GetHandle` など）は、あくまで言語に依存しない推奨にすぎません。
言語ごとのAPIは、その言語のスタイルに配慮しながら、型名やメソッド名を自由に選んでかまいません。

### メトリクスの `Attachment` サポート {#metric-attachment-support}

OpenCensusには、サンプリングのためにイベントへ関連情報を追加できる、メトリクスのアタッチメントという概念があります。
集約に使用されないラベル値は、OpenTelemetryのスパンコンテキストを含め、サンプルの「アタッチメント」として使用でき、エクスポートされるメトリクスにサンプルのトレースコンテキストを関連付けることができます。

## 対応するIssue {#issues-addressed}

[2019年8月21日に招集されたワーキンググループでのハンドルと命名に関する合意事項](https://docs.google.com/document/d/1d0afxe3J6bQT-I6UbRXeIYNcTIyBQv4axfjKF4yvAPA/edit#)

[`record` はトレーシングへの依存を持つ代わりに汎用的な `Attachment` クラスを受け取るべきである](https://github.com/open-telemetry/opentelemetry-specification/issues/144)