指标类型

Prometheus 客户端库提供了四种核心指标类型。除了原生直方图之外，这些类型目前仅在插桩客户端库的 API 和展示协议中存在差异。Prometheus 服务器尚未利用这些类型信息，而是将除原生直方图以外的所有类型扁平化为无类型的浮点值时间序列。然而，原生直方图会作为特殊的复合直方图样本时间序列被摄取。未来，Prometheus 可能也会将其他指标类型作为复合类型来处理。此外，目前也正在开展持久化简单浮点样本类型信息的工作。

Counter（计数器）

计数器 (Counter) 是一种累计指标，代表一个单调递增的计数器 ，其值只能增加，或者在重新启动时重置为零。例如，您可以使用计数器来表示已服务的请求数、已完成的任务数或错误发生次数。

请勿使用计数器来暴露可能会减少的值。例如，不要将计数器用于当前运行的进程数；而应使用仪表（Gauge）。

各类插桩库关于计数器的使用文档

• Go 
• Java 
• Python 
• Ruby 
• .Net 
• Rust 

Gauge（仪表盘）

仪表 (Gauge) 是一种代表单个数值的指标，该数值可以任意上升或下降。

仪表通常用于测量值，例如温度或当前内存使用情况，但也用于可以增减的“计数”，例如并发请求数。

各类插桩库关于仪表的使用文档

• Go 
• Java 
• Python 
• Ruby 
• .Net 
• Rust 

Histogram（直方图）

直方图 (Histogram) 通过在可配置的桶（bucket）中对观测值（通常是请求持续时间或响应大小等）进行计数来记录它们。它还提供所有观测值的总和。因此，直方图本质上是一个分桶的计数器。但是，直方图也可以表示分布的当前状态，在这种情况下，它被称为 仪表直方图 (gauge histogram)。与通常类似于计数器的直方图相比，被检测（插桩）的程序很少直接暴露仪表直方图，因此在插桩库中还不可用（至少目前如此），但在新版本的 protobuf 展示格式和 OpenMetrics  中有所体现。它们也经常通过 PromQL 表达式创建。例如，对计数器直方图应用 rate 函数的结果是一个仪表直方图，这与对计数器应用 rate 函数的结果是一个仪表是相同的道理。

直方图存在两种根本不同的版本：较新的 原生直方图 (native histograms) 和较旧的 经典直方图 (classic histograms)。

原生直方图以复合样本的形式暴露和摄取，其中每个样本代表观测值的计数和总和，以及一组动态的桶。

然而，经典直方图由简单浮点样本的多个时间序列组成。基本指标名称为 <basename> 的经典直方图会产生以下时间序列：

• 观测桶的累计计数器，暴露为 <basename>_bucket{le="<upper inclusive bound>"}
• 所有观测值的 总和，暴露为 <basename>_sum
• 已观测事件的 计数，暴露为 <basename>_count（与上方的 <basename>_bucket{le="+Inf"} 相同）

原生直方图通常比经典直方图高效得多，允许更高的分辨率，在插桩期间不需要显式配置桶边界，并在通过网络传输时提供原子性（例如通过 Prometheus 远程写入协议，而经典直方图可能会因为其组成时间序列独立传输而面临部分传输失败的问题）。它们的桶模式确保了它们之间始终可以相互聚合，即使分辨率可能发生了变化，而具有不同桶边界的经典直方图通常无法聚合。如果您正在使用的插桩库支持原生直方图（目前 Go 和 Java 支持），您可能应该相比经典直方图，更倾向于选择原生直方图。

如果由于某种原因您只能使用经典直方图，有一种方法可以至少获得原生直方图的部分好处：您可以将 Prometheus 配置为将经典直方图摄取为一种特殊形式的原生直方图，称为具有自定义桶边界的原生直方图 (NHCB)。NHCB 的存储方式与普通原生直方图相同的复合样本一致，提供了与普通原生直方图类似的更高效率和原子网络传输。然而，NHCB 的桶布局仍然与其经典对应物相同（在插桩期间静态配置），具有相同的受限分辨率和范围，以及在更改桶边界时同样存在难以聚合的问题。

使用 histogram_quantile() 函数 从直方图甚至直方图聚合中计算分位数。它适用于经典直方图和原生直方图，仅语法略有不同。直方图也适用于计算 Apdex 分数 。

您可以直接对经典直方图的桶进行操作，因为它们表示为单独的时间序列（如上所述，称为 <basename>_bucket{le="<upper inclusive bound>"}）。但请记住，这些桶是 累积的 ，即每个桶都计算小于或等于作为标签提供的上限的所有观测值。对于原生直方图，您可以使用 histogram_fraction() 函数（用于计算观测比例）和 裁剪操作符（用于过滤所需的观测区间）来查看给定边界内的观测值。

有关直方图使用的详细信息以及与 摘要 的区别，请参阅 直方图与摘要。

注意从 Prometheus v3.0 开始，经典直方图的 le 标签值在摄取期间会被规范化，以符合 OpenMetrics 规范数字  的格式。

各类插桩库关于直方图的使用文档

• Go 
• Java 
• Python 
• Ruby 
• .Net 
• Rust 

总结

与 直方图 (Histogram) 类似，摘要 (Summary) 也会对观测值（通常是请求持续时间和响应大小等）进行采样。虽然它也提供观测值的总数和所有观测值的总和，但它会在滑动时间窗口内计算可配置的分位数。

在一次抓取中，基本指标名称为 <basename> 的摘要会暴露多个时间序列：

• 已观测事件的流式 φ-分位数（0 ≤ φ ≤ 1），暴露为 <basename>{quantile="<φ>"}
• 所有观测值的 总和，暴露为 <basename>_sum
• 已观测事件的 计数，暴露为 <basename>_count

有关 φ-分位数、摘要使用的详细解释以及与 直方图 的区别，请参阅 直方图与摘要。

注意从 Prometheus v3.0 开始，quantile 标签值在摄取期间会被规范化，以符合 OpenMetrics 规范数字  的格式。

各类插桩库关于摘要的使用文档

• Go 
• Java 
• Python 
• Ruby 
• .Net