メトリックとラベルの命名

このドキュメントに示されているメトリックとラベルの規則は、Prometheusを使用する上で必須ではありませんが、スタイルガイドとベストプラクティスのコレクションの両方として役立ちます。個々の組織は、命名規則などの一部のプラクティスを異なる方法でアプローチしたい場合があります。

メトリック名

メトリック名は…

• …有効な文字についてはデータモデルに準拠する必要があります。
• …メトリックが属するドメインに関連する（単一単語の）アプリケーションプレフィックスを持つべきです。このプレフィックスは、クライアントライブラリによってnamespaceと呼ばれることがあります。アプリケーションに固有のメトリックの場合、プレフィックスは通常アプリケーション名自体です。ただし、クライアントライブラリによってエクスポートされる標準化されたメトリックのように、より汎用的なメトリックもあります。例
  • prometheus_notifications_total (Prometheusサーバー固有)
  • process_cpu_seconds_total (多くのクライアントライブラリによってエクスポートされる)
  • http_request_duration_seconds (すべてのHTTPリクエスト用)
• …単一の単位を持つ必要があります（つまり、秒とミリ秒を混ぜたり、秒とバイトを混ぜたりしないでください）。
• …基本単位を使用すべきです（例：秒、バイト、メートル — ミリ秒、メガバイト、キロメートルではない）。基本単位のリストは以下を参照してください。
• …複数形の単位を記述するサフィックスを持つべきです。累積カウントは、該当する場合、単位に加えてtotalをサフィックスとして持つことに注意してください。また、これは狭義の単位（下の表の単位など）に適用されますが、一般的な数えられるものには適用されないことにも注意してください。たとえば、connectionsやnotificationsはこのルールにおける単位とはみなされず、メトリック名の最後に置く必要はありません。（次の段落の例も参照してください。）
  • http_request_duration_seconds
  • node_memory_usage_bytes
  • http_requests_total (単位なしの累積カウントの場合)
  • process_cpu_seconds_total (単位付きの累積カウントの場合)
  • foobar_build_info (実行中のバイナリに関するメタデータを提供する擬似メトリックの場合)
  • data_pipeline_last_record_processed_timestamp_seconds (データ処理パイプラインで処理された最新レコードの時刻を追跡するタイムスタンプの場合)
• …他のすべてのルールに従う限り、メトリック名のリストが辞書順にソートされたときに便利なグループ化になるように、名前のコンポーネントを並べてもよいです。以下の例は、関連するすべてのメトリックが一緒にソートされるように、共通の名前コンポーネントを最初に配置しています。
  • prometheus_tsdb_head_truncations_closed_total
  • prometheus_tsdb_head_truncations_established_total
  • prometheus_tsdb_head_truncations_failed_total
  • prometheus_tsdb_head_truncations_total
    以下の例も有効ですが、異なるトレードオフに従っています。これらは個々に読みやすいですが、prometheus_tsdb_head_seriesのような無関係なメトリックが間にソートされる可能性があります。
  • prometheus_tsdb_head_closed_truncations_total
  • prometheus_tsdb_head_established_truncations_total
  • prometheus_tsdb_head_failed_truncations_total
  • prometheus_tsdb_head_truncations_total
• …すべてのラベル次元で同じ論理的な測定対象を表すべきです。
  • リクエスト期間
  • データ転送バイト数
  • 瞬時リソース使用率（パーセンテージ）

経験則として、特定のメトリックのすべての次元にわたるsum()またはavg()は意味があるべきです（必ずしも有用である必要はありません）。意味がない場合は、データを複数のメトリックに分割します。たとえば、さまざまなキューの容量を1つのメトリックにまとめるのは良いことですが、キューの容量とキュー内の現在の要素数を混ぜるのは良くありません。

なぜメトリック名に単位とタイプのサフィックスを含めるのか？

一部のメトリック命名規則（例：OpenTelemetry）では、メトリックの単位とタイプに関する情報をメトリック名に含めることを推奨しないか、あるいは許可していません。一般的な議論は、これらの情報はすでにどこか別の場所（例：スキーマ、メタデータ、他のラベルなど）で定義されているというものです。

Prometheusは、その情報を別の場所に保存している場合でも、メトリック名に単位とタイプを含めることを強く推奨します。これには以下の実用的な理由があります。

• メトリック消費の信頼性とUX：PromQLでそのようなメトリックを使用するために最新のUIとやり取りする場合、メトリックのタイプと単位に関する豊富な情報（オートコンプリート、オーバーレイ、ポップアップ）を表示することが可能です。残念ながら、強力なUIでの対話的なアドホッククエリだけがユーザーがメトリックとやり取りする方法ではありません。メトリック消費のエコシステムは広大です。消費の大部分は、アラート、記録、オートスケーリング、ダッシュボード、分析、処理など、さまざまなオブザーバビリティツールのためのプレーンなYAML設定の形式で行われます。特に監視/SREインシデントプラクティス中に、プレーンなYAMLでPromQL式を見て、作業している基礎となるメトリックのタイプと単位を理解することは非常に重要です。
• メトリックの衝突：採用の増加と時間の経過によるメトリックの変更に伴い、メトリック名に単位とタイプ情報がないために特定のシリーズが衝突するケースがあります（例：秒とミリ秒のprocess_cpu）。

ラベル

測定対象の特性を区別するためにラベルを使用します。

• api_http_requests_total - リクエストタイプを区別する: operation="create|update|delete"
• api_request_duration_seconds - リクエストステージを区別する: stage="extract|transform|load"

ラベル名をメトリック名に含めないでください。これは冗長性を生み、対応するラベルが集約された場合に混乱を引き起こします。

注意キーと値のラベルペアの固有の組み合わせはすべて新しい時系列を表し、保存されるデータ量を劇的に増加させる可能性があることに注意してください。ユーザーID、メールアドレス、その他の無限のセットの値など、カーディナリティの高い（多くの異なるラベル値を持つ）次元を保存するためにラベルを使用しないでください。

基本単位

Prometheusには、ハードコードされた単位はありません。互換性を高めるために、基本単位を使用する必要があります。以下に、いくつかのメトリックファミリーとその基本単位をリストアップします。このリストは網羅的なものではありません。

ファミリー	基本単位	備考
時間	秒
温度	摂氏	実用的な理由から、ケルビンよりも摂氏が推奨されます。色温度や温度を絶対値として扱う必要がある特殊なケースでは、ケルビンも基本単位として許容されます。
長さ	メートル
バイト	バイト
ビット	バイト	異なるメトリックを組み合わせる際の混乱を避けるため、ビットの方が一般的と思われる場合でも、常にバイトを使用してください。
パーセント	比率	値は0～1です（0～100ではありません）。ratioは、disk_usage_ratioのような名前のサフィックスとしてのみ使用されます。通常のメトリック名はA_per_Bのパターンに従います。
電圧	ボルト
電流	アンペア
エネルギー	ジュール
電力		ジュールのカウンタをエクスポートすることを推奨します。そうすれば、rate(joules[5m])でワット単位の電力が得られます。
質量	グラム	キロ接頭辞に関する問題を避けるため、キログラムよりもグラムが推奨されます。