## 提供的數據傳輸格式 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)。