匯出格式

可以使用簡單的文字式匯出格式將指標匯出到 Prometheus。有各種客戶端函式庫為您實作此格式。如果您的慣用語言沒有客戶端函式庫，您可以建立自己的。

文字格式

從 Prometheus 版本 2.0 開始，所有將指標匯出到 Prometheus 的程序都需要使用文字式格式。在本節中，您可以找到有關此格式的一些基本資訊，以及更詳細的格式分解。

基本資訊

方面 描述
創立 2014 年 4 月
支援於 Prometheus 版本 >=0.4.0
傳輸 HTTP
編碼 UTF-8，\n 行尾
HTTP Content-Type text/plain; version=0.0.4（遺失 version 值將會導致回溯到最新的文字格式版本。）
選用的 HTTP Content-Encoding gzip
優點
  • 人類可讀
  • 易於組裝，特別是對於極簡的情況（不需要巢狀結構）
  • 逐行可讀（類型提示和文件字串除外）
限制
  • 冗長
  • 類型和文件字串不是語法不可或缺的一部分，表示幾乎不存在指標合約驗證
  • 解析成本
支援的指標基本型
  • 計數器
  • 量表
  • 直方圖
  • 摘要
  • 未類型化

文字格式詳細資訊

Prometheus 的文字式格式是以行為導向的。行由換行符號 (\n) 分隔。最後一行必須以換行符號結尾。空白行會被忽略。

行格式

在同一行中，符號可以由任意數量的空格和/或 Tab 分隔（如果它們會與前一個符號合併，則必須至少分隔一個）。忽略開頭和結尾的空白字元。

註解、說明文字和類型資訊

以 # 作為第一個非空白字元的行是註解。除非 # 後的第一個符號是 HELP 或 TYPE，否則會忽略它們。這些行的處理方式如下：如果符號是 HELP，則至少需要一個符號，也就是指標名稱。所有剩餘的符號都會被視為該指標名稱的說明字串。HELP 行可以包含任何 UTF-8 字元序列（在指標名稱之後），但反斜線和換行符號必須分別逸出為 \\ 和 \n。對於任何給定的指標名稱，只能存在一個 HELP 行。

如果符號是 TYPE，則正好需要另外兩個符號。第一個是指標名稱，第二個是 counter、gauge、histogram、summary 或 untyped，定義該名稱指標的類型。對於給定的指標名稱，只能存在一個 TYPE 行。指標名稱的 TYPE 行必須出現在該指標名稱的第一個樣本報告之前。如果指標名稱沒有 TYPE 行，則類型會設定為 untyped。

剩餘的行使用以下語法（EBNF）描述樣本（每行一個）。

metric_name [
  "{" label_name "=" `"` label_value `"` { "," label_name "=" `"` label_value `"` } [ "," ] "}"
] value [ timestamp ]

在樣本語法中

  • metric_name 和 label_name 帶有常見的 Prometheus 表達式語言限制。
  • label_value 可以是任何 UTF-8 字元序列，但反斜線 (\)、雙引號 (") 和換行 (\n) 字元必須分別逸出為 \\、\" 和 \n。
  • value 是一個浮點數，以 Go 的 ParseFloat() 函式所要求的方式表示。除了標準數值之外，NaN、+Inf 和 -Inf 是有效的值，分別表示非數值、正無限大和負無限大。
  • timestamp 是一個 int64（自 epoch 以來的毫秒數，即 1970-01-01 00:00:00 UTC，不包括閏秒），以 Go 的 ParseInt() 函式所要求的方式表示。

分組與排序

給定指標的所有行必須作為一個單一組提供，其中選用的 HELP 和 TYPE 行排在最前面（不按特定順序）。除此之外，重複匯出中可重現的排序是偏好的，但不是必需的，也就是說，如果計算成本過高，則不要排序。

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

直方圖與摘要

histogram 和 summary 類型很難以文字格式表示。以下慣例適用

  • 名為 x 的摘要或直方圖的樣本總和會以名為 x_sum 的單獨樣本提供。
  • 名為 x 的摘要或直方圖的樣本計數會以名為 x_count 的單獨樣本提供。
  • 名為 x 的摘要的每個分位數都會以相同名稱 x 和標籤 {quantile="y"} 作為單獨的樣本行提供。
  • 名為 x 的直方圖的每個儲存區計數都會以名稱 x_bucket 和標籤 {le="y"} 作為單獨的樣本行提供（其中 y 是儲存區的上限）。
  • 直方圖必須具有 {le="+Inf"} 的儲存區。其值必須與 x_count 的值相同。
  • 直方圖的儲存區和摘要的分位數必須以其標籤值的遞增數值順序出現（分別針對 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

# 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 文字格式的指標連線格式的嘗試。它可以抓取目標，並且至少從 v2.23.0 開始也可用於聯盟指標。

範例 (實驗性)

利用 OpenMetrics 格式可以匯出和查詢範例。範例提供與度量集合相關的特定時間點快照，否則會針對 MetricFamily 進行摘要。此外，它們可能附加了追蹤 ID，當與追蹤系統一起使用時，可以提供有關特定服務的更多詳細資訊。

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

Protobuf 格式

較早版本的 Prometheus 除了目前的文字式格式外，還支援基於 Protocol Buffers（也稱為 Protobuf）的匯出格式。在 Prometheus 2.0 中，Protobuf 格式被標記為已棄用，並且 Prometheus 停止從上述匯出格式擷取樣本。

但是，Prometheus 新增了新的實驗性功能，其中 Protobuf 格式被認為是最可行的選項。讓 Prometheus 再次接受 Protocol Buffers。

以下列出一些實驗性功能，一旦啟用，將會設定 Prometheus 以偏好 Protobuf 匯出格式

功能標誌 引入它的版本
原生直方圖 2.40.0
已建立時間戳記零擷取 2.50.0

歷史版本

有關歷史格式版本的詳細資訊，請參閱舊版客戶端資料匯出格式文件。

原始 Protobuf 格式（具有原生直方圖的最新擴充功能）的目前版本維護在 prometheus/client_model 儲存庫中。

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