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

このドキュメントで提示されているメトリックとラベルの規則は、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"

ラベル名をメトリック名に含めないでください。これは冗長性を招き、該当するラベルが集約された場合に混乱を招く可能性があります。

基本単位

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

このドキュメントはオープンソースです。問題の報告やプルリクエストの提出にご協力ください。