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

このドキュメントで提示されているメトリクスおよびラベルの命名規則は、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])`でワット単位の電力が得られます。
質量	グラム	キロプレフィックスの問題を避けるため、キログラムよりもグラムが好まれます。