指標和標籤命名

本文件中介紹的指標和標籤規範並不是使用 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() 應當是有意義的（儘管不一定有用）。如果它沒有意義，請將資料拆分為多個指標。例如，將各種佇列的容量放在一個指標中是很好的，而將佇列的容量與佇列中當前的元素數量混在一起則不合適。

為什麼在指標名稱中包含單位和型別字尾？

一些指標命名規範（例如 OpenTelemetry）不建議甚至不允許在指標名稱中包含關於指標單位和型別的資訊。一個常見的論點是，這些資訊已經在其他地方定義了（例如模式、元資料、其他標籤等）。

出於以下實際原因，Prometheus 強烈建議在指標名稱中包含單位 and 型別，即使您將該資訊儲存在其他地方：

• 指標消費的可靠性和使用者體驗：當在現代 UI 中與此類指標進行互動以在 PromQL 中使用它時，可以顯示關於指標型別和單位的豐富資訊（自動補全、懸浮層、彈出視窗）。不幸的是，在功能強大的 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]) 即可得到以瓦特為單位的功率。
質量	克	克優於千克，以避免千 (kilo) 字首帶來的問題。