導出格式 · prometheus

## 提供的數據傳輸格式 exposition formats --- Prometheus實現了兩種不同的數據傳輸格式，客戶端可以使用檢測的度量指標給Prometheus服務，第一種：是基于文本的簡單格式, 第二種：更有效和更強大的協議緩沖格式。Prometheus服務和客戶端通過HTTP通信獲取要使用的是哪種協議。一個服務比較傾向于接收第二種更有效和更強大的協議緩沖格式。但是如果客戶端不支持前者，數據傳輸格式會回退到第二種基于文本的簡單格式大多數用戶應該使用已經存在的客戶庫，且這些客戶庫已經實現了兩種數據傳輸格式。 ### Format v0.0.4 v0.0.4是當前度量指標的數據傳輸格式版本到這個版本，Prometheus有兩種備用的數據傳輸格式：基于協議緩沖的格式和文本格式。客戶端必須支持這兩種備用格式中的一種。另外，客戶端可選擇性地提供不被Prometheus服務理解的其他數據傳輸文本格式。他們僅僅是為了易于理解和方便調試。強烈建議客戶端庫至少一種可讀的格式。有一種情況: 在HTTP頭部的Content-Type內容，如果客戶庫不能理解, 則易于理解的數據傳輸協議應該是候選項，v0.0.4的數據傳輸協議容易被理解，所以它是一個很好的數據傳輸格式候選者（并且也被Prometheus理解）。 #### 格式變體比較 | | 協議緩沖格式 | 文本格式 | |--|----------:|:--------| |開始時間| 2014.4月|2014.4月| |傳輸協議| HTTP | HTTP| | 編碼| - 32-bit varint-encoded record length-delimited | utf-9, \n行結尾| | | - Protocol Buffer messages of type | | | | - io.prometheus.client.MetricFamily | | | HTTP Content-Type| application/vnd.google.protobuf; proto=io.prometheus.client.MetricFamily; encoding=delimited | text/plain; version=0.0.4 (A missing version value will lead to a fall-back to the most recent text format version.)| | Optional HTTP Content-Encoding| gzip | gzip| | 優點 | - 跨平臺 | -可讀性好 | |- Size | - 易于組合，特別適用于簡單情況（無需嵌套）| | |- 編解碼代價小| - 逐行閱讀（處理類型提示和文本字符串外）| | |- 嚴格的范式 || | |- 支持鏈接和理論流（僅服務端行為需要更改）|| | 限制 | - 不具有可讀性| - 信息不全 | | | | - 類型和文檔格式不是語法的組成部分，意味著很少到不存在的度量契約驗證 | | | - 解析代價大| | 支持度量指標原子性 | - Counter | - Counter | | | - Gauge | - Gauge| | | - Histogram | - Histogram| | | - Summary | - Summary | | | - Untyped | - Untyped| | 兼容性| - 低于v.0.0.3無效 | 無 | | | - v0.0.4有效 | | ### Protocol buffer format details 協議緩沖區格式詳細信息在重復數據傳輸協議中，協議緩沖區的可重復排序是優選的，但不是必需的，即如果計算成本過高，則不排序同一個數據傳輸協議中`MetricFamily`的必須有一個唯一的名稱。且`MetricFamily`中的每個度量指標都必須有一組唯一的`LabelPair`字段。否則，這種嵌入行為是未定義的。 #### Text format details 文本格式詳解協議是面向行的。換行字符(\n)分隔行。最后一行必須以換行字符結束。空行被忽略。在一行內，令牌可以被任何數量的空格和/或制表符分開（如果它們不想和以前的token合并，則必須至少分開一個）。頭尾部的空白被忽略。具有"#"作為第一個費空格字符的行是注釋。它們被忽略，除非“#”之后的一個令牌是HELP或TYPE。這些行被視為如下：如果令牌是HELP，則至少需要一個令牌，這是度量指標名稱。所有剩余的令牌都被認為是該度量指標名稱的docstring。HELP行可以包含任何UTF-8字符序列（度量名稱后）。但反斜杠和換行字符必須分別轉移為\\和\n。相同的度量名稱只能有一個HELP行。如果令牌是TYPE，則預期只有兩個令牌。第一個是度量名稱，第二個是計數器，規格，直方圖，摘要或無類型，定義該名稱的度量標準的類型。相同的度量名稱只能有一個TYPE行。用于度量名稱的TYPE行必須出現在為該度量名稱報告的第一個樣本之前。如果度量名稱沒有TYPE行，則該類型將設置為無類型。剩余行用以下語法描述樣本，每行一個(EBNF)： ``` metric_name [ "{" label_name "=" `"` label_value `"` { "," label_name "=" `"` label_value `"` } [ "," ] "}" ] value [ timestamp ] ``` `metric_name`和`label_name`具有普通的Prometheus表達式語言限制。 `label_value`可以是UTF-8字符的任何序列，但反斜杠，雙引號和換行字符必須分別轉義為\\，\“和\ n，value為浮點數和時間戳一個int64（從時代以來的毫秒，即1970-01-01 00:00:00 UTC，不包括閏秒），由Go strconv軟件包（見函數ParseInt和ParseFloat）表示，特別是Nan，+ Inf和 -Inf是有效值。給定度量的所有行必須作為一個不間斷的組提供，可選的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或分位數標簽）出現。另見下面的例子。 ``` # 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 ``` #### 可選文本表示 Optional Text Representation 以下三種可選文本格式僅供使用，且不被Prometheus理解。因此，他們的定義可能會有些隨意。客戶端庫可能支持或可能不支持這些格式。工具不應該依賴這些格式。 1. HTML：此格式由HTTP Content-Type頭部請求，其值為text/html。在瀏覽器中查看的指標是一個“pretty”渲染。雖然生成客戶端在技術上完全免費組裝HTML，但客戶端庫之間的一致性應該是針對的。 2. 協議緩沖區文本格式：與協議緩沖區格式相同，但以文本形式。它由以文本格式（也稱為“調試字符串”）連接的協議消息組成，由另外的新行字符分隔（即在協議消息之間有空行）。請求格式為協議緩沖區格式，但HTTP Content-Type頭文件中的編碼設置為文本。 3. 協議緩沖區緊湊文本格式：與（2）相同，但使用緊湊文本格式而不是普通文本格式。緊湊文本格式將整個協議消息放在一行上。協議消息仍然以新的行字符分隔，但是不需要“空行”來進行分離。（每行只需一個協議消息）。格式被請求為協議緩沖區格式，但HTTP Content-Type頭中的編碼設置為compact-text。 ### 歷史版本有關歷史格式版本的詳細信息，請參閱舊版客戶端數據展示格式[文檔](https://docs.google.com/document/d/1ZjyKiKxZV83VI9ZKAXRGKaUKK2BIWCT7oiGBKDBpjEY/edit?usp=sharing)。