メトリクスに関するセマンティック規約

ステータス: Mixed

メトリクスに関しては、次のセマンティック規約が定義されています。

General Guidelines: メトリクスに関する一般的なガイドライン。
Database: SQLおよびNoSQLクライアントのメトリクス。
FaaS: Function as a Serviceのメトリクス。
GenAI: 生成AIのメトリクスについては、OpenTelemetry GenAIセマンティック規約リポジトリを参照してください。
HTTP: HTTPクライアントとサーバーのメトリクス。
Messaging: メッセージングシステム（キュー、パブリッシュ・サブスクライブなど）のメトリクス。
RPC: RPCクライアントとサーバーのメトリクス。
.NET: .NETランタイムコンポーネントが発行するネットワーク関連のメトリクス。
システムメトリクス
- System: 標準的なシステムメトリクス。
- Container
- Hardware: ハードウェア関連のメトリクス。
- K8s: K8sのメトリクス。
- Process: 標準的なプロセスメトリクス。
- Runtime Environment: ランタイム環境のメトリクス。
OTel SDK Telemetry: OpenTelemetry SDKコンポーネントが発行するメトリクス。

メトリクスに関するセマンティック規約とは別に、トレース、ログ、イベントについても、OpenTelemetryは、独自のリソースセマンティック規約を持つ包括的なリソースという概念を定義しています。

一般的なガイドライン

ステータス: Development

新しいメトリクス名や属性を定義する際は、既存の標準的なメトリクスや、フレームワーク・ライブラリのメトリクスの先行事例を考慮してください。

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

メトリクスの階層構造は名前空間を定義します。OpenTelemetryを補完するアーティファクトは、一部のメトリクスカテゴリーについてメトリクスの構造と階層を定義しており、これらは今後のメトリクス作成の際の判断材料になります。

共通の属性は、一貫して命名されるべきです（SHOULD）。これは発見しやすさを助け、メトリクス名に対する類似の属性の曖昧さを解消します。

Prometheusが推奨しているように、“経験則として、あるメトリクスのすべての属性に対する集計は意味を持つべきです”。

意味的な曖昧さは避けるべきです（SHOULD）。類似のメトリクスが、既存のすべてのメトリクスの中で実装に大きな違いがある場合は、接頭辞を付けたメトリクス名を使ってください。例えば、ガベージコレクションを行うランタイムはそれぞれ、わずかに異なる戦略や測定方法を持ちます。ランタイムで区別せずにGCのメトリクス名を一つの集合として使うと、エンドユーザーにとって異質な比較や混乱を生む可能性があります（例えば、gc.* よりも jvm.gc* を優先します）。多くのオペレーティングシステムのメトリクスの測定値も同様に曖昧です。

メトリクス名と属性は、一般的な命名ガイドラインに従うべきです（SHOULD）。

単位

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

OpenTelemetryとOpenMetrics公開形式を使うシステムの間で相互運用するコンポーネントを構築する場合は、OpenMetrics Guidelinesを使ってください。

Instrumentの単位

ステータス: Stable

単位は、Unified Code for Units of Measureに従うべきです（SHOULD）。

utilization（全体に対する割合を測定する）メトリクスのInstrumentは無次元であり、デフォルトの単位 1（unity）を使うべきです（SHOULD）。
数量を注記するために波括弧を使うすべての非単位は、それが表す数量の文法的な数と一致する必要があります。例えば、プロセスへの個々のリクエストの数を測定する場合、単位は {requests} ではなく {request} になります。
何かの整数カウントを測定するInstrumentは、先頭のデフォルト単位（1）なしで追加の意味を与えるために、波括弧を使った注記のみを使うべきです（SHOULD）。例えば {packet}、{error}、{fault} などを使います。
1 以外のInstrumentの単位や、注記を使う単位は、UCUMの大文字小文字を区別する（“c/s”）表記を使って指定すべきです（SHOULD）。例えば、正式名が「degree Celsius」である単位には「Cel」を使います。
Instrumentは、そうしない十分な技術的理由がない限り、接頭辞のない単位（すなわち MiBy ではなく By）を使うべきです（SHOULD）。
Instrumentが継続時間を測定する場合、秒（すなわち s）を使うべきです（SHOULD）。

Instrumentの型

ステータス: Stable

メトリクスのセマンティック規約の仕様は、Counter や UpDownCounter のような同期Instrument型の名前を使って書かれています。しかし、準拠する実装は、代わりに Asynchronous Counter や Asynchronous UpDownCounter のような非同期の等価物を使ってもかまいません（MAY）。実装が同期型を選ぶか非同期の等価物を選ぶかは、実装の詳細と見なされます。いずれの選択も本仕様に準拠します。

一貫したUpDownCounterの時系列

ステータス: Development

UpDownCounter メトリクスを記録する際、増加を記録するために使われる属性値は、それに対応する減少を記録する際にも使われるべきです（SHOULD）。そうしないと、その増加と減少は別々の時系列になってしまいます。

例えば、UpDownCounter で active_requests を追跡していて、リクエストの開始時にインクリメントし、リクエストの終了時にデクリメントしている場合、リクエスト開始時のインクリメント時にまだ利用できない属性は、リクエスト終了時のデクリメント時にも使うべきではありません。