OpenMetrics 2.0 客戶端庫遷移指南
本指南涵蓋了 OpenMetrics (OM) 1.0 到 OpenMetrics 2.0 影響客戶端庫（即暴露者）實現的變化。章節的組織方式允許您逐步實現更改，從版本協商開始，到指標型別、語法和元資料。本指南可能包含錯誤，在任何情況下，如果本文件與規範文件不一致，規範文件是權威的真實來源。
注意OpenMetrics 2.0 目前處於實驗階段（釋出候選版本），因此一些細節可能會有所變化。請在OpenMetrics 2.0 工作組問題 中追蹤進展。
本指南涵蓋了與客戶端庫/暴露者作者最相關的更改。有關完整的規範，包括 ABNF 語法、符合性要求和攝取器規則，請參閱完整的OpenMetrics 2.0 規範。如果您發現錯誤或有疑問，請在OpenMetrics 儲存庫 中提交問題。
如何使用本指南
以下每個部分都指導實現者完成這些更改。我們使用破壞性或非破壞性標籤。如果 OM 1.0 中有效的行在 OM 2.0 中變為無效，則該更改為破壞性。非破壞性更改新增新語法或放寬限制，而不會使任何現有有效行失效。
如果需要更多細節，還提供了規範的相關部分參考。
快速參考
OpenMetrics 2.0 包含許多更改。其中一些更改是放寬了以前嚴格的要求，例如指標名稱的構造方式或字元限制。其中一些更改是為了允許 OpenTelemetry 指標資料以 OpenMetrics 編碼而不違反規範。其他更改則提高了抓取器（例如 Prometheus）在各種情況下的效率和可靠性。這些更改引入了新的語法，主要側重於允許將指標資料編碼為單行，而不是需要多行來描述一個內聚的資訊。最後，一些更改添加了新功能和資料型別，如原生直方圖。
| 更改 | 1.0 | 2.0 | 是否破壞性？ |
|---|---|---|---|
| 協商 | |||
| Content-Type 版本頭 | version=1.0.0 | version=2.0.0 | 否 |
| 協商預設值 | 最舊版本 | 相同（預設為 1.0） | 否 |
| 命名 | |||
| MetricFamily 必須匹配 Metric Name | 隱式字尾去除 | 需要精確匹配 | 是 |
| Counter _total 字尾 | _total 必須 | _total 應該 | 否 |
| 保留後綴 | 未指定 | _count/_sum/_bucket 等 不應 | 否 |
| 元資料 | |||
| UTF-8 名稱 | |||
| 指標和標籤名稱引用 | 僅限 [a-zA-Z0-9_:] | 允許 UTF-8；需要時引用 | 否 |
| 起始時間戳 | |||
| st@ 替換 _created | 單獨的 _created 樣本 | 樣本行上的行內 st@ | 是 |
| 複合值 (CompositeValues) | |||
| 摘要 / 直方圖 / GaugeHistogram | 展開的 _bucket/_count/_sum 行 | 單個 {key:value} 複合值 | 是 |
| 總和和計數必填 | _count/_sum 可選 | 複合值中計數和總和必填 | 是 |
| 原生直方圖 | |||
| 僅限原生和組合直方圖 | 不適用 | 透過 schema/spans/buckets/etc 實現指數分桶 | 否 |
| Exemplar | |||
| W3C 跟蹤上下文鍵 | 不適用 | 推薦 trace_id 和 span_id | 否 |
| 強制時間戳 / 多個 Exemplar | 可選時間戳；最多 1 個 | 強制時間戳；允許多個 | 混合 |
| 大小限制 / W3C 鍵 / 直方圖放置 | 128 字元限制；分桶級別 | 軟限制；W3C 鍵；樣本級別 | 混合 |
| 未知型別 | |||
| 允許複合值 | 僅數字 | 數字或複合值 | 否 |
版本協商和 Content-Type
非破壞性：OM 1.0 的 Content-Type 仍然有效。
在 OM 1.0 中，暴露者使用以下 Content-Type 頭來標識其格式
OM 1.0
application/openmetrics-text; version=1.0.0; charset=utf-8
OM 2.0
application/openmetrics-text; version=2.0.0; charset=utf-8
協商預設值
當未請求特定版本時，暴露者必須預設為標準的最舊版本 (1.0.0)。使用標準的 HTTP Content-Type 協商。如果抓取器未請求版本 2.0.0，則響應 1.0.0。
這意味著您的暴露者應預設繼續提供 1.0 格式，並且僅在消費者請求時才切換到 2.0。
Protobuf 格式已移除
OM 2.0 不再指定官方的 Protobuf 格式。您可以繼續支援 1.0 版本的 Protobuf 格式，但 2.0 版本不包含新的或更新的 Protobuf 格式。
Prometheus Protobuf 線纜格式仍然重要並得到維護，請參閱暴露格式文件。
參見：OM 2.0 規範中的協議協商。
命名更改
OM 2.0 收緊了 MetricFamily 名稱與 Metric Name 之間的關係，並更改了計數器和資訊指標的字尾規則。在 OM 1.0 中，解析器隱式地去除了已知字尾，以將樣本名稱映射回其 MetricFamily。在 OM 2.0 中，這種隱式去除已不復存在：MetricFamily 名稱必須與每個 Metric 的 Name 精確匹配。
通常，強制的單位和 _total 字尾現在也只是推薦，而不是必需的。
規範術語更改
非破壞性：不影響暴露格式，僅影響規範中使用的術語。瞭解此更改有助於更輕鬆地使用 OM 2.0 規範。
OM 2.0 重構了資料模型層次結構。在 OM 2.0 中，MetricPoint 被移除，Sample 成為了一等資料模型物件
OM 1.0: MetricSet → MetricFamily → Metric → MetricPoint → Sample (文字格式) OM 2.0: MetricSet → MetricFamily → Metric → Sample (帶數字或複合值)
| 範圍 | OM 1.0 術語 | OM 2.0 術語 | 更改了什麼 |
|---|---|---|---|
| 所有型別 | MetricSet | MetricSet | 未更改。 |
| 所有型別 | MetricFamily | MetricFamily | 名稱現在必須與每個 Metric 的名稱匹配（沒有隱式字尾去除）。 |
| 所有型別 | Metric | Metric | 未更改。 |
| 所有型別 | MetricPoint | Sample | Sample 替換 MetricPoint。複雜型別（StateSet 除外）使用 CompositeValue 而不是多個 MetricPoint。 |
| StateSet | Metric | MetricGroup | 共享一個標籤集的所有狀態現在稱為 MetricGroup。 |
| StateSet | MetricPoint | Metric | 該集合中的單個狀態現在稱為 Metric。 |
MetricFamily 名稱必須匹配 Metric Name
破壞性：在 TYPE、HELP 和 UNIT 註釋中使用的 MetricFamily 名稱必須與 Metric 行上使用的名稱匹配。
在 OM 1.0 中，計數器的 TYPE 行使用基本名稱（例如 http_requests），而其樣本帶有 _total 字尾（例如 http_requests_total）。解析器知道在將樣本匹配回其 MetricFamily 時去除 _total，因此 MetricFamily 名稱和樣本 Metric Name 可以不同。
在 OM 2.0 中，MetricFamily 名稱必須與每個 Metric 的 Name 精確匹配。沒有隱式字尾去除。對於計數器，這意味著如果樣本使用 _total，則 TYPE 行必須包含它。
OM 1.0
# TYPE http_requests counter
# HELP http_requests Total HTTP requests.
http_requests_total 1027
OM 2.0
# TYPE http_requests_total counter
# HELP http_requests_total Total HTTP requests.
http_requests_total 1027
請注意，TYPE 和 HELP 行現在使用 http_requests_total 以精確匹配樣本名稱。這是您需要進行的最常見的更改：更新 TYPE 和 HELP 元資料名稱以包含以前僅在樣本上的字尾。
參見：OM 2.0 規範中的MetricFamily。
計數器字尾規則
計數器 _total
非破壞性：帶有 _total 的計數器仍然有效。
在 OM 1.0 中，計數器 Metric 名稱必須以 _total 結尾。
在 OM 2.0 中，計數器 Metric 名稱應該以 _total 結尾。它不再是強制性的。
提示：將規則更改為“應該”主要是為了實現與 OpenTelemetry 的相容性，OpenTelemetry 不要求計數器指標名稱採用任何特定格式。
OM 1.0
# TYPE http_requests counter
http_requests_total 1027
有效的 OM 2.0
# TYPE http_requests counter
http_requests 1027
保留後綴
非破壞性：OM 1.0 根本不允許這些字尾。
MetricFamily 名稱不應以以下任何保留後綴結尾
_count_sum_bucket_gcount_gsum
這些字尾是保留的，因為將直方圖和摘要轉換為經典表示的舊版攝取器會將它們擴充套件為帶有這些字尾的樣本。如果您有一個名為 foo_bucket 的 gauge 和一個名為 foo 的直方圖，舊版攝取器會將直方圖擴充套件為 foo_bucket、foo_count 和 foo_sum 樣本，從而與您的 gauge 發生衝突。
這是一個“不應”（而非“絕不”）規則，因此帶有這些字尾的現有指標仍將解析。但是，重新命名它們可以避免當您的指標被將複合型別擴充套件為經典表示的系統使用時發生的衝突錯誤。
參見：OM 2.0 規範中的MetricFamily。
實際命名更改
這是一個完整的 HTTP 伺服器的 OM 2.0 暴露示例，展示了命名規則如何協同工作
# TYPE http_requests_total counter
# HELP http_requests_total Total HTTP requests received.
http_requests_total{method="GET",code="200"} 1027
http_requests_total{method="POST",code="201"} 53
# TYPE http_request_duration_seconds histogram
# HELP http_request_duration_seconds Duration of HTTP requests in seconds.
http_request_duration_seconds{method="GET"} {count:1027,sum:172.5,bucket:[0.1:800,0.5:950,+Inf:1027]}
# TYPE build_info info
# HELP build_info Build metadata.
build_info{version="1.4.2",branch="main",goversion="go1.22"} 1
# EOF
每個指標的含義
- http_requests_total (計數器)：TYPE 行使用
http_requests_total，精確匹配樣本名稱。保留_total字尾以提高可讀性和向後相容性。 - http_request_duration_seconds (直方圖)：MetricFamily 名稱避免了保留後綴。直方圖使用複合值語法，所有分桶資料都在一行上（稍後描述）。
- build_info (資訊)：TYPE 行使用
build_info，匹配樣本名稱。MetricFamily 名稱上存在_info字尾是必需的。
元資料更改
OM 2.0 放寬了多項元資料要求，並重命名了一些約定。本節涵蓋了所有影響 MetricFamily 描述方式的元資料級別更改。
UTF-8 名稱
非破壞性：OM 1.0 傳統名稱的語法仍然有效。
OM 2.0 允許指標和標籤名稱包含超出傳統 [a-zA-Z0-9_:] 集合的 UTF-8 字元。這主要用於 OpenTelemetry 橋接場景，其中指標使用點分隔命名約定，如 process.cpu.seconds。點分隔名稱與命名更改中描述的寬鬆 _total 字尾規則（請參閱計數器和資訊字尾規則）配合良好，因為去掉 _total 可以得到更簡潔的點分隔指標名稱。
請注意，並非所有 Prometheus 生態系統工具都支援 UTF-8 指標名稱。
指標名稱引用
不匹配 ^[a-zA-Z_:][a-zA-Z0-9_:]*$ 的指標名稱必須用雙引號括起來。任何指標名稱都可以用雙引號括起來，但只有當名稱包含傳統集合之外的字元時才需要引用。
在帶引號的字串中，使用 \\ 表示文字反斜槓，\" 表示文字雙引號，\n 表示換行符。
# TYPE "process.cpu.seconds" counter
# HELP "process.cpu.seconds" Total user and system CPU time spent in seconds.
{"process.cpu.seconds"} 4.20072246e+06
參見：OM 2.0 規範中的UTF-8 引用。
標籤名稱引用
不匹配 ^[a-zA-Z_][a-zA-Z0-9_]*$ 的標籤名稱必須用雙引號括起來。任何標籤名稱都可以用雙引號括起來，但只有當名稱包含傳統集合之外的字元時才需要引用。
{"process.cpu.seconds","node.name"="my_node"} 4.20072246e+06
參見：OM 2.0 規範中的UTF-8 引用。
替代大括號語法
當指標名稱需要引用時，引用的名稱將作為第一個元素移到大括號內。對於引用的指標名稱，這是必需的：指標名稱必須出現在大括號內，而不是大括號外。在 ABNF 語法中，這被稱為 name-and-labels-in-braces 生產。
以下完整示例展示了帶有引用指標名稱的 TYPE、UNIT 和 HELP 元資料，後跟使用大括號語法且帶有引用指標名稱和引用標籤名稱的樣本行
# TYPE "process.cpu.seconds" counter
# UNIT "process.cpu.seconds" seconds
# HELP "process.cpu.seconds" Total user and system CPU time spent in seconds.
{"process.cpu.seconds","node.name"="my_node"} 4.20072246e+06
參見：OM 2.0 規範中的UTF-8 引用。
起始時間戳
破壞性：_created 樣本不再用於提供起始時間。
OM 2.0 將單獨的 _created 樣本替換為樣本行本身上的行內起始時間戳 (st@)，從而減少了暴露大小並避免了 _created 樣本和值樣本之間的競爭條件。計數器、直方圖和摘要具有建立語義並支援起始時間戳；儀表盤則不支援。
因此，OM 2.0 樣本行具有以下欄位順序
metric_name value [timestamp] [st@start_timestamp] [# exemplar...]
計數器
OM 1.0
# TYPE http_requests counter
http_requests_total 1027
http_requests_created 1000000000
OM 2.0
# TYPE http_requests_total counter
http_requests_total 1027 [email protected]
OM 1.0 示例使用 http_requests 作為 TYPE 名稱（隱式字尾去除），而 OM 2.0 使用 http_requests_total（MetricFamily 必須與 Metric Name 匹配，根據命名更改）。http_requests_created 樣本變為行內 st@ 時間戳。
直方圖
OM 1.0
# TYPE http_request_duration_seconds histogram
http_request_duration_seconds_bucket{le="0.1"} 800
http_request_duration_seconds_bucket{le="0.5"} 950
http_request_duration_seconds_bucket{le="+Inf"} 1027
http_request_duration_seconds_sum 172.5
http_request_duration_seconds_count 1027
http_request_duration_seconds_created 1000000000
OM 2.0 直方圖使用複合值語法（詳細內容請參見複合值）。這裡我們關注 st@ 的出現位置
OM 2.0
# TYPE http_request_duration_seconds histogram
http_request_duration_seconds {count:1027,sum:172.5,bucket:[0.1:800,0.5:950,+Inf:1027]} [email protected]
_created 樣本完全消失。st@ 時間戳出現在單個複合值行上的值之後。
實際的起始時間戳
此組合示例顯示了計數器和直方圖以及標籤、時間戳、起始時間戳和 Exemplar，演示了完整的欄位順序
# TYPE http_requests_total counter
http_requests_total{method="GET",code="200"} 1027 1710000000.123 [email protected] # {trace_id="abc123",span_id="def456"} 1.0 1709999999.456
http_requests_total{method="POST",code="201"} 53 1710000000.123 [email protected]
# TYPE http_request_duration_seconds histogram
http_request_duration_seconds{method="GET"} {count:1027,sum:172.5,bucket:[0.1:800,0.5:950,+Inf:1027]} 1710000000.123 [email protected]
# EOF
另請參見：Exemplar
複合值
破壞性：不再允許傳統的、多行的複雜型別（StateSet 除外）。
在 OM 1.0 中，複雜指標型別（直方圖、摘要、gaugehistograms）以多個展開的樣本行表示——每個分桶一行，計數一行，總和一行。在 OM 2.0 中，這些型別變為一個單行樣本，其值為一個複合值 (CompositeValue)：一個結構化的 {key:value,...} 塊，包含所有欄位。
所有三種類型——histogram、summary 和 gaugehistogram——在 OM 2.0 中都必須使用複合值語法。
語法概述
複合值用花括號括起來，包含逗號分隔的 key:value 欄位，無空格。鍵是固定的文字名稱；值是數字、整數或括號括起來的列表，具體取決於欄位。完整的鍵集如下
| 鍵 | 值型別 | 由...使用 | 描述 |
|---|---|---|---|
count | 數字 | 直方圖, 摘要 | 觀測計數。 |
sum | 數字 | 直方圖, 摘要 | 觀測值的總和。 |
gcount | 數字 | GaugeHistogram | Gauge 觀測計數。 |
gsum | 數字 | GaugeHistogram | Gauge 觀測值的總和。 |
quantile | [q:v,...] | 摘要 | 分位數/值對，按分位數排序。 |
bucket | [le:v,...,+Inf:v] | 直方圖, GaugeHistogram (經典) | 經典分桶上限/計數對。+Inf 是必需的。 |
schema | 整數 | 直方圖, GaugeHistogram (原生) | 原生直方圖解析度模式。 |
zero_threshold | 實數 | 直方圖, GaugeHistogram (原生) | 零分桶的寬度。 |
zero_count | 數字 | 直方圖, GaugeHistogram (原生) | 零分桶中的觀測計數。 |
negative_spans | [off:len,...] | 直方圖, GaugeHistogram (原生) | 負分桶的 span 定義。 |
negative_buckets | [v,...] | 直方圖, GaugeHistogram (原生) | 負分桶的計數。 |
positive_spans | [off:len,...] | 直方圖, GaugeHistogram (原生) | 正分桶的 span 定義。 |
positive_buckets | [v,...] | 直方圖, GaugeHistogram (原生) | 正分桶的計數。 |
並非每個鍵都出現在每個複合值中。哪些鍵是必需的取決於指標型別
- 摘要：
count、sum、quantile - 經典直方圖：
count、sum、bucket - 經典 GaugeHistogram：
gcount、gsum、bucket - 原生直方圖：
count、sum、schema、zero_threshold、zero_count，以及可選的negative_spans/negative_buckets和/或positive_spans/positive_buckets - 原生 GaugeHistogram：
gcount、gsum、schema、zero_threshold、zero_count，以及可選的negative_spans/negative_buckets和/或positive_spans/positive_buckets - 組合（經典 + 原生）：
count/gcount、sum/gsum、原生欄位，然後是bucket
一個抽象示例，顯示所有鍵（組合的經典 + 原生直方圖）
{count:<n>,sum:<n>,schema:<i>,zero_threshold:<r>,zero_count:<n>,negative_spans:[<off>:<len>,...],negative_buckets:[<n>,...],positive_spans:[<off>:<len>,...],positive_buckets:[<n>,...],bucket:[<le>:<n>,...,+Inf:<n>]}
其中 <n> 是一個數字，<i> 是一個整數，<r> 是一個實數，<off> 是一個整數偏移量，<len> 是一個正整數長度，而 <le> 是一個實數值的分桶邊界。欄位必須按所示順序出現。大括號內不得有任何空格。
參見：OM 2.0 規範中的複合值。
總結
規則：在 OM 2.0 中，摘要樣本必須包含計數 (Count)、總和 (Sum) 和一組分位數 (quantiles)。在 OM 1.0 中，這些都是可選的。以前省略計數或總和的暴露者現在必須包含它們。
OM 1.0
# TYPE http_request_duration_seconds_summary summary
http_request_duration_seconds_summary{quantile="0.5"} 0.013
http_request_duration_seconds_summary{quantile="0.9"} 0.025
http_request_duration_seconds_summary{quantile="0.99"} 0.10
http_request_duration_seconds_summary_sum 172.5
http_request_duration_seconds_summary_count 1027
OM 2.0
# TYPE http_request_duration_seconds_summary summary
http_request_duration_seconds_summary {count:1027,sum:172.5,quantile:[0.5:0.013,0.9:0.025,0.99:0.10]}
所有五個樣本行合併為一個。分位數對映移至複合值塊內部。計數和總和現在是強制欄位。如果沒有觀測值，請使用 quantile:[]（空分位數列表）。
參見：OM 2.0 規範中的摘要。
Histogram（直方圖）
OM 1.0
# TYPE http_request_duration_seconds histogram
http_request_duration_seconds_bucket{le="0.1"} 800
http_request_duration_seconds_bucket{le="0.5"} 950
http_request_duration_seconds_bucket{le="+Inf"} 1027
http_request_duration_seconds_sum 172.5
http_request_duration_seconds_count 1027
OM 2.0
# TYPE http_request_duration_seconds histogram
http_request_duration_seconds {count:1027,sum:172.5,bucket:[0.1:800,0.5:950,+Inf:1027]}
每個 _bucket、_sum 和 _count 樣本行合併為一個複合值。分桶列表使用 threshold:count 對，包括 +Inf 分桶。欄位必須按此順序出現：count、sum、bucket。_sum 和 _count 字尾完全消失。
參見：OM 2.0 規範中的帶經典分桶的直方圖。
儀表盤直方圖
GaugeHistogram 測量當前分佈（非基於重置）。常見示例：佇列深度、飛行中請求大小。與直方圖不同，值具有 Gauge 語義——它們可以上升或下降而無需重置。OM 1.0 展開格式使用 _gcount/_gsum 字尾；OM 2.0 使用帶有 gcount 和 gsum 欄位名稱的複合值（保留 Gauge 語義字首）。
OM 1.0
# TYPE queue_depth_bytes gaugehistogram
queue_depth_bytes_bucket{le="1024"} 5
queue_depth_bytes_bucket{le="65536"} 18
queue_depth_bytes_bucket{le="+Inf"} 23
queue_depth_bytes_gcount 23
queue_depth_bytes_gsum 1048576
OM 2.0
# TYPE queue_depth_bytes gaugehistogram
queue_depth_bytes {gcount:23,gsum:1048576,bucket:[1024:5,65536:18,+Inf:23]}
複合值格式類似於經典直方圖，但使用 gcount 和 gsum 而不是 count 和 sum。TYPE 行也區分它們。欄位必須按此順序出現：gcount、gsum、bucket。GaugeHistogram 沒有起始時間戳（沒有建立語義）。
參見：OM 2.0 規範中的帶經典分桶的 GaugeHistogram。
實際的複合值
一個展示所有型別在一起的完整暴露示例
# TYPE http_requests_total counter
http_requests_total{method="GET",code="200"} 1027 1710000000 st@1000000000
# TYPE http_request_duration_seconds_summary summary
http_request_duration_seconds_summary{path="/api/v1"} {count:1027,sum:172.5,quantile:[0.5:0.013,0.9:0.025,0.99:0.10]} 1710000000 st@1000000000
# TYPE http_request_duration_seconds histogram
http_request_duration_seconds{path="/api/v1"} {count:1027,sum:172.5,bucket:[0.1:800,0.5:950,+Inf:1027]} 1710000000 st@1000000000
# TYPE queue_depth_bytes gaugehistogram
queue_depth_bytes{queue="work"} {gcount:23,gsum:1048576,bucket:[1024:5,65536:18,+Inf:23]} 1710000000
# EOF
注意：計數器行使用純數字值，而不是複合值。摘要和直方圖使用複合值塊。GaugeHistogram 沒有起始時間戳（沒有建立語義）。
總和和計數必填
破壞性：OM 2.0 不允許省略總和和計數。
在 OM 2.0 中，直方圖和 GaugeHistogram 的總和 (Sum) 和計數 (Count) 現在是必需的。在 OM 1.0 中，這些是可選的。
直方圖
OM 1.0
# TYPE http_request_duration_seconds histogram
http_request_duration_seconds_bucket{le="0.1"} 800
http_request_duration_seconds_bucket{le="0.5"} 950
http_request_duration_seconds_bucket{le="+Inf"} 1027
http_request_duration_seconds_created 1000000000
OM 2.0
# TYPE http_request_duration_seconds histogram
http_request_duration_seconds {count:1027,sum:172.5,bucket:[0.1:800,0.5:950,+Inf:1027]} st@1000000000
GaugeHistogram
OM 1.0
# TYPE queue_depth_bytes gaugehistogram
queue_depth_bytes_bucket{le="1024"} 5
queue_depth_bytes_bucket{le="65536"} 18
queue_depth_bytes_bucket{le="+Inf"} 23
OM 2.0
# TYPE queue_depth_bytes gaugehistogram
queue_depth_bytes {gcount:23,gsum:1048576,bucket:[1024:5,65536:18,+Inf:23]}
參見：OM 2.0 規範中的直方圖和GaugeHistogram。
原生直方圖
非破壞性：OM 1.0 中完全不支援原生直方圖。
原生直方圖是 OM 2.0 中的新功能。與在插樁時選擇固定分桶邊界不同，原生直方圖使用指數分桶模式，可在所有值範圍上提供自動解析度，無需任何分桶配置。schema 欄位控制分桶寬度粒度：值越高，分桶越窄（越精細）。
本節建立在複合值中介紹的複合值語法之上。原生直方圖欄位遵循上述相同的 {key:value,...} 格式。
純原生直方圖
純原生直方圖複合值按順序包含以下欄位
count-- 觀測總數（數字）。sum-- 所有觀測值的總和（數字）。schema-- 控制指數分桶寬度的整數（-4 到 8）。值越高意味著粒度越精細。zero_threshold-- 定義零分桶邊界 [-threshold, +threshold] 的非負浮點數。zero_count-- 零分桶中的觀測計數。positive_spans-- 對映分桶索引的offset:length對列表（見下文）。positive_buckets-- 觀測計數列表，每個分桶一個。
span 是 offset:length 對，描述了哪些指數分桶被填充。第一個 span 的偏移量是起始分桶索引（可以為負）。其長度是從該索引開始的連續填充分桶的數量。每個後續 span 的偏移量是跳過下一個組之前的空分桶的數量。所有 span 長度的總和等於分桶列表中的值總數。有關分桶邊界公式，請參閱規範中的原生分桶。
負 spans 和 buckets (negative_spans, negative_buckets) 對負觀測值使用相同的語法。
如果未填充任何分桶，則可以完全省略 span 和 bucket 欄位。
# TYPE http_request_duration_seconds histogram
http_request_duration_seconds {count:59,sum:120.0,schema:3,zero_threshold:1e-4,zero_count:2,positive_spans:[0:3,2:2],positive_buckets:[10,15,12,8,12]} 1710000000 st@1000000000
該示例有兩個 span：第一個從分桶索引 0 開始，包含 3 個連續分桶，然後跳過 2 個空分桶，再包含 2 個連續分桶。總分桶計數為 3 + 2 = 5，與 positive_buckets 中的五個值匹配。
參見：OM 2.0 規範中的帶原生分桶的直方圖。
經典和原生的組合
一些消費者尚不支援原生分桶。組合的複合值在一行中包含兩種表示形式，提供向後相容性。欄位順序是：count、sum，然後是所有原生欄位（schema 到 positive_buckets），最後是經典 bucket 欄位。這種排序允許偏好原生分桶的解析器在經典分桶列表之前停止讀取。
# TYPE http_request_duration_seconds histogram
http_request_duration_seconds {count:59,sum:120.0,schema:3,zero_threshold:1e-4,zero_count:2,positive_spans:[0:3,2:2],positive_buckets:[10,15,12,8,12],bucket:[0.01:5,0.1:25,1.0:47,10.0:57,+Inf:59]} st@1000000000
參見：OM 2.0 規範中的帶經典和原生分桶的直方圖。
帶原生分桶的 GaugeHistogram
帶有原生分桶的 GaugeHistogram 樣本遵循與直方圖相同的語法，只是使用 gcount 和 gsum 而不是 count 和 sum。TYPE 行也區分它們。
參見：OM 2.0 規範中的帶原生分桶的 GaugeHistogram。
實際的原生直方圖
一個實際的暴露示例，展示了純原生和組合的經典+原生直方圖
# TYPE http_request_duration_seconds histogram
http_request_duration_seconds{method="GET"} {count:59,sum:120.0,schema:3,zero_threshold:1e-4,zero_count:2,positive_spans:[0:3,2:2],positive_buckets:[10,15,12,8,12]} 1710000000 st@1000000000
http_request_duration_seconds{method="POST"} {count:34,sum:68.5,schema:3,zero_threshold:1e-4,zero_count:1,positive_spans:[0:2,3:1],positive_buckets:[8,12,13],bucket:[0.01:3,0.1:14,1.0:28,10.0:33,+Inf:34]} 1710000000 st@1000000000
# EOF
GET 行使用純原生欄位。POST 行包含原生和經典分桶欄位，以支援尚未支援原生分桶的消費者。下一節涵蓋可附加到這些行的 Exemplar 語法（請參閱Exemplar）。
Exemplars（範例）
OM 2.0 更改了多項 Exemplar 規則。強制時間戳、每個樣本允許多個 Exemplar 以及放寬大小限制都會影響暴露者如何將跟蹤上下文附加到指標。
強制時間戳
破壞性：Exemplar 時間戳不再是可選的。
在 OM 1.0 中，Exemplar 時間戳是可選的。在 OM 2.0 中，每個 Exemplar 都必須包含一個時間戳。僅此一項就對不期望 Exemplar 值後有時間戳的 OM 1.0 解析器造成了破壞性更改。
http_requests_total 1027 1710000000 # {trace_id="abc123",span_id="def456"} 1.0 1709999999
Exemplar（# 之後的所有內容）具有標籤、一個值 (1.0) 和一個強制時間戳 (1709999999)。
多個 Exemplar
非破壞性：仍然允許單個 Exemplar。
在 OM 1.0 中，每個樣本最多可以有一個 Exemplar。OM 2.0 允許在單個樣本上使用多個 Exemplar。每個 Exemplar 都以 # 開頭，後跟其自己的標籤集、值和時間戳。
http_requests_total 1027 1710000000 # {trace_id="abc123",span_id="def456"} 1.0 1709999999 # {trace_id="xyz789",span_id="uvw012"} 1.0 1709999800
W3C 跟蹤上下文鍵
OM 2.0 建議使用 trace_id 和 span_id 作為 Exemplar 標籤鍵，遵循 W3C 跟蹤上下文約定。上面的示例已經演示了這一點。使用一致的鍵名稱可以讓消費者將指標與分散式跟蹤關聯起來，而無需每個暴露者進行配置。
放寬大小限制
在 OM 1.0 中，Exemplar 標籤集有 128 個字元的硬性限制。OM 2.0 取消了這一硬性限制，並代之以軟性指導：暴露者不應發出過大的 Exemplar 標籤集。這將把施加抓取 Exemplar 限制的負擔轉移到抓取器，並將在使用 Exemplar 時提供更大的靈活性。
直方圖 Exemplar 放置
在 OM 1.0 中，直方圖 Exemplar 出現在單獨的 _bucket 行上。在 OM 2.0 中，使用複合值語法時，Exemplar 附加在複合值之後的單個樣本行上。沒有標籤的 Exemplar 必須使用空的 LabelSet {}。將多個 Exemplar 附加到樣本時，該樣本上所有 Exemplar 的標籤名稱必須一致。
參見：OM 2.0 規範中的Exemplar。
未知型別
非破壞性
在 OM 1.0 中，具有未知型別的指標樣本只能具有數字值。在 OM 2.0 中，具有未知型別的指標樣本也可以具有複合值。
由於通常不應使用未知型別（它存在是為了處理型別不確定的第三方指標），因此這是一個小的更改。它主要影響需要處理任意未知型別資料的攝取器和庫。
參見：OM 2.0 規範中的未知。