指標與標籤命名

本文檔中介紹的指標和標籤慣例並非使用 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() 應該是有意義的（儘管不一定有用）。如果沒有意義，請將資料分割成多個指標。例如，在一個指標中包含各種佇列的容量是好的，而將佇列的容量與佇列中目前的元素數量混合則不好。

標籤

使用標籤來區分被測量的事物的特性

• api_http_requests_total - 區分請求類型：operation="create|update|delete"
• api_request_duration_seconds - 區分請求階段：stage="extract|transform|load"

請勿將標籤名稱放在指標名稱中，因為這會引入冗餘，並且如果聚合各自的標籤，則會造成混淆。

基本單位

Prometheus 沒有任何硬編碼的單位。為了獲得更好的相容性，應該使用基本單位。以下列出一些指標系列及其基本單位。該清單並非詳盡無遺。

本文件為開放原始碼。請透過提交問題或提取請求來協助改進。