OpenMetrics 2.0 客户端库迁移指南
本指南涵盖了 OpenMetrics (OM) 1.0 到 OpenMetrics 2.0 中影响客户端库（即导出器）实现的变化。各章节经过组织，方便您逐步实现这些更改，从版本协商开始，一直到指标类型、语法和元数据。本指南可能包含错误，如果本文档与规范文档不一致，规范文档是权威的事实来源。
注意OpenMetrics 2.0 目前处于实验阶段（候选发布版本），因此某些细节可能会发生变化。您可以在 OpenMetrics 2.0 工作组议题 中跟踪进度。
本指南涵盖了与客户端库/导出器作者最相关的变更。有关完整的规范（包括 ABNF 语法、一致性要求和提取器规则），请参阅完整的 OpenMetrics 2.0 规范。如果您发现错误或有疑问，请在 OpenMetrics 仓库 中提交议题。
如何使用本指南
下面的每一部分都会指导实现者完成变更。我们使用中断性 (Breaking) 或非中断性 (Non-breaking) 标签。如果某行代码在 OM 1.0 中有效，但在 OM 2.0 中无效，则该更改为中断性的。非中断性更改会增加新语法或放宽限制，而不会使任何现有的有效代码行失效。
如果需要更多详细信息，还会引用规范的相关部分。
快速参考
OpenMetrics 2.0 包含许多变更。其中一些变更放宽了以前严格的要求，例如指标名称的构造方式或字符限制。其中一些变更旨在允许在不违反规范的情况下将 OpenTelemetry 指标数据编码为 OpenMetrics 格式。其他变更提高了提取器（例如 Prometheus）在各种情况下的效率和可靠性。这些变更引入了新的语法，主要集中在允许将指标数据编码为单行，而不是要求使用多行来描述一个连贯的信息片段。最后，一些变更增加了新特性和数据类型，例如原生直方图 (Native Histograms)。
| 变更 | 1.0 | 2.0 | 是否中断？ |
|---|---|---|---|
| 协商 | |||
| Content-Type 版本标头 | version=1.0.0 | version=2.0.0 | 否 |
| 协商默认值 | 旧版本 | 相同（默认 1.0） | 否 |
| 命名 | |||
| MetricFamily 必须匹配指标名称 | 隐式后缀剥离 | 需要精确匹配 | 是 |
| 计数器 _total 后缀 | _total 必须 | _total 应该 | 否 |
| 保留后缀 | 未指定 | _count/_sum/_bucket 等不应该 | 否 |
| 元数据 | |||
| UTF-8 名称 | |||
| 指标和标签名称引用 | 仅限 [a-zA-Z0-9_:] | 允许 UTF-8；必要时加引号 | 否 |
| 开始时间戳 | |||
| st@ 替换 _created | 独立的 _created 样本 | 样本行上的行内 st@ | 是 |
| CompositeValues (复合值) | |||
| 摘要 / 直方图 / 仪表直方图 | 展开的 _bucket/_count/_sum 行 | 单个 {key:value} 复合值 | 是 |
| 需要求和 (Sum) 和计数 (Count) | _count/_sum 可选 | 复合值中需要计数和求和 | 是 |
| 原生直方图 | |||
| 仅原生和组合直方图 | 不适用 | 通过 schema/spans/buckets/etc 实现指数分桶 | 否 |
| 样本示例 (Exemplars) | |||
| W3C 追踪上下文键 | 不适用 | 建议使用 trace_id 和 span_id | 否 |
| 强制时间戳 / 多个样本示例 | 可选时间戳；最多 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 内容类型协商。如果提取器未请求版本 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 规范中的 协议协商 (Protocol Negotiation)。
命名变更
OM 2.0 加强了 MetricFamily 名称与指标名称之间的关系，并更改了计数器和信息指标的后缀规则。在 OM 1.0 中，解析器会隐式剥离已知的后缀，将样本名称映射回其 MetricFamily。在 OM 2.0 中，这种隐式剥离已不复存在：MetricFamily 名称必须与每个指标的名称完全匹配。
通常，现在也建议使用强制的单位和 _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 (包含 Number 或 CompositeValue)
| 范围 | OM 1.0 术语 | OM 2.0 术语 | 变更内容 |
|---|---|---|---|
| 所有类型 | MetricSet | MetricSet | 未更改。 |
| 所有类型 | MetricFamily | MetricFamily | 名称现在必须匹配每个指标的名称（无隐式后缀剥离）。 |
| 所有类型 | Metric | Metric | 未更改。 |
| 所有类型 | MetricPoint | Sample | Sample 替换 MetricPoint。复杂类型（StateSet 除外）使用 CompositeValue 代替多个 MetricPoint。 |
| StateSet | Metric | MetricGroup | 共享一个标签集的所有状态的集合现在称为 MetricGroup。 |
| StateSet | MetricPoint | Metric | 该集合中的单个状态现在称为 Metric。 |
MetricFamily 名称必须匹配指标名称
中断性：TYPE、HELP 和 UNIT 注释中使用的 MetricFamily 名称必须与指标行上使用的名称匹配。
在 OM 1.0 中，计数器的 TYPE 行使用了基本名称（例如 http_requests），而其样本带有 _total 后缀（例如 http_requests_total）。解析器知道在将样本与 MetricFamily 匹配时剥离 _total，因此 MetricFamily 名称和样本指标名称可以不同。
在 OM 2.0 中，MetricFamily 名称必须与每个指标的名称完全匹配。没有隐式后缀剥离。对于计数器，这意味着如果样本使用 _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 中，计数器指标名称必须以 _total 结尾。
在 OM 2.0 中，计数器指标名称应该以 _total 结尾。它不再是强制性的。
提示：将规则更改为“应该”主要是为了实现与 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 样本，从而与您的仪表发生冲突。
这是一个“不应该”（而不是“必须不”），因此带有这些后缀的现有指标仍然可以解析。但是，重命名它们可以避免当您的指标被将复合类型展开为经典表示的系统消费时发生冲突错误。
参见：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 名称避免了保留后缀。直方图使用 CompositeValue 语法，所有分桶数据都在一行上（稍后介绍）。
- 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 引用 (UTF-8 Quoting)。
标签名称引用
不匹配 ^[a-zA-Z_][a-zA-Z0-9_]*$ 的标签名称必须用双引号括起来。任何标签名称都可以用双引号括起来，但仅当名称包含传统集之外的字符时，才需要加引号。
{"process.cpu.seconds","node.name"="my_node"} 4.20072246e+06
参见：OM 2.0 规范中的 UTF-8 引用 (UTF-8 Quoting)。
替代大括号语法
当指标名称需要加引号时，带引号的名称会移到大括号内作为第一个元素。这对于带引号的指标名称是必需的：指标名称必须出现在大括号内，而不是外面。在 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 引用 (UTF-8 Quoting)。
开始时间戳
中断性：_created 样本不再用于提供开始时间。
OM 2.0 用样本行本身上的行内开始时间戳 (st@) 替换了单独的 _created 样本，减小了公开大小并避免了 _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 必须匹配指标名称）。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 直方图使用 CompositeValue 语法（在复合值中详细介绍）。这里我们关注 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@ 时间戳出现在单个 CompositeValue 行上的值之后。
实践中的开始时间戳
此组合示例展示了与标签、时间戳、开始时间戳和展示完整字段顺序的样本示例一起使用的计数器和直方图
# 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
另请参阅：样本示例 (Exemplars)
参阅：OM 2.0 规范中的 Counter 和 Histogram with Classic Buckets。
CompositeValues
破坏性变更：传统的复合类型多行格式不再允许使用（StateSet 除外）。
在 OM 1.0 中，复杂指标类型（直方图、摘要、仪表直方图）表示为多行展开样本——每个存储桶一行，计数一行，求和一行。在 OM 2.0 中，这些指标合并为单一样本行，其值即为 CompositeValue：一个包含所有字段的结构化 {key:value,...} 块。
所有三种类型——histogram、summary 和 gaugehistogram——在 OM 2.0 中都必须使用 CompositeValue 语法。
语法概述
CompositeValue 用花括号括起来，包含逗号分隔的 key:value 字段，中间没有空格。键是固定的字面名称；值根据字段的不同，可以是数字、整数或括号括起来的列表。完整的键集合如下：
| 键 | 值类型 | 用于 | 描述 |
|---|---|---|---|
count | 数字 | histogram, summary | 观测次数。 |
sum | 数字 | histogram, summary | 观测值的总和。 |
gcount | 数字 | gaugehistogram | 仪表观测次数。 |
gsum | 数字 | gaugehistogram | 仪表观测值的总和。 |
quantile | [q:v,...] | summary | 分位数/值对，按分位数排序。 |
bucket | [le:v,...,+Inf:v] | histogram, gaugehistogram (经典) | 经典存储桶上限/计数对。必须包含 +Inf。 |
schema | 整数 | histogram, gaugehistogram (原生) | 原生直方图分辨率模式。 |
zero_threshold | 实数 | histogram, gaugehistogram (原生) | 零桶的宽度。 |
zero_count | 数字 | histogram, gaugehistogram (原生) | 零桶中的观测次数。 |
negative_spans | [off:len,...] | histogram, gaugehistogram (原生) | 负数桶的跨度定义。 |
negative_buckets | [v,...] | histogram, gaugehistogram (原生) | 负数桶的计数。 |
positive_spans | [off:len,...] | histogram, gaugehistogram (原生) | 正数桶的跨度定义。 |
positive_buckets | [v,...] | histogram, gaugehistogram (原生) | 正数桶的计数。 |
并非每个键都会出现在每个 CompositeValue 中。所需的键取决于指标类型：
- Summary:
count,sum,quantile - 经典直方图 (Classic histogram):
count,sum,bucket - 经典仪表直方图 (Classic gaugehistogram):
gcount,gsum,bucket - 原生直方图 (Native histogram):
count,sum,schema,zero_threshold,zero_count，以及可选的negative_spans/negative_buckets和/或positive_spans/positive_buckets - 原生仪表直方图 (Native 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 规范中的 CompositeValues。
总结
规则：在 OM 2.0 中，Summary 样本必须包含计数 (Count)、求和 (Sum) 和一组分位数。在 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]}
所有五个样本行折叠为一行。分位数映射移动到 CompositeValue 块内部。计数和求和现在是强制字段。如果没有观测值，请使用 quantile:[]（空分位数列表）。
参阅：OM 2.0 规范中的 Summary。
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 样本行合并为一个 CompositeValue。存储桶列表使用 threshold:count 对，并包含 +Inf 桶。字段必须按以下顺序出现：count, sum, bucket。_sum 和 _count 后缀将完全消失。
参阅：OM 2.0 规范中的 Histogram with Classic Buckets。
仪表盘直方图
仪表直方图 (GaugeHistogram) 测量当前分布（非重置型）。常见示例：队列深度、飞行中请求大小。与直方图不同，其值具有仪表语义——可以在不重置的情况下升降。OM 1.0 的展开格式使用 _gcount/_gsum 后缀；OM 2.0 使用带有 gcount 和 gsum 字段名的 CompositeValue（保留了仪表语义前缀）。
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]}
CompositeValue 格式与经典直方图类似，但使用 gcount 和 gsum 而不是 count 和 sum。TYPE 行也区分了它们。字段必须按以下顺序出现：gcount, gsum, bucket。仪表直方图没有开始时间戳（无创建语义）。
参阅：OM 2.0 规范中的 GaugeHistogram with Classic Buckets。
CompositeValues 实践
展示所有类型并存的完整展示示例
# 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
注意：计数器行使用纯数字值，而不是 CompositeValue。摘要和直方图使用 CompositeValue 块。仪表直方图没有开始时间戳（无创建语义）。
必需的求和与计数
破坏性变更：OM 2.0 不允许省略求和与计数。
在 OM 2.0 中，直方图和仪表直方图现在必须包含求和与计数。在 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
仪表直方图
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 规范中的 Histogram 和 GaugeHistogram。
原生直方图
非破坏性变更：原生直方图在 OM 1.0 中完全不受支持。
原生直方图是 OM 2.0 中的新特性。它们不使用在仪表化时选定的固定存储桶边界，而是使用指数存储桶模式，该模式在所有值范围内提供自动分辨率，无需任何存储桶配置。schema 字段控制存储桶宽度的粒度：值越高，产生的存储桶越窄（越精细）。
本节基于 CompositeValues 中介绍的 CompositeValue 语法。原生直方图字段遵循上述相同的 {key:value,...} 格式。
仅原生直方图
仅原生直方图的 CompositeValue 按顺序包含以下字段：
count-- 总观测次数（数字）。sum-- 所有观测值的总和（数字）。schema-- 控制指数桶宽度的整数（-4 到 8）。值越高表示粒度越细。zero_threshold-- 定义零桶边界 [-threshold, +threshold] 的非负浮点数。zero_count-- 零桶中的观测次数。positive_spans-- 映射桶索引的offset:length对列表（见下文）。positive_buckets-- 观测计数列表，每个桶一个。
跨度 (Spans) 是描述哪些指数桶已填充的 offset:length 对。第一个跨度的偏移量是起始桶索引（可以是负数）。其长度是从该索引开始连续填充的桶的数量。后续每个跨度的偏移量是下一组桶之前跳过的空桶数量。所有跨度长度之和等于桶列表中的值总数。关于桶边界公式，请参阅规范中的 Native Buckets。
负跨度和桶 (negative_spans, negative_buckets) 对负数观测值使用相同的语法。
如果没有桶被填充，则可以完全省略跨度和桶字段。
# 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
该示例有两个跨度：第一个从桶索引 0 开始，包含 3 个连续桶，然后跳过 2 个空桶，接着是 2 个连续桶。桶总数为 3 + 2 = 5，与 positive_buckets 中的五个值匹配。
参阅：OM 2.0 规范中的 Histogram with Native Buckets。
组合式经典与原生
某些消费者尚不支持原生桶。组合式的 CompositeValue 在单行中包含两种表示形式，以提供向后兼容性。字段顺序为：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 规范中的 Histogram with both Classic and Native Buckets。
原生桶的仪表直方图
带有原生桶的仪表直方图样本遵循与直方图相同的语法，只是使用 gcount 和 gsum 而不是 count 和 sum。TYPE 行也区分了它们。
参阅：OM 2.0 规范中的 GaugeHistogram with Native Buckets。
原生直方图实践
展示仅原生直方图和组合式经典+原生直方图并存的实际展示示例
# 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 行包含原生和经典桶字段，以兼容尚不支持原生桶的消费者。下一节将介绍可附加到这些行的示例语法（参阅 Exemplars）。
Exemplars（范例）
OM 2.0 更改了多项示例规则。强制时间戳、每个样本多个示例以及放宽的大小限制都会影响暴露程序如何将追踪上下文附加到指标上。
强制时间戳
破坏性变更：示例时间戳不再是可选的。
在 OM 1.0 中，示例时间戳是可选的。在 OM 2.0 中，每个示例都必须包含时间戳。仅此一项就是对不期望在示例值之后出现时间戳的 OM 1.0 解析器的破坏性变更。
http_requests_total 1027 1710000000 # {trace_id="abc123",span_id="def456"} 1.0 1709999999
示例（# 之后的所有内容）具有标签、一个值 (1.0) 和一个强制时间戳 (1709999999)。
多个示例
非破坏性变更：仍允许单个示例。
在 OM 1.0 中，每个样本最多只能有一个示例。OM 2.0 允许在单个样本上设置多个示例。每个示例都以 # 开头，后跟其自己的标签集、值和时间戳。
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 建议遵循 W3C Trace Context 约定，使用 trace_id 和 span_id 作为示例标签键。上面的示例已经证明了这一点。使用一致的键名使消费者无需针对每个暴露程序进行配置即可将指标与分布式追踪关联起来。
大小限制放宽
在 OM 1.0 中，示例标签集有严格的 128 字符限制。OM 2.0 移除了这一硬性上限，改为软性指导：暴露程序不应发出过大的示例标签集。这会将施加限制的责任转移给采集器，并在使用示例时提供更大的灵活性。
直方图示例放置
在 OM 1.0 中，直方图示例出现在单独的 _bucket 行上。在 OM 2.0 的 CompositeValue 语法中，示例附加在 CompositeValue 之后的单一样本行上。没有标签的示例必须使用空标签集 {}。将多个示例附加到样本时，请确保该样本上的所有示例使用一致的标签名称。
参阅：OM 2.0 规范中的 Exemplars。
未知类型
非破坏性变更
在 OM 1.0 中，未知类型指标中的样本只能具有数字值。在 OM 2.0 中，未知类型指标中的样本也可以具有 CompositeValue。
由于通常不应使用未知类型（它仅存在于类型不确定的第三方指标中），这是一个微小的变更。它主要影响需要处理任意未知类型数据的采集器和库。
参阅：OM 2.0 规范中的 Unknown。