OTEP-0108: メトリクスInstrumentの命名ガイドライン

目的

メトリクスのInstrumentにおける名前とラベルは、主に人間がメトリクスデータとやり取りする際の手段です。ユーザーはダッシュボードを構築したり分析を行ったりする際に、これらの名前に依存しています。名前と階層構造は、日常的な調査の中で理解可能かつ発見しやすいものである必要があり、これはインシデントの際に極めて重要になります。これらの目標と、将来のメトリクス命名標準における一貫性を確保するために、本書ではこれらの名前に関するメタ標準を概説します。

ガイドライン

メトリクスの名前とラベルは、単一のユニバースと単一の階層の中に存在します。メトリクスの名前とラベルは、既存のすべてのメトリクス名のユニバースの中で検討されなければなりません（MUST）。新しいメトリクスの名前とラベルを定義する際は、既存の標準的なメトリクスや、フレームワーク・ライブラリ由来のメトリクスの先行事例を考慮してください。

関連するメトリクスは、その用途に基づいた階層の中にまとめてネストされるべきです（SHOULD）。 CPUやネットワークのようなOSメトリクスや、GC内部のようなアプリケーションランタイムのメトリクスといった、一般的なメトリクスのカテゴリについてトップレベルの階層を定義してください。ライブラリやフレームワークも同様に、それぞれのメトリクスを階層にネストするべきです。これは発見のしやすさと、アドホックな比較の助けになります。これにより、ユーザーはあるメトリクスから類似のメトリクスを見つけ出すことができます。

メトリクスの階層構造は名前空間を定義します。これを支援するOpenTelemetryのアーティファクトが、一部のカテゴリのメトリクスについてメトリクスの構造と階層を定義しており、これらは将来メトリクスを作成する際の判断の助けとなります。

一般的なラベルは、一貫した名前で付けられるべきです（SHOULD）。これは発見のしやすさを助け、メトリクス名に類似したラベルの曖昧さを解消します。

Prometheusが推奨するように、“経験則として、あるメトリクスのすべてのディメンションにわたる集計は、意味のあるものでなければなりません（SHOULD）”。

意味的な曖昧さは避けるべきです（SHOULD）。既存のすべてのメトリクスの中で類似のメトリクスが実装面で大きく異なる場合には、接頭辞を付けたメトリクス名を使用してください。たとえば、ガベージコレクションを行うすべてのランタイムは、それぞれ微妙に異なる戦略と測定方法を持っています。ランタイムごとに区別せず、GCに対して単一のメトリクス名のセットを使用すると、エンドユーザーにとって異質な比較や混乱を生む可能性があります。（たとえば、runtime.gc.* よりも runtime.java.gc* を優先してください。）多くのOSメトリクスの測定方法は互いに似通っています。

慣例的なメトリクス、またはOpenTelemetryのメタデータに単位がすでに含まれているメトリクス（たとえばGoにおける metric.WithUnit ）については、メトリクス名に単位を含めるべきではありません（SHOULD NOT）。メトリクス名に追加の意味を与える場合には、単位を含めてもかまいません（MAY）。メトリクスは、何よりもまず理解可能かつ使用可能でなければなりません（MUST）。