指標型別

Prometheus 客戶端庫提供了四種核心指標型別。除了原生直方圖之外，這些型別目前僅在插樁客戶端庫的 API 和展示協議中存在差異。Prometheus 伺服器尚未利用這些型別資訊，而是將除原生直方圖以外的所有型別扁平化為無型別的浮點值時間序列。然而，原生直方圖會作為特殊的複合直方圖樣本時間序列被攝取。未來，Prometheus 可能也會將其他指標型別作為複合型別來處理。此外，目前也正在開展持久化簡單浮點樣本型別資訊的工作。

Counter（計數器）

計數器 (Counter) 是一種累計指標，代表一個單調遞增的計數器 ，其值只能增加，或者在重新啟動時重置為零。例如，您可以使用計數器來表示已服務的請求數、已完成的任務數或錯誤發生次數。

請勿使用計數器來暴露可能會減少的值。例如，不要將計數器用於當前執行的程序數；而應使用儀表（Gauge）。

各類插樁庫關於計數器的使用文件

• Go 
• Java 
• Python 
• Ruby 
• .Net 
• Rust 

Gauge（儀表盤）

儀表 (Gauge) 是一種代表單個數值的指標，該數值可以任意上升或下降。

儀表通常用於測量值，例如溫度或當前記憶體使用情況，但也用於可以增減的“計數”，例如併發請求數。

各類插樁庫關於儀表的使用文件

• Go 
• Java 
• Python 
• Ruby 
• .Net 
• Rust 

Histogram（直方圖）

直方圖 (Histogram) 透過在可配置的桶（bucket）中對觀測值（通常是請求持續時間或響應大小等）進行計數來記錄它們。它還提供所有觀測值的總和。因此，直方圖本質上是一個分桶的計數器。但是，直方圖也可以表示分佈的當前狀態，在這種情況下，它被稱為 儀表直方圖 (gauge histogram)。與通常類似於計數器的直方圖相比，被檢測（插樁）的程式很少直接暴露儀表直方圖，因此在插樁庫中還不可用（至少目前如此），但在新版本的 protobuf 展示格式和 OpenMetrics  中有所體現。它們也經常透過 PromQL 表示式建立。例如，對計數器直方圖應用 rate 函式的結果是一個儀表直方圖，這與對計數器應用 rate 函式的結果是一個儀表是相同的道理。

直方圖存在兩種根本不同的版本：較新的 原生直方圖 (native histograms) 和較舊的 經典直方圖 (classic histograms)。

原生直方圖以複合樣本的形式暴露和攝取，其中每個樣本代表觀測值的計數和總和，以及一組動態的桶。

然而，經典直方圖由簡單浮點樣本的多個時間序列組成。基本指標名稱為 <basename> 的經典直方圖會產生以下時間序列：

• 觀測桶的累計計數器，暴露為 <basename>_bucket{le="<upper inclusive bound>"}
• 所有觀測值的 總和，暴露為 <basename>_sum
• 已觀測事件的 計數，暴露為 <basename>_count（與上方的 <basename>_bucket{le="+Inf"} 相同）

原生直方圖通常比經典直方圖高效得多，允許更高的解析度，在插樁期間不需要顯式配置桶邊界，並在透過網路傳輸時提供原子性（例如透過 Prometheus 遠端寫入協議，而經典直方圖可能會因為其組成時間序列獨立傳輸而面臨部分傳輸失敗的問題）。它們的桶模式確保了它們之間始終可以相互聚合，即使解析度可能發生了變化，而具有不同桶邊界的經典直方圖通常無法聚合。如果您正在使用的插樁庫支援原生直方圖（目前 Go 和 Java 支援），您可能應該相比經典直方圖，更傾向於選擇原生直方圖。

如果由於某種原因您只能使用經典直方圖，有一種方法可以至少獲得原生直方圖的部分好處：您可以將 Prometheus 配置為將經典直方圖攝取為一種特殊形式的原生直方圖，稱為具有自定義桶邊界的原生直方圖 (NHCB)。NHCB 的儲存方式與普通原生直方圖相同的複合樣本一致，提供了與普通原生直方圖類似的更高效率和原子網路傳輸。然而，NHCB 的桶佈局仍然與其經典對應物相同（在插樁期間靜態配置），具有相同的受限解析度和範圍，以及在更改桶邊界時同樣存在難以聚合的問題。

使用 histogram_quantile() 函式 從直方圖甚至直方圖聚合中計算分位數。它適用於經典直方圖和原生直方圖，僅語法略有不同。直方圖也適用於計算 Apdex 分數 。

您可以直接對經典直方圖的桶進行操作，因為它們表示為單獨的時間序列（如上所述，稱為 <basename>_bucket{le="<upper inclusive bound>"}）。但請記住，這些桶是 累積的 ，即每個桶都計算小於或等於作為標籤提供的上限的所有觀測值。對於原生直方圖，您可以使用 histogram_fraction() 函式（用於計算觀測比例）和 裁剪運算子（用於過濾所需的觀測區間）來檢視給定邊界內的觀測值。

有關直方圖使用的詳細資訊以及與 摘要 的區別，請參閱 直方圖與摘要。

注意從 Prometheus v3.0 開始，經典直方圖的 le 標籤值在攝取期間會被規範化，以符合 OpenMetrics 規範數字  的格式。

各類插樁庫關於直方圖的使用文件

• Go 
• Java 
• Python 
• Ruby 
• .Net 
• Rust 

總結

與 直方圖 (Histogram) 類似，摘要 (Summary) 也會對觀測值（通常是請求持續時間和響應大小等）進行取樣。雖然它也提供觀測值的總數和所有觀測值的總和，但它會在滑動時間視窗內計算可配置的分位數。

在一次抓取中，基本指標名稱為 <basename> 的摘要會暴露多個時間序列：

• 已觀測事件的流式 φ-分位數（0 ≤ φ ≤ 1），暴露為 <basename>{quantile="<φ>"}
• 所有觀測值的 總和，暴露為 <basename>_sum
• 已觀測事件的 計數，暴露為 <basename>_count

有關 φ-分位數、摘要使用的詳細解釋以及與 直方圖 的區別，請參閱 直方圖與摘要。

注意從 Prometheus v3.0 開始，quantile 標籤值在攝取期間會被規範化，以符合 OpenMetrics 規範數字  的格式。

各類插樁庫關於摘要的使用文件

• Go 
• Java 
• Python 
• Ruby 
• .Net