向 Prometheus 暴露指标 | 鹏之背

date

related_level

slug

type

relate_date

summary

status

通过 HTTP 文本页面直接暴露指标

参考资料

https://prometheus.io/docs/instrumenting/exposition_formats/

https://prometheus.io/docs/instrumenting/content_negotiation/#protocol-headers

如果没有 exporter 和 client library，也可以通过简单的 Prometheus 文本格式，OpenMetrics 文本格式或者 Protobuf 格式来暴露指标

HTTP 文本页面暴露指标的优势和局限性

优势

人类可读
构造简单，尤其适用于轻量级场景（无需嵌套）
可逐行读取（类型提示和文档字符串除外）

局限性

冗长（verbose）
类型和文档字符串不是语法的组成部分，几乎无法进行指标契约验证
解析开销较大

对 HTTP Content-Type 类型的要求

被抓取的目标（scrape targets）必须在其指标端点返回有效的 Content-Type 响应头

如果 Content-Type 缺失、无法解析，或不属于支持的媒体类型，抓取将失败

每个协议都必须与特定的 MIME 类型和版本相关联

协议	MIME 类型	参数
PrometheusProto	application/vnd.google.protobuf	proto=io.prometheus.client.MetricFamily;encoding=delimited
PrometheusText0.0.4	text/plain	version=0.0.4
PrometheusText1.0.0	text/plain	version=1.0.0
OpenMetricsText0.0.1	application/openmetrics-text	version=0.0.1
OpenMetricsText1.0.0	application/openmetrics-text	version=1.0.0

Prometheus 文本格式

通过 HTTP 传输，HTTP Content-Type 为 text/plain; version=0.0.4 的 UTF-8 编码页面

可选 gzip 压缩
如果缺少 version 值，则将回退到最新的文本格式版本

支持所有原生指标类型（counter, gauge, histogram, summary）和未定义类型 untyped

Prometheus 文本格式是面向行的

行之间用换行符 ( \n ) 分隔，最后一行必须以换行符结尾
空行会被忽略

行格式

在一行内，各标记（token）之间可以用任意数量的空格和/或制表符分隔（如果两个标记连在一起会合并，则至少需要一个空白字符分隔）
行首和行尾的空白字符会被忽略

注释、帮助文本和类型信息

以 # 作为第一个非空白字符的行被视为注释

这些行通常会被忽略，除非 # 后的第一个标记是 HELP 或 TYPE

对于任意给定的指标名称，只能存在一条 HELP 行和 TYPE 行

HELP 行

在 # HELP 之后，至少还需要一个标记，即指标名称

其余所有标记被视为该指标的文档字符串

HELP 行在指标名称之后可以包含任意 UTF-8 字符序列，但反斜杠 \ 和换行符 \n 必须分别转义为 \\ 和 \n

TYPE 行

在 # TYPE 之后，必须且仅能有两个标记：第一个是指标名称，第二个是指标类型

有效指标类型：counter, gauge, histogram, summary, 未定义类型 untyped
如果没有为某个指标提供 TYPE 行，则其类型默认为 untyped

TYPE 行必须出现在该指标第一个样本数据之前

若指标名称不符合 Prometheus 传统命名字符集的要求，则必须使用引号并进行转义

样本数据行

其余行用于描述样本数据，每行一个样本，EBNF 语法如下

语法规则说明

identifier 带有 Prometheus 表达式语言的常规限制
escaped_string 由任何 UTF-8 字符组成，但反斜杠、双引号和换行符必须转义
value 是一个浮点数，格式需符合 Go 语言 ParseFloat() 函数的要求

除标准数值外，还支持 NaN, +Inf, -Inf

timestamp 是一个 int64 类型的时间戳，格式需符合 Go 语言 ParseInt() 函数的要求

Prometheus 文本中的 histogram 和 summary 约定

名为 x 的 summary 或 histogram

总和（sum） 以单独的样本 x_sum 表示
计数（count） 以单独的样本 x_count 表示

名为 x 的 summary

每个分位数（quantile）以单独的样本行表示，指标名为 x，并带有标签 {quantile="y"}

名为 x 的 histogram

每个桶（bucket）计数以单独的样本行表示，指标名为 x_bucket，并带有标签 {le="y"}（其中 y 是该桶的上界）
必须包含一个 {le="+Inf"} 的桶，其值必须等于 x_count 的值

histogram 的桶（按 le 标签）和 summary 的分位数（按 quantile 标签）必须按标签值的数值升序排列

Prometheus 文本行分组与排序

对于同一个指标的所有行，必须作为一个连续的组提供

该组中可选的 HELP 和 TYPE 行应放在最前面（二者顺序不限）

除上述要求外，重复暴露指标时建议保持可重现的排序，但非强制要求

若排序计算成本过高，可不排序

每一行的指标名称与标签组合必须唯一

否则，数据摄入（ingestion）行为将无法定义

Prometheus 文本格式示例

基于 Prometheus 文本格式的 OpenMetrics 文本格式

参考资料

https://prometheus.io/docs/specs/om/open_metrics_spec/

Prometheus 不仅可以使用 OpenMetrics 格式抓取目标，也支持将其用于指标联邦（federation）

示例数据（Exemplars）是对某个已汇总的 MetricFamily（指标族）在特定时间点的快照

实验性功能，Prometheus 需要在启动参数中添加 --enable-feature=exemplar-storage
Exemplar 可附带一个 Trace ID（追踪 ID），当与分布式追踪系统结合使用时，能提供与具体服务相关的更详细上下文信息

Protobuf 格式是基于 Protocol Buffers 的指标暴露格式

当以下任一条件满足时，Prometheus 将优先使用 Protobuf 格式

通过特性开关启用：-enable-feature=created-timestamp-zero-ingestion
在配置中启用：scrape_native_histograms: true

和文本格式比较

维度	文本格式	Protobuf
适用场景	Prometheus 内部、简单指标、人类可读	跨系统标准、复杂指标、高性能后端
设计哲学	Producer 简单优先	Consumer 结构清晰优先
标准化潜力	低（需重构）	高
未来扩展性	差（难以支持高级 histogram）	好
Prometheus 性能	更优（因优化实现）	较差（因 Go Protobuf 实现问题）

通过 HTTP 文本页面直接暴露指标

白鸟3