Prometheus logo

Prometheus

文件下載社群支援與培訓部落格

Ctrl + K

GitHub Logo

展示格式

自 Prometheus 2.0 版本起，預設情況下，所有向 Prometheus 暴露指標的程序都必須使用文字（text）格式。在 HTTP 協商之後，也可以使用另一種選擇——**protobuf** 格式。

有各種 客戶端庫已為您實現了這些格式。如果您首選的語言沒有客戶端庫，您可以 建立自己的客戶端庫。

本文件概述了官方支援的展示格式。

Prometheus 文字格式

在本節中，您可以找到關於該格式的一些 基本資訊，以及該格式更 詳細的分解。

基本資訊

方面描述
引入時間2014年4月
支援版本Prometheus 版本 >=0.4.0
傳輸方式HTTP
編碼UTF-8，\n 換行符
HTTP Content-Type帶有引數的 text/plain
  • version=0.0.4（如果缺少 version 值，將回退到最新的文字格式版本。）
可選的 HTTP Content-Encodinggzip
優點
  • 易於人類閱讀
  • 易於組裝，特別是在極簡情況下（無需巢狀）
  • 逐行可讀（元資料除外）
侷限性
  • 冗長
  • 型別和文件字串不是語法的有機組成部分，這意味著幾乎沒有指標契約驗證
  • 解析成本
支援的基礎指標型別
  • 計數器
  • Gauge
  • 直方圖
  • 摘要
  • Untyped
支援的高階特性

詳細資訊

Prometheus 的文字格式是面向行的。行與行之間由換行符（\n）分隔。最後一行必須以換行符結束。空行將被忽略。

行格式

在一行之內，標記（token）可以透過任意數量的空格和/或製表符分隔（且在標記可能與前一個標記合併的情況下，必須至少由一個分隔）。前導和尾隨空白字元會被忽略。

註釋、幫助文字和型別資訊

第一個非空白字元為 # 的行是註釋。除非 # 後面的第一個標記是 HELP 或 TYPE，否則它們會被忽略。這些行按以下方式處理：如果標記是 HELP，則其後至少應有另一個標記，即指標名稱。所有其餘標記均被視為該指標名稱的文件字串（docstring）。HELP 行可以包含任何 UTF-8 字元序列（在指標名稱之後），但反斜槓和換行符必須分別轉義為 \\ 和 \n。任何給定的指標名稱只能有一行 HELP。

如果標記是 TYPE，則其後應正好有另外兩個標記。第一個是指標名稱，第二個是 counter、gauge、histogram、summary 或 untyped 之一，用於定義該指標名稱的型別。對於給定的指標名稱，只能有一行 TYPE。指標名稱的 TYPE 行必須出現在該指標名稱上報第一個樣本之前。如果某個指標名稱沒有 TYPE 行，則其型別會被設為 untyped。不符合傳統 Prometheus 指標名稱字元集的指標名稱必須用雙引號括起來並進行轉義。

其餘行描述樣本（每行一個），使用以下語法（EBNF ）

metric_name_or_labels value [ timestamp ]

metric_name_or_labels = metric_name [ "{" labels "}" ] | "{" quoted_metric_name [ "," labels ] "}"

metric_name = identifier

quoted_metric_name = `"` escaped_string `"`

labels = [ label_pairs ]

label_pairs = label_pair { "," label_pair } [ "," ]

label_pair = label_name "=" `"` escaped_string `"`

label_name = identifier | `"` escaped_string `"`

在樣本語法中

  • identifier 遵循通常的 Prometheus 表示式語言限制。
  • escaped_string 由任何 UTF-8 字元組成，但反斜槓、雙引號和換行符必須進行轉義。
  • 當 metric_name 被雙引號括起來時，它出現在大括號內部，而不是外部。
  • label_name 可以選擇性地用雙引號括起來。
  • 不符合通常 Prometheus 表示式語言限制的指標和標籤名稱必須使用帶引號的語法。
  • label_value 可以是任何 UTF-8 字元序列，但反斜槓（\）、雙引號（"）和換行符（\n）必須分別轉義為 \\、\" 和 \n。
  • value 是一個浮點數，其表示方式符合 Go 語言 ParseFloat() 函式的要求。除了標準的數值外，NaN、+Inf 和 -Inf 也是有效的值，分別代表非數字、正無窮和負無窮。
  • timestamp（時間戳）是一個 int64 整數（自紀元以來的毫秒數，即 1970-01-01 00:00:00 UTC，不包括閏秒），其表示方式符合 Go 語言 ParseInt() 函式的要求。

分組與排序

給定指標的所有行必須作為單個組提供，且可選的 HELP 和 TYPE 行排在最前面（無特定順序）。除此之外，在重複展示中，最好進行可復現的排序，但這不是強制要求的，即：如果計算成本過高，則無需排序。

每行必須具有指標名稱和標籤的唯一組合。否則，攝入行為將是未定義的。

直方圖與彙總

histogram 和 summary 型別在文字格式中較難表示。以下規則適用：

  • 名為 x 的 summary 或 histogram 的樣本總和（sum）作為一個名為 x_sum 的獨立樣本給出。
  • 名為 x 的 summary 或 histogram 的樣本數量（count）作為一個名為 x_count 的獨立樣本給出。
  • 名為 x 的 summary 的每個分位數（quantile）作為一個獨立的樣本行給出，其名稱同樣為 x，並帶有一個標籤 {quantile="y"}。
  • 名為 x 的 histogram 的每個桶計數（bucket count）作為一個獨立的樣本行給出，名稱為 x_bucket，並帶有一個標籤 {le="y"}（其中 y 是桶的上限）。
  • histogram 必須有一個帶有 {le="+Inf"} 的桶。其值必須與 x_count 的值相同。
  • histogram 的桶和 summary 的分位數必須按照其標籤值（分別針對 le 或 quantile 標籤）的數值遞增順序出現。

示例

下面是一個完整的 Prometheus 指標展示示例，包括註釋、HELP 和 TYPE 表示式、直方圖、彙總、字元轉義示例等。

# HELP http_requests_total The total number of HTTP requests.
# TYPE http_requests_total counter
http_requests_total{method="post",code="200"} 1027 1395066363000
http_requests_total{method="post",code="400"}    3 1395066363000

# Escaping in label values:
msdos_file_access_time_seconds{path="C:\\DIR\\FILE.TXT",error="Cannot find file:\n\"FILE.TXT\""} 1.458255915e9

# UTF-8 metric and label names:
{"my.dotted.metric", "error.message"="Not Found"}

# Minimalistic line:
metric_without_timestamp_and_labels 12.47

# A weird metric from before the epoch:
something_weird{problem="division by zero"} +Inf -3982045

# A histogram, which has a pretty complex representation in the text format:
# HELP http_request_duration_seconds A histogram of the request duration.
# TYPE http_request_duration_seconds histogram
http_request_duration_seconds_bucket{le="0.05"} 24054
http_request_duration_seconds_bucket{le="0.1"} 33444
http_request_duration_seconds_bucket{le="0.2"} 100392
http_request_duration_seconds_bucket{le="0.5"} 129389
http_request_duration_seconds_bucket{le="1"} 133988
http_request_duration_seconds_bucket{le="+Inf"} 144320
http_request_duration_seconds_sum 53423
http_request_duration_seconds_count 144320

# Finally a summary, which has a complex representation, too:
# HELP rpc_duration_seconds A summary of the RPC duration in seconds.
# TYPE rpc_duration_seconds summary
rpc_duration_seconds{quantile="0.01"} 3102
rpc_duration_seconds{quantile="0.05"} 3272
rpc_duration_seconds{quantile="0.5"} 4773
rpc_duration_seconds{quantile="0.9"} 9001
rpc_duration_seconds{quantile="0.99"} 76656
rpc_duration_seconds_sum 1.7560473e+07
rpc_duration_seconds_count 2693

OpenMetrics 文字格式

OpenMetrics 是一項旨在標準化指標傳輸格式的努力，它基於 Prometheus 文字格式構建。自 Prometheus v2.23.0 起，它既可以用於抓取目標，也適用於指標聯邦。

目前有兩個版本的 OpenMetrics：

基本資訊

方面描述
引入時間2020年11月
支援版本Prometheus 版本 >=2.5.0
傳輸方式HTTP
編碼UTF-8，\n 換行符，以 # EOF 結尾。
HTTP Content-Type帶有引數的 application/openmetrics-text
  • version=1.0.0（如果缺少 version 值，將回退到最新的 OpenMetrics 文字版本。）
可選的 HTTP Content-Encodinggzip
優點
  • 易於人類閱讀
  • 易於組裝，特別是在極簡情況下（無需巢狀）
  • 逐行可讀（元資料除外）
侷限性
  • 冗長
  • 型別和文件字串不是語法的有機組成部分，這意味著幾乎沒有指標契約驗證
  • 解析成本
支援的基礎指標型別
  • 計數器
  • Gauge
  • 直方圖
  • GaugeHistogram
  • 摘要
  • Info
  • StateSet
  • Untyped
支援的高階特性
  • 單位元資料
  • Exemplar 取樣 (Counters, Histogram, GaugeHistogram)
  • 建立/啟動時間戳 (Counter, Histogram, GaugeHistogram, Summary)
  • UTF-8 指標名稱和標籤名稱

Exemplar 取樣（實驗性）

利用 OpenMetrics 格式可以展示和查詢 Exemplar 取樣 。Exemplar 提供了與某個指標集相關的特定時間點的快照，而該指標集在其他情況下是被彙總的 MetricFamily。此外，它們還可以附帶 Trace ID，當與鏈路追蹤系統配合使用時，可以提供與特定服務相關的更詳細的資訊。

要啟用此實驗性功能，您的版本必須至少為 v2.26.0，並在啟動引數中新增 --enable-feature=exemplar-storage。

Prometheus Protobuf 格式

除了文字表示外，Prometheus 官方還支援 protobuf 展示格式 。

負載必須編碼為一組 代表 MetricFamily 的 Protobuf 訊息。訊息必須以二進位制形式編碼，並以其可變長度無符號整數（varint）編碼的大小作為字首，以此作為分隔。這種基於可變長度整數大小分隔的編碼方式提供了流式處理能力，這對於大型抓取目標尤為重要。

所有字串欄位都必須採用 UTF-8 編碼。

預設情況下，Prometheus 3.0 更傾向於使用基於文字的協議，除非：

  • 透過 Prometheus 配置中的 scrape_protocols 設定進行了手動偏好設定。
  • 啟用某些特性時優先使用 Protobuf 格式，例如：
    • --enable-feature=created-timestamp-zero-ingestion 或 --enable-feature=st-storage
    • 相應的配置選項（scrape_native_histograms: true）

在 Prometheus 2.0 中，Protobuf 格式曾被標記為已廢棄，但此後這一決定被撤銷。從 Prometheus 3.0 開始，Prometheus Proto 被積極使用和維護，作為文字格式的補充。

基本資訊

方面描述
引入時間2014年4月
支援版本Prometheus 版本 >=0.4.0
傳輸方式HTTP
編碼採用 32 位可變長度整數編碼、記錄長度分隔的 io.prometheus.client.MetricFamily Protocol Buffer 訊息
HTTP Content-Type帶有引數的 application/vnd.google.protobuf
  • proto=io.prometheus.client.MetricFamily
  • encoding=delimited
可選的 HTTP Content-Encodinggzip
優點
  • 跨平臺
  • 大小
  • 向前/向後相容性
  • 嚴格的 Schema
  • 支援拼接與流式處理
  • 複合值
侷限性
  • 非人類可讀
支援的基礎指標型別
  • 計數器
  • Gauge
  • 直方圖
  • GaugeHistogram
  • 摘要
  • Untyped
支援的高階特性
  • 單位元資料
  • Exemplar 取樣 (Counters, Histogram, GaugeHistogram)
  • 建立/啟動時間戳 (Counter, Histogram, GaugeHistogram, Summary)
  • 原生（稀疏與指數）Histogram、GaugeHistogram
  • UTF-8 指標名稱和標籤名稱

何時使用 Proto 而非文字？

文字格式具有人類可讀性、壓縮效果好且對於程式設計使用足夠高效，但 Prometheus 社群也維護 Protobuf 格式，因為：

  • 它提高了新特性的質量和迭代速度，這些新特性可以以向後/向前相容的方式進行安全測試。
  • 鑑於其程式碼生成和靈活性特點，Protobuf 有助於展示器（exposer）/攝入器（ingestor）的實現。
  • 在（令人意外地罕見的）情況下，二進位制編碼可以更高效地進行編碼/解碼。

您可以在 PromCon 2025 演講  中瞭解更多資訊。

版本控制

目前 Prometheus 的 protobuf 是穩定的，但明確未進行版本控制。相反，它以 Prometheus 的版本控制作為參考。

Schema

標識為 io.prometheus.client 的 Protobuf schema 維護在 Prometheus 倉庫的 此處 。Schema 也可在 buf 登錄檔  中找到。

HTTP Content-Type 要求

從 Prometheus 3.0 開始，抓取目標對指標端點的響應必須返回有效的 Content-Type 請求頭。如果 Content-Type 缺失、無法解析或不是受支援的媒體型別，抓取將會失敗。有關詳細資訊，請參閱遷移指南中關於 抓取協議 的變更。

準確的 HTTP 內容型別請參見各個展示格式章節。

ScrapeProtocols 與 Content-Type

Prometheus 抓取配置透過 scrape_protocols 配置提供基於 content-type 的抓取協議協商。為了方便 Prometheus 使用者，抓取協議透過對映到具體 content-type 的唯一名稱來引用。有關詳細資訊，請參閱 協議頭。

然而，目標應當以絕對的、響應 content-type（例如 application/openmetrics-text;version=1.0.0）且僅限一種展示格式來暴露指標。

歷史版本

有關歷史格式版本的詳細資訊，請參閱遺留的 客戶端資料展示格式（Client Data Exposition Format）  文件。

原始 Protobuf 格式（包含最近針對原生直方圖的擴充套件）的當前版本維護在 prometheus/client_model 倉庫 。

本頁內容