可以使用简单的基于文本的说明格式向 Prometheus 公开度量指标。有多种客户端库可以为你实现这种格式。如果您的首选语言没有客户端库，您可以创建自己的客户端库。
从 Prometheus 2.0 版开始，所有向 Prometheus 公开度量指标的进程都需要使用基于文本的格式。在本节中，您可以找到有关该格式的一些基本信息以及更详细的格式说明。
信息项 | 描述 |
开始 | April 2014 |
支持版本 | Prometheus version >=0.4.0 |
传输方式 | HTTP |
编码 | UTF-8, \n line endings |
HTTP Content-Type | text/plain; version=0.0.4 (A missing version value will lead to a fall-back to the most recent text format version.) |
可选的 HTTP Content-Encoding | gzip |
优势 |
|
限制 |
|
支持的指标原始类型 |
|
Prometheus 的文本格式以行为导向。每行之间用换行符 (\n) 分隔。最后一行必须以换行符结束。空行将被忽略。
在一行中，标记符可以用任意数量的空格和/或制表符分隔（如果它们与前一个标记符合并，则必须至少用一个空格和/或制表符分隔）。前导和尾部空白将被忽略。
以 # 作为第一个非空格字符的行是注释。除非 # 后面的第一个字符是 HELP 或 TYPE，否则这些行将被忽略。这些行的处理方法如下： 如果标记为 HELP，则至少还需要一个标记，即指标名称。其余所有标记均视为该指标名称的文档字符串。HELP 行可以包含任何 UTF-8 字符序列（在度量名称之后），但反斜杠和换行符必须分别转义为 \ 和 \n。任何给定的度量衡名称只能有一个 HELP 行。
如果标记为 TYPE，则会出现另外两个标记。第一个是指标名称，第二个是 counter, gauge, histogram, summary, 或 untyped，定义了该名称的指标类型。一个给定的度量衡名称只能有一个 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）字符必须分别转义为\\、\"和\n。
value 是根据 Go 的 ParseFloat() 函数要求表示的浮点数。除了标准数值外，NaN、+Inf 和 -Inf 也是有效值，分别代表非数字、正无穷大和负无穷大。
时间戳是 int64（自纪元起的毫秒数，即 1970-01-01 00:00:00 UTC，不包括闰秒），用 Go 的ParseInt() 函数表示。
给定指标的所有行必须作为一组提供，并将可选的 "HELP" 和 "TYPE" 行放在首位（顺序不限）。除此以外，最好能在重复阐述中进行可重现的排序，但不是必需的，也就是说，如果计算成本过高，就不要排序。
每一行都必须有唯一的度量名称和标签组合。否则，摄取行为将无法定义。
直方图和摘要类型难以用文本格式表示。以下约定适用：
名为 x 的汇总或直方图的样本总和以名为 x_sum 的单独样本给出。
名为 x 的汇总或直方图的样本计数作为名为 x_count 的单独样本给出。
名为 x 的汇总的每个分位数都会作为单独的样本行给出，样本行的名称与 x 相同，标签为 {quantile="y"}。
以 x 命名的直方图的每个桶计数作为单独的样本行给出，其名称为 x_bucket，标签为 {le="y"}（其中 y 是桶的上限）。
直方图必须有一个带有 {le="+Inf"} 的桶。其值必须与 x_count 的值相同。
直方图的数据桶和摘要的量化值必须按其标签值（分别为 le 或量化值标签）的数字递增顺序排列。
下面是一个完整的 Prometheus 指标说明示例，包括注释、HELP 和 TYPE 表达式、直方图、摘要、字符转义示例等：
# 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 2693OpenMetrics 以 Prometheus 文本格式为基础，努力实现指标格式的标准化。至少从 v2.23.0 版开始，它就可以用于抓取目标，也可以用于联合度量。
利用 OpenMetrics 格式可以阐述和查询示例。示例提供了一个与度量集相关的时间点快照，用于其他汇总的度量族。此外，它们还可能附带一个跟踪 ID，与跟踪系统一起使用时，可以提供与特定服务相关的更详细信息。
要启用这一试验性功能，您必须至少拥有 v2.26.0 版本，并在参数中添加 --enable-feature=exemplar-storage。
除了当前基于文本的格式外，Prometheus 的早期版本还支持基于协议缓冲区（又称 Protobuf）的示例格式。随着 Prometheus 2.0 的发布，Protobuf 格式被标记为废弃格式，Prometheus 也停止了从该阐述格式摄取样本。
不过，Prometheus 增加了新的实验功能，其中 Protobuf 格式被认为是最可行的选择。这使得 Prometheus 再次接受 Protobuf。
以下是实验功能列表，一旦启用这些功能，Prometheus 就会倾向于使用 Protobuf 输出格式：
特征标志 | 引入它的版本 |
native-histograms | 2.40.0 |
created-timestamp-zero-ingestion | 2.50.0 |
有关历史格式版本的详细信息，请参阅旧版客户端数据说明格式文档。
原始 Protobuf 格式的当前版本（包括最近对本地直方图的扩展）保存在prometheus/client_model 资源库中。
川公网安备51010802032098
