Live2d Test Env

普罗米修斯官方文档

 介绍

什么是普罗米修斯？

Prometheus是最初在SoundCloud上构建的开源系统监视和警报工具包 。自2012年成立以来，许多公司和组织都采用了Prometheus，该项目拥有非常活跃的开发人员和用户社区。现在，它是一个独立的开源项目，并且独立于任何公司进行维护。为了强调这一点并阐明项目的治理结构，Prometheus 在2016年加入了 Cloud Native Computing Foundation，这是继Kubernetes之后的第二个托管项目。

有关Prometheus的详细说明，请参见媒体部分中的资源链接 。

特征

普罗米修斯的主要特点是：

  • 一个多维数据模型，其中包含通过度量标准名称和键/值对标识的时间序列数据
  • PromQL，一种灵活的查询语言 ，可利用此维度
  • 不依赖分布式存储；单服务器节点是自治的
  • 时间序列收集通过HTTP上的拉模型进行
  • 通过中间网关支持推送时间序列
  • 通过服务发现或静态配置发现目标
  • 多种图形和仪表板支持模式

组件

Prometheus生态系统包含多个组件，其中许多是可选的：

  • Prometheus主服务器，它会刮取并存储时间序列数据
  • 客户端库，用于检测应用程序代码
  • 一个支持短暂工作的推送网关
  • 诸如HAProxy，StatsD，Graphite等服务的专用出口商
  • 一个alertmanager处理警报
  • 各种支持工具

大多数Prometheus组件都是用Go编写的，因此易于构建和部署为静态二进制文件。

建筑

下图说明了Prometheus的体系结构及其某些生态系统组件：

普罗米修斯建筑

Prometheus直接或通过中间推送网关从已检测作业中删除指标，以用于短期作业。它在本地存储所有刮取的样本，并对这些数据运行规则，以汇总和记录现有数据中的新时间序列，或生成警报。Grafana或其他API使用者可用于可视化收集的数据。

什么时候合适？

Prometheus非常适合记录任何纯数字时间序列。它既适合以机器为中心的监视，也适合于高度动态的面向服务的体系结构的监视。在微服务世界中，它对多维数据收集和查询的支持是一种特别的优势。

Prometheus的设计旨在提高可靠性，使其成为中断期间要使用的系统，以使您能够快速诊断问题。每个Prometheus服务器都是独立的，而不依赖于网络存储或其他远程服务。当基础结构的其他部分损坏时，您可以依靠它，并且无需设置广泛的基础结构即可使用它。

什么时候不合适？

普罗米修斯重视可靠性。即使在故障情况下，您始终可以查看有关系统的可用统计信息。如果您需要100％的准确性（例如按请求计费），则Prometheus并不是一个不错的选择，因为所收集的数据可能不会足够详细和完整。在这种情况下，最好使用其他系统来收集和分析数据以进行计费，并使用Prometheus进行其余的监视。

普罗米修斯！Prometheus是一个监视平台，它通过在这些目标上刮擦度量标准HTTP端点来从被监视的目标收集度量标准。本指南将向您展示如何使用Prometheus安装，配置和监视我们的第一个资源。您将下载，安装并运行Prometheus。您还将下载并安装导出器，这些工具可在主机和服务上显示时间序列数据。我们的第一个导出器将是Prometheus本身，它提供有关内存使用，垃圾回收等的各种主机级别指标。

下载Prometheus

下载适用于您的平台的最新版本的Prometheus，然后将其解压缩：

tar xvfz prometheus-*.tar.gz
cd prometheus-*

Prometheus服务器是一个称为prometheus（或prometheus.exe在Microsoft Windows上）的二进制文件。我们可以运行二进制文件，并通过传递--help标志来查看有关其选项的帮助。

./prometheus --help
usage: prometheus [<flags>]

The Prometheus monitoring server

. . .

在启动Prometheus之前，让我们对其进行配置。

配置Prometheus

Prometheus配置为YAML。Prometheus下载随附一个名为的文件中的示例配置，prometheus.yml这是一个入门的好地方。

我们删除了示例文件中的大多数注释，以使其更加简洁（注释以开头的行#）。

global:
  scrape_interval:     15s
  evaluation_interval: 15s

rule_files:
  # - "first.rules"
  # - "second.rules"

scrape_configs:
  - job_name: prometheus
    static_configs:
      - targets: ['localhost:9090']

有示例配置文件中配置的三个模块：global，rule_files，和scrape_configs。

该global块控制Prometheus服务器的全局配置。我们有两个选择。第一个scrape_interval控制，Prometheus多久刮一次目标。您可以为单个目标覆盖此目标。在这种情况下，全局设置是每15秒刮一次。该evaluation_interval选项控制Prometheus多久评估一次规则。Prometheus使用规则来创建新的时间序列并生成警报。

该rule_files块指定了我们希望Prometheus服务器加载的任何规则的位置。目前，我们还没有任何规则。

最后一块，scrape_configs控制Prometheus监视哪些资源。由于Prometheus还将有关自身的数据公开为HTTP端点，因此它可以抓取并监视其自身的运行状况。在默认配置中，有一个名为的作业，prometheus它会刮擦Prometheus服务器公开的时间序列数据。该作业包含一个静态配置的目标localhost端口9090。Prometheus希望指标可用于路径上的目标/metrics。因此，此默认作业是通过以下网址进行抓取：http：// localhost：9090 / metrics。

返回的时间序列数据将详细说明Prometheus服务器的状态和性能。

有关配置选项的完整说明，请参阅 配置文档。

开始普罗米修斯

要使用我们新创建的配置文件启动Prometheus，请切换到包含Prometheus二进制文件的目录并运行：

./prometheus --config.file=prometheus.yml

普罗米修斯应该开始。您还应该能够在http：// localhost：9090上浏览到有关其自身的状态页。给它大约30秒的时间，以从其自己的HTTP指标终结点收集有关自身的数据。

您还可以通过导航到自己的指标终结点：http：// localhost：9090 / metrics来验证Prometheus是否正在提供有关其自身的指标。

使用表达式浏览器

让我们尝试查看Prometheus收集的有关自身的一些数据。要使用Prometheus的内置表达式浏览器，请导航至 http：// localhost：9090 / graph，然后在“图形”选项卡中选择“控制台”视图。

正如您可以从http：// localhost：9090 / metrics收集的那样，称为Prometheus导出的有关其自身的一个指标 promhttp_metric_handler_requests_total（/metricsPrometheus服务器已处理的请求总数）。继续并将其输入到表达式控制台中：

promhttp_metric_handler_requests_total

这将返回多个不同的时间序列（以及每个序列的最新值），所有时间序列均带有度量名称promhttp_metric_handler_requests_total，但带有不同的标签。这些标签指定不同的请求状态。

如果我们只对导致HTTP代码的请求感兴趣200，则可以使用此查询来检索该信息：

promhttp_metric_handler_requests_total{code="200"}

要计算返回的时间序列数，您可以编写：

count(promhttp_metric_handler_requests_total)

有关表达语言的更多信息，请参见 表达语言文档。

使用绘图界面

要绘制图形表达式，请导航至http：// localhost：9090 / graph并使用“图形”选项卡。

例如，输入以下表达式以图形化显示自抓取的Prometheus中发生的每秒HTTP请求速率返回状态代码200：

rate(promhttp_metric_handler_requests_total{code="200"}[1m])

您可以尝试使用图形范围参数和其他设置。

监控其他目标

仅从Prometheus收集指标并不能很好地说明Prometheus的功能。为了更好地了解Prometheus可以做什么，我们建议您浏览有关其他出口商的文档。在使用节点监控出口Linux或MacOS的主机指标指南是一个良好的开端。

摘要

在本指南中，您安装了Prometheus，配置了Prometheus实例以监视资源，并了解了在Prometheus表达式浏览器中使用时间序列数据的一些基础知识。要继续学习Prometheus，请查看“ 概述”以获取有关接下来要探索的内容的一些想法。

普罗米修斯与石墨

范围

Graphite专注于成为具有查询语言和图形功能的被动时间序列数据库。其他任何问题都可以通过外部组件解决。

Prometheus是一个完整的监视和趋势分析系统，其中包括基于时间序列数据的内置和主动抓取，存储，查询，制图和警报。它了解有关世界的外观（应该存在哪些端点，什么时间序列模式意味着麻烦等），并积极尝试查找错误。

资料模型

石墨存储命名时间序列的数值样本，就像Prometheus一样。但是，Prometheus的元数据模型更加丰富：尽管Graphite指标名称由点分隔的组件组成，这些组件隐式地对维进行编码，但是Prometheus明确将维编码为键值对（称为标签），并附加到指标名称。这允许通过查询语言通过这些标签轻松进行过滤，分组和匹配。

此外，尤其是当Graphite与StatsD结合使用 时，通常只在所有受监视实例上存储聚合数据，而不是将实例保留为一个维度并能够深入到单个有问题的实例。

例如，使用Graphite / StatsD通常使用如下代码存储对API服务器的HTTP请求数以及响应代码500和POST对/tracks端点的方法：

stats.api-server.tracks.post.500 -> 93

在Prometheus中，可以像这样对相同的数据进行编码（假设三个api服务器实例）：

api_server_http_requests_total{method="POST",handler="/tracks",status="500",instance="<sample1>"} -> 34
api_server_http_requests_total{method="POST",handler="/tracks",status="500",instance="<sample2>"} -> 28
api_server_http_requests_total{method="POST",handler="/tracks",status="500",instance="<sample3>"} -> 31

存储

Graphite以Whisper格式将时间序列数据存储在本地磁盘上，这 是一种RRD样式的数据库，它希望样本以固定的时间间隔到达。每个时间序列都存储在一个单独的文件中，新样本在一定时间后会覆盖旧样本。

Prometheus还在每个时间序列上创建一个本地文件，但允许在出现刮擦或规则评估时以任意间隔存储样本。由于仅附加了新样本，因此旧数据可以任意保留。普罗米修斯（Prometheus）也适用于许多短暂的，经常变化的时间序列集。

摘要

Prometheus除了更易于运行和集成到您的环境之外，还提供了更丰富的数据模型和查询语言。如果您想要一个可以长期保存历史数据的群集解决方案，那么Graphite可能是一个更好的选择。

Prometheus与InfluxDB

InfluxDB是一个开放源代码的时间序列数据库，具有用于扩展和集群化的商业选项。Prometheus开发开始将近一年后，InfluxDB项目才发布，因此我们当时无法将其视为替代方案。尽管如此，Prometheus和InfluxDB之间仍然存在显着差异，并且两种系统都针对稍有不同的用例。

范围

为了进行公平的比较，我们还必须将Kapacitor与InfluxDB一起考虑 ，因为它们结合起来可以解决与Prometheus和Alertmanager相同的问题空间。

对于InfluxDB本身，与Graphite相同的范围差异 适用于此。此外，InfluxDB还提供连续查询，这些查询等同于Prometheus记录规则。

Kapacitor的范围是Prometheus记录规则，警报规则和Alertmanager的通知功能的组合。Prometheus提供了一种更强大的查询语言来进行图形显示和警报。Prometheus Alertmanager还提供了分组，重复数据删除和静音功能。

数据模型/存储

与Prometheus一样，InfluxDB数据模型也将键值对作为标签，称为标签。此外，InfluxDB还有第二级标签，称为字段，使用范围受到更多限制。InfluxDB支持最高达十亿分之一秒分辨率的时间戳，以及float64，int64，bool和字符串数据类型。相比之下，Prometheus支持float64数据类型，但对字符串和毫秒分辨率时间戳的支持有限。

InfluxDB使用日志结构合并树的变体进行存储，并带有按时间分片的预写日志。与Prometheus每个时间序列的仅附加文件相比，此方法更适合事件记录。

日志，指标和图形，我的天哪！ 描述了事件记录和指标记录之间的区别。

建筑

Prometheus服务器彼此独立运行，并且仅依靠其本地存储来实现其核心功能：抓取，规则处理和警报。InfluxDB的开源版本与此类似。

根据设计，商业InfluxDB产品是一个分布式存储集群，其中存储和查询由多个节点一次处理。

这意味着商业InfluxDB将更易于水平扩展，但是这也意味着您必须从一开始就管理分布式存储系统的复杂性。Prometheus的运行更简单，但是在某些时候，您将需要沿着产品，服务，数据中心或类似方面的可伸缩性边界明确地分片服务器。独立服务器（可以并行冗余运行）也可以为您提供更好的可靠性和故障隔离。

Kapacitor的开源版本没有用于规则，警报或通知的内置分布式/冗余选项。Kapacitor的开源发行版可以通过用户手动分片来扩展，类似于Prometheus本身。Influx提供了Enterprise Kapacitor，它支持HA /冗余警报系统。

相比之下，Prometheus和Alertmanager通过运行Prometheus的冗余副本并使用Alertmanager的高可用性 模式提供了完全开源的冗余选项 。

摘要

系统之间有许多相似之处。两者都有标签（在InfluxDB中称为标签），可以有效地支持多维指标。两者都使用基本相同的数据压缩算法。两者都有广泛的集成，包括彼此之间的集成。两者都有钩子，可让您进一步扩展它们，例如使用统计工具分析数据或执行自动操作。

InfluxDB更好的地方：

  • 如果您要进行事件记录。
  • 商业选项为InfluxDB提供集群，这对于长期数据存储也更好。
  • 最终在副本之间保持一致的数据视图。

普罗米修斯更好的地方：

  • 如果您主要是在做指标。
  • 更强大的查询语言，警报和通知功能。
  • 图形和警报的可用性和正常运行时间更高。

InfluxDB由一家商业公司按照开放核模型进行维护，并提供高级功能，如封闭源群集，托管和支持。Prometheus是一个完全开源的独立项目，由许多公司和个人维护，其中一些还提供商业服务和支持。

Prometheus与OpenTSDB

OpenTSDB是基于Hadoop和HBase的分布式时间序列数据库 。

范围

这里适用的范围与石墨相同 。

资料模型

OpenTSDB的数据模型几乎与Prometheus的数据模型相同：时间序列由一组任意键值对标识（OpenTSDB标签是Prometheus标签）。指标的所有数据都 存储在一起，从而限制了指标的基数。尽管有一些细微的差别：Prometheus允许标签值中包含任意字符，而OpenTSDB的限制更严格。OpenTSDB还缺少完整的查询语言，仅允许通过其API进行简单的汇总和数学运算。

存储

OpenTSDB的存储在Hadoop和HBase之上实现 。这意味着可以轻松地水平扩展OpenTSDB，但是您必须从一开始就接受运行Hadoop / HBase集群的总体复杂性。

Prometheus最初运行起来会更简单，但是一旦超出单个节点的容量，就需要进行明确的分片。

摘要

Prometheus提供了更丰富的查询语言，可以处理更高的基数指标，并且构成了完整监视系统的一部分。如果您已经在运行Hadoop并重视长期存储的优势，那么OpenTSDB是一个不错的选择。

普罗米修斯与纳吉斯

Nagios是一个始于1990年代的NetSaint监视系统。

范围

Nagios主要是基于脚本的退出代码进行警报。这些称为“检查”。单个警报会静音，但是不会进行分组，路由或重复数据删除。

有各种各样的插件。例如，允许管道传输几千字节的perfData插件以返回到时间序列数据库（例如Graphite）或使用NRPE 在远程计算机上运行检查。

资料模型

Nagios是基于主机的。每个主机可以具有一个或多个服务，并且每个服务可以执行一项检查。

没有标签或查询语言的概念。

存储

除了当前的检查状态外，Nagios本身还没有存储空间。有一些插件可以存储诸如可视化的数据。

建筑

Nagios服务器是独立的。所有检查配置均通过文件进行。

摘要

Nagios适用于黑匣子探测已足够的小型和/或静态系统的基本监视。

如果您想进行白盒监控，或者具有动态或基于云的环境，那么Prometheus是一个不错的选择。

普罗米修斯vs.森苏

Sensu是可组合的监视管道，可以重用现有的Nagios检查。

范围

这里适用与Nagios相同的一般范围差异。

还有一个客户端套接字，允许将临时检查结果推送到Sensu中。

资料模型

Sensu与Nagios具有相同的粗略数据模型。

存储

Sensu使用Redis持久监视数据，包括Sensu客户端注册表，检查结果，检查执行历史记录和当前事件数据。

建筑

Sensu具有许多组件。它使用RabbitMQ作为传输方式，使用Redis作为当前状态，并使用单独的服务器进行处理和API访问。

Sensu部署的所有组件（RabbitMQ，Redis和Sensu Server / API）都可以集群化，以实现高可用性和冗余配置。

摘要

如果您现有的Nagios设置希望按原样缩放，或者想利用Sensu的自动注册功能，那么Sensu是一个不错的选择。

如果您想进行白盒监控，或者具有非常动态或基于云的环境，那么Prometheus是一个不错的选择。

一般

什么是普罗米修斯？

Prometheus是具有活跃生态系统的开源系统监视和警报工具包。请参阅概述。

Prometheus与其他监控系统相比如何？

请参阅比较页面。

普罗米修斯有什么依赖性？

Prometheus主服务器独立运行，没有外部依赖性。

可以使Prometheus高度可用吗？

是的，在两台或更多台单独的计算机上运行相同的Prometheus服务器。相同的警报将由Alertmanager进行重复数据删除。

为了提高Alertmanager的可用性，您可以在Mesh群集中运行多个实例，并将Prometheus服务器配置为向每个实例 发送通知。

有人告诉我普罗米修斯“没有规模”。

实际上，存在多种缩放和联合Prometheus的方法。阅读 “稳健感知”博客上的扩展和联合Prometheus，以开始使用。

普罗米修斯用什么语言书写？

大多数Prometheus组件都是用Go编写的。有些还用Java，Python和Ruby编写。

Prometheus功能，存储格式和API的稳定性如何？

Prometheus GitHub组织中所有已达到版本1.0.0的存储库都大致遵循 语义版本控制。重大更改以主要版本的增量表示。实验性组件可能会出现例外，声明中会明确标明例外情况。

通常，即使尚未达到1.0.0版的存储库也相当稳定。我们的目标是为每个存储库制定适当的发布流程并最终发布1.0.0。无论如何，[CHANGE]对于尚未正式发布的组件，重大更改都将在发布说明中（以标记）或明确传达。

为什么要拉而不是推？

提取HTTP有许多优点：

  • 开发更改时，可以在笔记本电脑上运行监控。
  • 您可以更轻松地判断目标是否已关闭。
  • 您可以手动转到目标并使用Web浏览器检查其运行状况。

总体而言，我们认为拉动比推动略好，但在考虑使用监控系统时，不应将其视为重点。

对于必须推送的情况，我们提供Pushgateway。

如何将日志输入Prometheus？

简短的回答：不要！请改用ELK堆栈之类的东西。

更长的答案：Prometheus是一个收集和处理指标的系统，而不是事件记录系统。Raintank博客文章 Logs and Metrics and Graphs，Oh My！ 提供有关日志和指标之间差异的更多详细信息。

如果您想从应用程序日志中提取Prometheus指标，则Google的 mtail可能会有所帮助。

谁写了普罗米修斯？

Prometheus最初由Matt T. Proud和 Julius Volz私人创立 。它的大部分初始开发是由SoundCloud赞助的。

现在，它已由众多公司和个人维护和扩展。

Prometheus使用什么许可证？

Prometheus是根据 Apache 2.0许可发布的。

普罗米修斯的复数是什么？

经过广泛研究，已经确定“ Prometheus”的正确复数是“ Prometheis”。

我可以重新载入Prometheus的配置吗？

是的，发送SIGHUP到Prometheus进程或到/-/reload端点的HTTP POST请求 将重新加载并应用配置文件。各种组件尝试妥善处理失败的更改。

我可以发送警报吗？

是的，使用Alertmanager。

当前，支持以下外部系统：

我可以创建仪表板吗？

是的，我们建议您使用Grafana进行生产。也有控制台模板。

我可以更改时区吗？为什么所有内容都采用UTC？

为避免任何时区混乱，特别是在涉及所谓的夏时制时，我们决定在Prometheus的所有组件中内部专门使用Unix time和UTC进行显示。可以将精心完成的时区选择引入UI。欢迎捐款。有关 此工作的当前状态，请参阅 问题500。

仪器仪表

哪些语言有乐器库？

有许多客户端库可使用Prometheus指标来检测您的服务。有关 详细信息，请参见客户端库文档。

如果您有兴趣为新语言的客户库提供帮助，请参阅博览会格式。

我可以监视机器吗？

是的，Node Exporter在Linux和其他Unix系统上公开了一组广泛的计算机级别指标，例如CPU使用率，内存，磁盘使用率，文件系统完整性和网络带宽。

我可以监视网络设备吗？

是的，SNMP导出器允许监视支持SNMP的设备。

我可以监视批处理作业吗？

是的，使用Pushgateway。另请参阅监视批处理作业的 最佳做法。

Prometheus可以直接监视哪些应用程序？

请参阅导出器和集成列表。

我可以通过JMX监视JVM应用程序吗？

是的，对于不能直接使用Java客户端进行检测的应用程序，可以将JMX Exporter 单独使用或作为Java代理使用。

仪器的性能影响是什么？

客户端库和语言之间的性能可能会有所不同。对于Java， 基准测试 表明，根据争用，使用Java客户端增加计数器/表将花费12-17ns。除了对延迟最关键的代码之外，所有其他代码都可以忽略不计。

故障排除

我的Prometheus 1.x服务器需要花费很长时间才能启动，并且会向日志发送有关崩溃恢复的大量信息。

您正在遭受不干净的关机。Prometheus必须在结束后彻底关闭SIGTERM，对于频繁使用的服务器可能需要一段时间。如果服务器崩溃或被严重杀死（例如，内核被OOM杀死，或者在等待Prometheus关闭时，您的运行级别系统不耐烦），则必须执行崩溃恢复，在正常情况下，恢复时间应少于一分钟，但是可以在某些情况下要花很长时间。有关详细信息，请参见 崩溃恢复。

我的Prometheus 1.x服务器内存不足。

请参阅有关 配置Prometheus的内存使用情况的部分以获取可用内存量。

我的Prometheus 1.x服务器报告处于“紧急模式”或“存储需要节流”。

您的存储设备负担重。阅读 有关配置本地存储的部分， 以了解如何调整设置以获得更好的性能。

实作

为什么所有样本值都是64位浮点数？我想要整数。

我们将自己限制在64位浮点数以简化设计。该 IEEE 754双精度二进制浮点格式 支持整数精度值高达2 53。如果需要整数精度高于2 53但低于2 63，则支持本机64位整数将（仅）有帮助。原则上，可以实现对不同样本值类型（包括某种大整数，甚至支持64位以上）的支持，但现在并不是优先考虑的事情。计数器即使每秒增加一百万次，也只会在超过285年后才会出现精度问题。

为什么Prometheus服务器组件不支持TLS或身份验证？我可以添加那些吗？

注意：Prometheus团队在2018年8月11日的开发峰会上改变了其立场，该项目的路线图上现已支持在服务端点中支持TLS和身份验证 。更改代码后，将更新此文档。

尽管TLS和身份验证是经常需要的功能，但我们故意没有在Prometheus的任何服务器端组件中实现它们。两者都有太多不同的选项和参数（仅TLS就有10多个选项），我们决定专注于构建最佳监视系统，而不是在每个服务器组件中都支持完全通用的TLS和身份验证解决方案。

如果您需要TLS或身份验证，我们建议在Prometheus前面放置一个反向代理。例如，请参见使用Nginx将基本身份验证添加到Prometheus。

这仅适用于入站连接。Prometheus确实支持 刮除启用TLS和auth的目标，并且其他创建出站连接的Prometheus组件也具有类似的支持。

概念

资料模型

Prometheus从根本上将所有数据存储为时间序列：带有时间戳的值流属于同一度量标准和同一组标注维。除了存储的时间序列外，Prometheus可能会生成临时的导出时间序列作为查询的结果。

指标名称和标签

每个时间序列都通过其指标名称和可选的键值对（称为标签）来唯一标识。

所述度量名称指定了测得的系统的一般特征（例如http_requests_total-请求接收到的HTTP的总数）。它可能包含ASCII字母和数字，以及下划线和冒号。它必须匹配正则表达式[a-zA-Z_:][a-zA-Z0-9_:]*。

注意：冒号是为用户定义的记录规则保留的。出口商或直接仪器都不应使用它们。

标签启用了Prometheus的维度数据模型：具有相同度量标准名称的标签的任何给定组合都可以标识该度量标准的特定维度实例（例如：所有POST向/api/tracks处理程序使用该方法的HTTP请求）。查询语言允许基于这些维度进行过滤和聚合。更改任何标签值，包括添加或删除标签，都会创建一个新的时间序列。

标签名称可能包含ASCII字母，数字和下划线。它们必须匹配正则表达式[a-zA-Z_][a-zA-Z0-9_]*。开头的标签名称__ 保留供内部使用。

标签值可以包含任何Unicode字符。

标签值为空的标签被认为等同于不存在的标签。

另请参阅命名指标和标签的最佳做法。

样本

样本构成实际的时间序列数据。每个样本包括：

  • 一个float64值
  • 毫秒精度的时间戳

符号

给定度量标准名称和一组标签，通常使用以下符号来标识时间序列：

<metric name>{<label name>=<label value>, ...}

例如，度量名称的时间序列api_http_requests_total和标签method="POST"，并handler="/messages"可以这样写：

api_http_requests_total{method="POST", handler="/messages"}

这与OpenTSDB使用的符号相同。

METRIC TYPES

Prometheus客户端库提供了四种核心度量标准类型。这些仅在客户端库（以启用针对特定类型的使用量身定制的API）和有线协议中有所区别。Prometheus服务器尚未使用类型信息，而是将所有数据展平为未键入的时间序列。将来可能会改变。

计数器

一个计数器是代表一个累积指标单调递增计数器，其价值只能在重新启动增加或归零。例如，您可以使用计数器来表示已服务请求，已完成任务或错误的数量。

不要使用计数器来显示可以减小的值。例如，请勿对当前正在运行的进程数使用计数器；而是使用量规。

客户端的客户端库使用文档：

 

 

量规

甲轨距是表示单个数值，可以任意地上升和下降的度量。

量表通常用于测量值，例如温度或当前的内存使用量，还用于可能上升和下降的“计数”，例如并发请求数。

量规的客户端库使用文档：

 

 

直方图

甲直方图样本观测（通常之类的东西请求持续时间或响应大小）和计数它们配置的桶中。它还提供所有观察值的总和。

基本指标名称为的直方图<basename>在刮擦期间会暴露多个时间序列：

  • 观察桶的累积计数器，以 <basename>_bucket{le="<upper inclusive bound>"}
  • 的总和的所有观察值的，公开为<basename>_sum
  • 该计数已观察到的事件的，公开为<basename>_count（等同于<basename>_bucket{le="+Inf"}上文）

使用该 histogram_quantile()功能 可以根据直方图甚至是直方图的聚合来计算分位数。直方图也适用于计算 Apdex得分。在铲斗上操作时，请记住直方图是 累积的。有关直方图用法的详细信息以及与摘要的差异，请参见 直方图和摘要。

客户端库使用情况的直方图文档：

摘要

类似于直方图，摘要会采样观察结果（通常是请求持续时间和响应大小之类的东西）。尽管它还提供了观测值的总数和所有观测值的总和，但它可以计算滑动时间窗口内的可配置分位数。

基本度量标准名称为“摘要”的摘要会<basename>在刮刮期间显示多个时间序列：

  • 流φ-位数（0≤φ≤1）观察到的事件的，公开为<basename>{quantile="<φ>"}
  • 的总和的所有观察值的，公开为<basename>_sum
  • 该计数的事件已经被观察到，暴露<basename>_count

有关φ分位数的详细说明，摘要用法以及与直方图的差异，请参见直方图和摘要。

客户端库使用情况文档摘要：

作业和实例

用Prometheus术语来说，您可以抓取的端点称为实例，通常对应于单个进程。具有相同目的的实例的集合（例如，出于可伸缩性或可靠性而复制的过程）称为job。

例如，具有四个复制实例的API服务器作业：

  • 工作： api-server
    • 实例1： 1.2.3.4:5670
    • 实例2： 1.2.3.4:5671
    • 实例3： 5.6.7.8:5670
    • 实例4： 5.6.7.8:5671

自动生成的标签和时间序列

当Prometheus抓取目标时，它会自动在抓取的时间序列上附加一些标签，以识别被抓取的目标：

  • job：目标所属的已配置作业名称。
  • instance：<host>:<port>抓取的目标网址的一部分。

如果在抓取的数据中已经存在这些标签中的任何一个，则行为取决于honor_labels配置选项。有关 更多信息，请参见 抓取配置文档。

对于每个实例刮擦，Prometheus 按照以下时间序列存储样本：

  • up{job="<job-name>", instance="<instance-id>"}：1实例是否正常（即可达）或0刮取失败。
  • scrape_duration_seconds{job="<job-name>", instance="<instance-id>"}：刮擦的持续时间。
  • scrape_samples_post_metric_relabeling{job="<job-name>", instance="<instance-id>"}：应用公制重新标记后剩余的样本数。
  • scrape_samples_scraped{job="<job-name>", instance="<instance-id>"}：目标暴露的样本数量。
  • scrape_series_added{job="<job-name>", instance="<instance-id>"}：此刮板中新系列的大概数量。v2.10的新功能

该up时间序列对于实例可用性监视很有用。

 普罗米修斯

入门

本指南是一种“ Hello World”风格的教程，该教程显示了如何在简单的示例设置中安装，配置和使用Prometheus。您将在本地下载并运行Prometheus，对其进行配置以抓取自身和示例应用程序，然后使用查询，规则和图形来利用收集的时间序列数据。

下载并运行Prometheus

为您的平台下载最新版本的Prometheus，然后解压缩并运行它：

tar xvfz prometheus-*.tar.gz
cd prometheus-*

 

在启动Prometheus之前，让我们对其进行配置。

配置Prometheus进行自我监控

Prometheus通过在这些目标上刮擦度量标准HTTP端点来从受监视的目标收集度量标准。由于Prometheus还以相同的方式公开有关其自身的数据，因此它也可以抓取并监视其自身的运行状况。

虽然仅收集有关自身数据的Prometheus服务器在实践中不是很有用，但它是一个很好的入门示例。将以下基本Prometheus基本配置另存为名为的文件prometheus.yml：

global:
  scrape_interval:     15s # By default, scrape targets every 15 seconds.

  # Attach these labels to any time series or alerts when communicating with
  # external systems (federation, remote storage, Alertmanager).
  external_labels:
    monitor: 'codelab-monitor'

# A scrape configuration containing exactly one endpoint to scrape:
# Here it's Prometheus itself.
scrape_configs:
  # The job name is added as a label `job=<job_name>` to any timeseries scraped from this config.
  - job_name: 'prometheus'

    # Override the global default and scrape targets from this job every 5 seconds.
    scrape_interval: 5s

    static_configs:
      - targets: ['localhost:9090']

 

有关配置选项的完整说明，请参阅 配置文档。

开始普罗米修斯

要使用新创建的配置文件启动Prometheus，请切换到包含Prometheus二进制文件的目录并运行：

# Start Prometheus.
# By default, Prometheus stores its database in ./data (flag --storage.tsdb.path).
./prometheus --config.file=prometheus.yml

 

普罗米修斯应该开始。您还应该能够在localhost：9090浏览到有关其自身的状态页。花几秒钟的时间从其自己的HTTP指标终结点收集有关其自身的数据。

您还可以通过导航到其度量标准端点来验证Prometheus是否正在提供有关其自身的度量标准： localhost：9090 / metrics

使用表达式浏览器

让我们尝试查看Prometheus收集的有关自身的一些数据。要使用Prometheus的内置表达式浏览器，请导航至 http：// localhost：9090 / graph，然后在“图形”选项卡中选择“控制台”视图。

正如您可以从localhost：9090 / metrics收集的那样，称为Prometheus导出的有关其自身的一项指标 prometheus_target_interval_length_seconds（两次目标刮擦之间的实际时间间隔）。继续并将其输入到表达式控制台中：

prometheus_target_interval_length_seconds

这将返回多个不同的时间序列（以及每个序列的最新值），所有时间序列均带有度量名称 prometheus_target_interval_length_seconds，但带有不同的标签。这些标签指定不同的延迟百分比和目标组间隔。

如果我们只对第99个百分位延迟感兴趣，则可以使用以下查询来检索该信息：

prometheus_target_interval_length_seconds{quantile="0.99"}

要计算返回的时间序列数，您可以编写：

count(prometheus_target_interval_length_seconds)

有关表达语言的更多信息，请参见 表达语言文档。

使用绘图界面

要绘制图形表达式，请导航至http：// localhost：9090 / graph并使用“图形”选项卡。

例如，输入以下表达式以绘制在自抓取的Prometheus中创建的块的每秒速率：

rate(prometheus_tsdb_head_chunks_created_total[1m])

 

试用图形范围参数和其他设置。

启动一些样本目标

让我们变得更加有趣，并为Prometheus抓取一些示例目标。

Go客户端库包含一个示例，该示例导出具有不同延迟分布的三个服务的虚拟RPC延迟。

确保您已安装Go编译器，并设置了可正常运行的Go构建环境（带有正确的GOPATH）。

下载Prometheus的Go客户端库，并运行以下三个示例过程：

# Fetch the client library code and compile example.
git clone https://github.com/prometheus/client_golang.git
cd client_golang/examples/random
go get -d
go build

# Start 3 example targets in separate terminals:
./random -listen-address=:8080
./random -listen-address=:8081
./random -listen-address=:8082

 

现在，您应该具有示例目标，可以监听http：// localhost：8080 / metrics， http：// localhost：8081 / metrics和http：// localhost：8082 / metrics。

配置Prometheus监视样本目标

现在，我们将配置Prometheus来抓取这些新目标。让我们将所有三个端点归为一个名为的工作example-random。但是，假设前两个端点是生产目标，而第三个端点代表金丝雀实例。为了在Prometheus中对此建模，我们可以将多个端点组添加到单个作业中，并为每个目标组添加额外的标签。在此示例中，我们将group="production"标签添加到第一组目标，同时添加group="canary"到第二组。

为此，请将以下作业定义添加到scrape_configs 您的部分，prometheus.yml然后重新启动Prometheus实例：

scrape_configs:
  - job_name:       'example-random'

    # Override the global default and scrape targets from this job every 5 seconds.
    scrape_interval: 5s

    static_configs:
      - targets: ['localhost:8080', 'localhost:8081']
        labels:
          group: 'production'

      - targets: ['localhost:8082']
        labels:
          group: 'canary'

 

转到表达式浏览器，并验证Prometheus现在是否具有有关这些示例端点公开的时间序列的信息，例如 rpc_durations_seconds度量。

配置规则以将抓取的数据汇总到新的时间序列中

尽管在我们的示例中不是问题，但是在临时计算时，汇总了数千个时间序列的查询可能会变慢。为了提高效率，Prometheus允许您通过配置的记录规则将表达式预记录到全新的持久时间序列中。假设我们感兴趣的是记录在5分钟的时间内在rpc_durations_seconds_count所有实例（但保留job和service尺寸）上平均的示例RPC（）的每秒速率。我们可以这样写：

avg(rate(rpc_durations_seconds_count[5m])) by (job, service)

 

尝试绘制此表达式的图形。

要将由该表达式产生的时间序列记录到名为的新指标中job_service:rpc_durations_seconds_count:avg_rate5m，请使用以下记录规则创建一个文件，并将其另存为prometheus.rules.yml：

groups:
- name: example
  rules:
  - record: job_service:rpc_durations_seconds_count:avg_rate5m
    expr: avg(rate(rpc_durations_seconds_count[5m])) by (job, service)

 

要使Prometheus接受这一新规则，请在中添加一条rule_files语句prometheus.yml。现在，配置应如下所示：

global:
  scrape_interval:     15s # By default, scrape targets every 15 seconds.
  evaluation_interval: 15s # Evaluate rules every 15 seconds.

  # Attach these extra labels to all timeseries collected by this Prometheus instance.
  external_labels:
    monitor: 'codelab-monitor'

rule_files:
  - 'prometheus.rules.yml'

scrape_configs:
  - job_name: 'prometheus'

    # Override the global default and scrape targets from this job every 5 seconds.
    scrape_interval: 5s

    static_configs:
      - targets: ['localhost:9090']

  - job_name:       'example-random'

    # Override the global default and scrape targets from this job every 5 seconds.
    scrape_interval: 5s

    static_configs:
      - targets: ['localhost:8080', 'localhost:8081']
        labels:
          group: 'production'

      - targets: ['localhost:8082']
        labels:
          group: 'canary'

 

通过新配置重新启动Prometheus，并job_service:rpc_durations_seconds_count:avg_rate5m 通过表达式浏览器查询或绘制图表，以验证具有度量标准名称的新时间序列现在可用。

安装

使用预编译的二进制文件

我们为大多数官方Prometheus组件提供了预编译的二进制文件。请查看下载部分，以获取所有可用版本的列表。

从来源

要从源代码构建Prometheus组件，请参见Makefile相应存储库中的目标。

使用Docker

所有Prometheus服务都可以在Quay.io或 Docker Hub上作为Docker映像使用 。

在Docker上运行Prometheus就像docker run -p 9090:9090 prom/prometheus。这将以示例配置启动Prometheus，并将其公开在端口9090上。

Prometheus映像使用卷来存储实际指标。对于生产部署，强烈建议使用“ 数据卷容器” 模式来简化Prometheus升级中的数据管理。

要提供您自己的配置，有几个选项。这是两个例子。

体积和装订量

prometheus.yml通过运行以下命令从主机绑定挂载：

docker run \
    -p 9090:9090 \
    -v /tmp/prometheus.yml:/etc/prometheus/prometheus.yml \
    prom/prometheus

或使用其他卷进行配置：

docker run \
    -p 9090:9090 \
    -v /path/to/config:/etc/prometheus \
    prom/prometheus

自订图片

为了避免在主机上管理文件并将其绑定安装，可以将配置烘焙到映像中。如果配置本身是静态的，并且在所有环境中都相同，则此方法效果很好。

为此，使用Prometheus配置创建一个新目录， Dockerfile如下所示：

FROM prom/prometheus
ADD prometheus.yml /etc/prometheus/

 

现在构建并运行它：

docker build -t my-prometheus .
docker run -p 9090:9090 my-prometheus

 

一个更高级的选项是在使用某些工具开始时动态呈现配置，甚至让守护程序定期更新它。

使用配置管理系统

如果您更喜欢使用配置管理系统，则可能对以下第三方贡献感兴趣：

Ansible

Chef

Puppet

SaltStack

 配置

Prometheus通过命令行标志和配置文件进行配置。尽管命令行标志配置了不可变的系统参数（例如存储位置，要保留在磁盘和内存中的数据量等），但配置文件定义了与抓取作业及其实例有关的所有内容，以及哪些规则文件加载。

要查看所有可用的命令行标志，请运行./prometheus -h。

Prometheus可以在运行时重新加载其配置。如果新配置格式不正确，则更改将不会应用。通过向SIGHUPPrometheus进程发送a或向/-/reload端点发送HTTP POST请求（--web.enable-lifecycle启用该标志）来触发配置重载。这还将重新加载所有已配置的规则文件。

配置文件

要指定要加载的配置文件，请使用该--config.file标志。

该文件以YAML格式写入，由以下所述的方案定义。方括号表示参数是可选的。对于非列表参数，该值设置为指定的默认值。

通用占位符定义如下：

  • <boolean>：可以接受值的布尔值true或false
  • <duration>：与正则表达式匹配的持续时间 [0-9]+(ms|[smhdwy])
  • <labelname>：与正则表达式匹配的字符串 [a-zA-Z_][a-zA-Z0-9_]*
  • <labelvalue>：一串unicode字符
  • <filename>：当前工作目录中的有效路径
  • <host>：由主机名或IP后跟可选端口号组成的有效字符串
  • <path>：有效的网址路径
  • <scheme>：可以采用值http或https
  • <string>：常规字符串
  • <secret>：是秘密的常规字符串，例如密码
  • <tmpl_string>：使用前已模板扩展的字符串

其他占位符分别指定。

在这里可以找到有效的示例文件。

全局配置指定在所有其他配置上下文中有效的参数。它们还用作其他配置部分的默认设置。

global:
  # How frequently to scrape targets by default.
  [ scrape_interval: <duration> | default = 1m ]

  # How long until a scrape request times out.
  [ scrape_timeout: <duration> | default = 10s ]

  # How frequently to evaluate rules.
  [ evaluation_interval: <duration> | default = 1m ]

  # The labels to add to any time series or alerts when communicating with
  # external systems (federation, remote storage, Alertmanager).
  external_labels:
    [ <labelname>: <labelvalue> ... ]

  # File to which PromQL queries are logged.
  # Reloading the configuration will reopen the file.
  [ query_log_file: <string> ]

# Rule files specifies a list of globs. Rules and alerts are read from
# all matching files.
rule_files:
  [ - <filepath_glob> ... ]

# A list of scrape configurations.
scrape_configs:
  [ - <scrape_config> ... ]

# Alerting specifies settings related to the Alertmanager.
alerting:
  alert_relabel_configs:
    [ - <relabel_config> ... ]
  alertmanagers:
    [ - <alertmanager_config> ... ]

# Settings related to the remote write feature.
remote_write:
  [ - <remote_write> ... ]

# Settings related to the remote read feature.
remote_read:
  [ - <remote_read> ... ]

 

<scrape_config>

一个scrape_config小节指定一组目标和参数，描述如何刮除它们。在一般情况下，一个刮擦配置指定一个作业。在高级配置中，这可能会改变。

可以通过static_configs参数静态配置目标，也可以使用受支持的服务发现机制之一动态发现目标。

此外，relabel_configs在刮擦之前，允许对任何目标及其标签进行高级修改。

# The job name assigned to scraped metrics by default.
job_name: <job_name>

# How frequently to scrape targets from this job.
[ scrape_interval: <duration> | default = <global_config.scrape_interval> ]

# Per-scrape timeout when scraping this job.
[ scrape_timeout: <duration> | default = <global_config.scrape_timeout> ]

# The HTTP resource path on which to fetch metrics from targets.
[ metrics_path: <path> | default = /metrics ]

# honor_labels controls how Prometheus handles conflicts between labels that are
# already present in scraped data and labels that Prometheus would attach
# server-side ("job" and "instance" labels, manually configured target
# labels, and labels generated by service discovery implementations).
#
# If honor_labels is set to "true", label conflicts are resolved by keeping label
# values from the scraped data and ignoring the conflicting server-side labels.
#
# If honor_labels is set to "false", label conflicts are resolved by renaming
# conflicting labels in the scraped data to "exported_<original-label>" (for
# example "exported_instance", "exported_job") and then attaching server-side
# labels.
#
# Setting honor_labels to "true" is useful for use cases such as federation and
# scraping the Pushgateway, where all labels specified in the target should be
# preserved.
#
# Note that any globally configured "external_labels" are unaffected by this
# setting. In communication with external systems, they are always applied only
# when a time series does not have a given label yet and are ignored otherwise.
[ honor_labels: <boolean> | default = false ]

# honor_timestamps controls whether Prometheus respects the timestamps present
# in scraped data.
#
# If honor_timestamps is set to "true", the timestamps of the metrics exposed
# by the target will be used.
#
# If honor_timestamps is set to "false", the timestamps of the metrics exposed
# by the target will be ignored.
[ honor_timestamps: <boolean> | default = true ]

# Configures the protocol scheme used for requests.
[ scheme: <scheme> | default = http ]

# Optional HTTP URL parameters.
params:
  [ <string>: [<string>, ...] ]

# Sets the `Authorization` header on every scrape request with the
# configured username and password.
# password and password_file are mutually exclusive.
basic_auth:
  [ username: <string> ]
  [ password: <secret> ]
  [ password_file: <string> ]

# Sets the `Authorization` header on every scrape request with
# the configured bearer token. It is mutually exclusive with `bearer_token_file`.
[ bearer_token: <secret> ]

# Sets the `Authorization` header on every scrape request with the bearer token
# read from the configured file. It is mutually exclusive with `bearer_token`.
[ bearer_token_file: /path/to/bearer/token/file ]

# Configures the scrape request's TLS settings.
tls_config:
  [ <tls_config> ]

# Optional proxy URL.
[ proxy_url: <string> ]

# List of Azure service discovery configurations.
azure_sd_configs:
  [ - <azure_sd_config> ... ]

# List of Consul service discovery configurations.
consul_sd_configs:
  [ - <consul_sd_config> ... ]

# List of DNS service discovery configurations.
dns_sd_configs:
  [ - <dns_sd_config> ... ]

# List of EC2 service discovery configurations.
ec2_sd_configs:
  [ - <ec2_sd_config> ... ]

# List of OpenStack service discovery configurations.
openstack_sd_configs:
  [ - <openstack_sd_config> ... ]

# List of file service discovery configurations.
file_sd_configs:
  [ - <file_sd_config> ... ]

# List of GCE service discovery configurations.
gce_sd_configs:
  [ - <gce_sd_config> ... ]

# List of Kubernetes service discovery configurations.
kubernetes_sd_configs:
  [ - <kubernetes_sd_config> ... ]

# List of Marathon service discovery configurations.
marathon_sd_configs:
  [ - <marathon_sd_config> ... ]

# List of AirBnB's Nerve service discovery configurations.
nerve_sd_configs:
  [ - <nerve_sd_config> ... ]

# List of Zookeeper Serverset service discovery configurations.
serverset_sd_configs:
  [ - <serverset_sd_config> ... ]

# List of Triton service discovery configurations.
triton_sd_configs:
  [ - <triton_sd_config> ... ]

# List of labeled statically configured targets for this job.
static_configs:
  [ - <static_config> ... ]

# List of target relabel configurations.
relabel_configs:
  [ - <relabel_config> ... ]

# List of metric relabel configurations.
metric_relabel_configs:
  [ - <relabel_config> ... ]

# Per-scrape limit on number of scraped samples that will be accepted.
# If more than this number of samples are present after metric relabelling
# the entire scrape will be treated as failed. 0 means no limit.
[ sample_limit: <int> | default = 0 ]

 

在<job_name>所有刮板配置中，哪里必须是唯一的。

<tls_config>

A tls_config允许配置TLS连接。

# CA certificate to validate API server certificate with.
[ ca_file: <filename> ]

# Certificate and key files for client cert authentication to the server.
[ cert_file: <filename> ]
[ key_file: <filename> ]

# ServerName extension to indicate the name of the server.
# https://tools.ietf.org/html/rfc4366#section-3.1
[ server_name: <string> ]

# Disable validation of the server certificate.
[ insecure_skip_verify: <boolean> ]

 

<azure_sd_config>

Azure SD配置允许从Azure VM检索抓取目标。

重新标记期间，以下meta标签可用于目标：

  • __meta_azure_machine_id：机器ID
  • __meta_azure_machine_location：机器运行的位置
  • __meta_azure_machine_name：机器名称
  • __meta_azure_machine_os_type：机器操作系统
  • __meta_azure_machine_private_ip：机器的专用IP
  • __meta_azure_machine_public_ip：机器的公用IP（如果存在）
  • __meta_azure_machine_resource_group：机器的资源组
  • __meta_azure_machine_tag_<tagname>：机器的每个标签值
  • __meta_azure_machine_scale_set：vm所属的比例尺集的名称（仅当您使用比例尺集时才设置此值）
  • __meta_azure_subscription_id：订阅ID
  • __meta_azure_tenant_id：租户ID

请参阅以下有关Azure发现的配置选项：

# The information to access the Azure API.
# The Azure environment.
[ environment: <string> | default = AzurePublicCloud ]

# The authentication method, either OAuth or ManagedIdentity.
# See https://docs.microsoft.com/en-us/azure/active-directory/managed-identities-azure-resources/overview
[ authentication_method: <string> | default = OAuth]
# The subscription ID. Always required.
subscription_id: <string>
# Optional tenant ID. Only required with authentication_method OAuth.
[ tenant_id: <string> ]
# Optional client ID. Only required with authentication_method OAuth.
[ client_id: <string> ]
# Optional client secret. Only required with authentication_method OAuth.
[ client_secret: <secret> ]

# Refresh interval to re-read the instance list.
[ refresh_interval: <duration> | default = 300s ]

# The port to scrape metrics from. If using the public IP address, this must
# instead be specified in the relabeling rule.
[ port: <int> | default = 80 ]

 

<consul_sd_config>

Consul SD配置允许从Consul的 Catalog API 检索抓取目标。

重新标记期间，目标上可以使用以下元标记：

  • __meta_consul_address：目标地址
  • __meta_consul_dc：目标的数据中心名称
  • __meta_consul_tagged_address_<key>：每个节点标记了目标的地址键值
  • __meta_consul_metadata_<key>：目标的每个节点元数据键值
  • __meta_consul_node：为目标定义的节点名称
  • __meta_consul_service_address：目标的服务地址
  • __meta_consul_service_id：目标的服务ID
  • __meta_consul_service_metadata_<key>：目标的每个服务元数据键值
  • __meta_consul_service_port：目标的服务端口
  • __meta_consul_service：目标所属的服务名称
  • __meta_consul_tags：由标签分隔符连接的目标的标签列表
# The information to access the Consul API. It is to be defined
# as the Consul documentation requires.
[ server: <host> | default = "localhost:8500" ]
[ token: <secret> ]
[ datacenter: <string> ]
[ scheme: <string> | default = "http" ]
[ username: <string> ]
[ password: <secret> ]

tls_config:
  [ <tls_config> ]

# A list of services for which targets are retrieved. If omitted, all services
# are scraped.
services:
  [ - <string> ]

# See https://www.consul.io/api/catalog.html#list-nodes-for-service to know more
# about the possible filters that can be used.

# An optional list of tags used to filter nodes for a given service. Services must contain all tags in the list.
tags:
  [ - <string> ]

# Node metadata used to filter nodes for a given service.
[ node_meta:
  [ <name>: <value> ... ] ]

# The string by which Consul tags are joined into the tag label.
[ tag_separator: <string> | default = , ]

# Allow stale Consul results (see https://www.consul.io/api/features/consistency.html). Will reduce load on Consul.
[ allow_stale: <bool> ]

# The time after which the provided names are refreshed.
# On large setup it might be a good idea to increase this value because the catalog will change all the time.
[ refresh_interval: <duration> | default = 30s ]

 

请注意，用于刮擦目标的IP地址和端口组装为 <__meta_consul_address>:<__meta_consul_service_port>。但是，在某些Consul设置中，相关地址在中__meta_consul_service_address。在这种情况下，您可以使用重新标签 功能来替换特殊__address__标签。

在重新标记阶段是过滤器的服务或节点优选和更有力的方式为基于任意标签的服务。对于拥有数千项服务的用户而言，直接使用Consul API更为有效，该API具有基本的过滤节点支持（当前通过节点元数据和单个标签）。

<dns_sd_config>

基于DNS的服务发现配置允许指定一组DNS域名，这些域名会定期查询以发现目标列表。从中读取要联系的DNS服务器/etc/resolv.conf。

此服务发现方法仅支持基本DNS A，AAAA和SRV记录查询，但不支持RFC6763中指定的高级DNS-SD方法 。

在重新标记阶段，元标记 __meta_dns_name在每个目标上可用，并设置为产生发现的目标的记录名称。

# A list of DNS domain names to be queried.
names:
  [ - <domain_name> ]

# The type of DNS query to perform.
[ type: <query_type> | default = 'SRV' ]

# The port number used if the query type is not SRV.
[ port: <number>]

# The time after which the provided names are refreshed.
[ refresh_interval: <duration> | default = 30s ]

 

<domain_name>有效的DNS域名在哪里。凡<query_type>为SRV，A或AAAA。

<ec2_sd_config>

EC2 SD配置允许从AWS EC2实例检索抓取目标。默认情况下使用私有IP地址，但可以通过重新标记将其更改为公共IP地址。

重新标记期间，目标上可以使用以下元标记：

  • __meta_ec2_availability_zone：实例在其中运行的可用性区域
  • __meta_ec2_instance_id：EC2实例ID
  • __meta_ec2_instance_state：EC2实例的状态
  • __meta_ec2_instance_type：EC2实例的类型
  • __meta_ec2_owner_id：拥有EC2实例的AWS账户的ID
  • __meta_ec2_platform：操作系统平台，在Windows服务器上设置为“ Windows”，否则不存在
  • __meta_ec2_primary_subnet_id：主网络接口的子网ID（如果有）
  • __meta_ec2_private_dns_name：实例的私有DNS名称（如果有）
  • __meta_ec2_private_ip：实例的私有IP地址（如果存在）
  • __meta_ec2_public_dns_name：实例的公共DNS名称（如果有）
  • __meta_ec2_public_ip：实例的公共IP地址（如果有）
  • __meta_ec2_subnet_id：用逗号分隔的实例在其中运行的子网ID列表（如果有）
  • __meta_ec2_tag_<tagkey>：实例的每个标签值
  • __meta_ec2_vpc_id：运行实例的VPC的ID（如果有）

请参阅以下有关EC2发现的配置选项：

# The information to access the EC2 API.

# The AWS region. If blank, the region from the instance metadata is used.
[ region: <string> ]

# Custom endpoint to be used.
[ endpoint: <string> ]

# The AWS API keys. If blank, the environment variables `AWS_ACCESS_KEY_ID`
# and `AWS_SECRET_ACCESS_KEY` are used.
[ access_key: <string> ]
[ secret_key: <secret> ]
# Named AWS profile used to connect to the API.
[ profile: <string> ]

# AWS Role ARN, an alternative to using AWS API keys.
[ role_arn: <string> ]

# Refresh interval to re-read the instance list.
[ refresh_interval: <duration> | default = 60s ]

# The port to scrape metrics from. If using the public IP address, this must
# instead be specified in the relabeling rule.
[ port: <int> | default = 80 ]

# Filters can be used optionally to filter the instance list by other criteria.
# Available filter criteria can be found here:
# https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeInstances.html
# Filter API documentation: https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_Filter.html
filters:
  [ - name: <string>
      values: <string>, [...] ]

 

在重新标记阶段是基于任意标签过滤目标的优选和更强大的方式。对于具有数千个实例的用户，直接使用支持过滤实例的EC2 API可能会更有效。

<openstack_sd_config>

OpenStack SD配置允许从OpenStack Nova实例检索抓取目标。

<openstack_role>可以将以下类型之一配置为发现目标：

hypervisor

该hypervisor角色为每个Nova虚拟机管理程序节点发现一个目标。目标地址默认为host_ip虚拟机监控程序的属性。

The following meta labels are available on targets during relabeling:

  • __meta_openstack_hypervisor_host_ip: the hypervisor node's IP address.
  • __meta_openstack_hypervisor_name: the hypervisor node's name.
  • __meta_openstack_hypervisor_state: the hypervisor node's state.
  • __meta_openstack_hypervisor_status: the hypervisor node's status.
  • __meta_openstack_hypervisor_type: the hypervisor node's type.

instance

The instance role discovers one target per network interface of Nova instance. The target address defaults to the private IP address of the network interface.

The following meta labels are available on targets during relabeling:

  • __meta_openstack_address_pool: the pool of the private IP.
  • __meta_openstack_instance_flavor: the flavor of the OpenStack instance.
  • __meta_openstack_instance_id: the OpenStack instance ID.
  • __meta_openstack_instance_name: the OpenStack instance name.
  • __meta_openstack_instance_status: the status of the OpenStack instance.
  • __meta_openstack_private_ip: the private IP of the OpenStack instance.
  • __meta_openstack_project_id: the project (tenant) owning this instance.
  • __meta_openstack_public_ip: the public IP of the OpenStack instance.
  • __meta_openstack_tag_<tagkey>: each tag value of the instance.
  • __meta_openstack_user_id: the user account owning the tenant.

请参阅以下有关OpenStack发现的配置选项：

# The information to access the OpenStack API.

# The OpenStack role of entities that should be discovered.
role: <openstack_role>

# The OpenStack Region.
region: <string>

# identity_endpoint specifies the HTTP endpoint that is required to work with
# the Identity API of the appropriate version. While it's ultimately needed by
# all of the identity services, it will often be populated by a provider-level
# function.
[ identity_endpoint: <string> ]

# username is required if using Identity V2 API. Consult with your provider's
# control panel to discover your account's username. In Identity V3, either
# userid or a combination of username and domain_id or domain_name are needed.
[ username: <string> ]
[ userid: <string> ]

# password for the Identity V2 and V3 APIs. Consult with your provider's
# control panel to discover your account's preferred method of authentication.
[ password: <secret> ]

# At most one of domain_id and domain_name must be provided if using username
# with Identity V3. Otherwise, either are optional.
[ domain_name: <string> ]
[ domain_id: <string> ]

# The project_id and project_name fields are optional for the Identity V2 API.
# Some providers allow you to specify a project_name instead of the project_id.
# Some require both. Your provider's authentication policies will determine
# how these fields influence authentication.
[ project_name: <string> ]
[ project_id: <string> ]

# The application_credential_id or application_credential_name fields are
# required if using an application credential to authenticate. Some providers
# allow you to create an application credential to authenticate rather than a
# password.
[ application_credential_name: <string> ]
[ application_credential_id: <string> ]

# The application_credential_secret field is required if using an application
# credential to authenticate.
[ application_credential_secret: <secret> ]

# Whether the service discovery should list all instances for all projects.
# It is only relevant for the 'instance' role and usually requires admin permissions.
[ all_tenants: <boolean> | default: false ]

# Refresh interval to re-read the instance list.
[ refresh_interval: <duration> | default = 60s ]

# The port to scrape metrics from. If using the public IP address, this must
# instead be specified in the relabeling rule.
[ port: <int> | default = 80 ]

# TLS configuration.
tls_config:
  [ <tls_config> ]

 

<file_sd_config>

基于文件的服务发现提供了一种配置静态目标的更通用的方法，并用作插入自定义服务发现机制的接口。

它读取一组包含零个或多个 <static_config>s的文件。对所有已定义文件的更改将通过磁盘监视来检测并立即应用。文件可以以YAML或JSON格式提供。仅应用导致形成良好目标组的更改。

JSON文件必须包含使用以下格式的静态配置列表：

[
  {
    "targets": [ "<host>", ... ],
    "labels": {
      "<labelname>": "<labelvalue>", ...
    }
  },
  ...
]

作为备用，文件内容也将以指定的刷新间隔定期重新读取。

__meta_filepath在 重新标记阶段，每个目标都有一个元标记。它的值设置为从中提取目标的文件路径。

There is a list of integrations with this discovery mechanism.

# Patterns for files from which target groups are extracted.
files:
  [ - <filename_pattern> ... ]

# Refresh interval to re-read the files.
[ refresh_interval: <duration> | default = 5m ]

Where <filename_pattern> may be a path ending in .json, .yml or .yaml. The last path segment may contain a single * that matches any character sequence, e.g. my/path/tg_*.json.

<gce_sd_config>

GCE SD configurations allow retrieving scrape targets from GCP GCE instances. The private IP address is used by default, but may be changed to the public IP address with relabeling.

The following meta labels are available on targets during relabeling:

  • __meta_gce_instance_id: the numeric id of the instance
  • __meta_gce_instance_name: the name of the instance
  • __meta_gce_label_<name>: each GCE label of the instance
  • __meta_gce_machine_type: full or partial URL of the machine type of the instance
  • __meta_gce_metadata_<name>: each metadata item of the instance
  • __meta_gce_network: the network URL of the instance
  • __meta_gce_private_ip: the private IP address of the instance
  • __meta_gce_project: the GCP project in which the instance is running
  • __meta_gce_public_ip: the public IP address of the instance, if present
  • __meta_gce_subnetwork: the subnetwork URL of the instance
  • __meta_gce_tags: comma separated list of instance tags
  • __meta_gce_zone: the GCE zone URL in which the instance is running

See below for the configuration options for GCE discovery:

# The information to access the GCE API.

# The GCP Project
project: <string>

# The zone of the scrape targets. If you need multiple zones use multiple
# gce_sd_configs.
zone: <string>

# Filter can be used optionally to filter the instance list by other criteria
# Syntax of this filter string is described here in the filter query parameter section:
# https://cloud.google.com/compute/docs/reference/latest/instances/list
[ filter: <string> ]

# Refresh interval to re-read the instance list
[ refresh_interval: <duration> | default = 60s ]

# The port to scrape metrics from. If using the public IP address, this must
# instead be specified in the relabeling rule.
[ port: <int> | default = 80 ]

# The tag separator is used to separate the tags on concatenation
[ tag_separator: <string> | default = , ]

 

Credentials are discovered by the Google Cloud SDK default client by looking in the following places, preferring the first location found:

  1. a JSON file specified by the GOOGLE_APPLICATION_CREDENTIALS environment variable
  2. a JSON file in the well-known path $HOME/.config/gcloud/application_default_credentials.json
  3. fetched from the GCE metadata server

If Prometheus is running within GCE, the service account associated with the instance it is running on should have at least read-only permissions to the compute resources. If running outside of GCE make sure to create an appropriate service account and place the credential file in one of the expected locations.

<kubernetes_sd_config>

Kubernetes SD configurations allow retrieving scrape targets from Kubernetes' REST API and always staying synchronized with the cluster state.

One of the following role types can be configured to discover targets:

node

The node role discovers one target per cluster node with the address defaulting to the Kubelet's HTTP port. The target address defaults to the first existing address of the Kubernetes node object in the address type order of NodeInternalIP, NodeExternalIP, NodeLegacyHostIP, and NodeHostName.

Available meta labels:

  • __meta_kubernetes_node_name: The name of the node object.
  • __meta_kubernetes_node_label_<labelname>: Each label from the node object.
  • __meta_kubernetes_node_labelpresent_<labelname>: true for each label from the node object.
  • __meta_kubernetes_node_annotation_<annotationname>: Each annotation from the node object.
  • __meta_kubernetes_node_annotationpresent_<annotationname>: true for each annotation from the node object.
  • __meta_kubernetes_node_address_<address_type>: The first address for each node address type, if it exists.

In addition, the instance label for the node will be set to the node name as retrieved from the API server.

service

The service role discovers a target for each service port for each service. This is generally useful for blackbox monitoring of a service. The address will be set to the Kubernetes DNS name of the service and respective service port.

Available meta labels:

  • __meta_kubernetes_namespace: The namespace of the service object.
  • __meta_kubernetes_service_annotation_<annotationname>: Each annotation from the service object.
  • __meta_kubernetes_service_annotationpresent_<annotationname>: "true" for each annotation of the service object.
  • __meta_kubernetes_service_cluster_ip: The cluster IP address of the service. (Does not apply to services of type ExternalName)
  • __meta_kubernetes_service_external_name: The DNS name of the service. (Applies to services of type ExternalName)
  • __meta_kubernetes_service_label_<labelname>: Each label from the service object.
  • __meta_kubernetes_service_labelpresent_<labelname>: true for each label of the service object.
  • __meta_kubernetes_service_name: The name of the service object.
  • __meta_kubernetes_service_port_name: Name of the service port for the target.
  • __meta_kubernetes_service_port_protocol: Protocol of the service port for the target.

pod

The pod role discovers all pods and exposes their containers as targets. For each declared port of a container, a single target is generated. If a container has no specified ports, a port-free target per container is created for manually adding a port via relabeling.

Available meta labels:

  • __meta_kubernetes_namespace: The namespace of the pod object.
  • __meta_kubernetes_pod_name: The name of the pod object.
  • __meta_kubernetes_pod_ip: The pod IP of the pod object.
  • __meta_kubernetes_pod_label_<labelname>: Each label from the pod object.
  • __meta_kubernetes_pod_labelpresent_<labelname>: truefor each label from the pod object.
  • __meta_kubernetes_pod_annotation_<annotationname>: Each annotation from the pod object.
  • __meta_kubernetes_pod_annotationpresent_<annotationname>: true for each annotation from the pod object.
  • __meta_kubernetes_pod_container_init: true if the container is an InitContainer
  • __meta_kubernetes_pod_container_name: Name of the container the target address points to.
  • __meta_kubernetes_pod_container_port_name: Name of the container port.
  • __meta_kubernetes_pod_container_port_number: Number of the container port.
  • __meta_kubernetes_pod_container_port_protocol: Protocol of the container port.
  • __meta_kubernetes_pod_ready: Set to true or false for the pod's ready state.
  • __meta_kubernetes_pod_phase: Set to Pending, Running, Succeeded, Failed or Unknown in the lifecycle.
  • __meta_kubernetes_pod_node_name: The name of the node the pod is scheduled onto.
  • __meta_kubernetes_pod_host_ip: The current host IP of the pod object.
  • __meta_kubernetes_pod_uid: The UID of the pod object.
  • __meta_kubernetes_pod_controller_kind: Object kind of the pod controller.
  • __meta_kubernetes_pod_controller_name: Name of the pod controller.

endpoints

The endpoints role discovers targets from listed endpoints of a service. For each endpoint address one target is discovered per port. If the endpoint is backed by a pod, all additional container ports of the pod, not bound to an endpoint port, are discovered as targets as well.

Available meta labels:

  • __meta_kubernetes_namespace: The namespace of the endpoints object.
  • __meta_kubernetes_endpoints_name: The names of the endpoints object.
  • For all targets discovered directly from the endpoints list (those not additionally inferred from underlying pods), the following labels are attached:
    • __meta_kubernetes_endpoint_hostname: Hostname of the endpoint.
    • __meta_kubernetes_endpoint_node_name: Name of the node hosting the endpoint.
    • __meta_kubernetes_endpoint_ready: Set to true or false for the endpoint's ready state.
    • __meta_kubernetes_endpoint_port_name: Name of the endpoint port.
    • __meta_kubernetes_endpoint_port_protocol: Protocol of the endpoint port.
    • __meta_kubernetes_endpoint_address_target_kind: Kind of the endpoint address target.
    • __meta_kubernetes_endpoint_address_target_name: Name of the endpoint address target.
  • If the endpoints belong to a service, all labels of the role: service discovery are attached.
  • For all targets backed by a pod, all labels of the role: pod discovery are attached.

ingress

The ingress role discovers a target for each path of each ingress. This is generally useful for blackbox monitoring of an ingress. The address will be set to the host specified in the ingress spec.

可用的元标签：

  • __meta_kubernetes_namespace：入口对象的名称空间。
  • __meta_kubernetes_ingress_name：入口对象的名称。
  • __meta_kubernetes_ingress_label_<labelname>：来自入口对象的每个标签。
  • __meta_kubernetes_ingress_labelpresent_<labelname>：true用于来自入口对象的每个标签。
  • __meta_kubernetes_ingress_annotation_<annotationname>：来自入口对象的每个注释。
  • __meta_kubernetes_ingress_annotationpresent_<annotationname>：true用于来自入口对象的每个注释。
  • __meta_kubernetes_ingress_scheme：https如果设置了TLS配置，则为入口的协议方案。默认为http。
  • __meta_kubernetes_ingress_path：来自入口规范的路径。默认为/。

请参阅以下有关Kubernetes发现的配置选项：

# The information to access the Kubernetes API.

# The API server addresses. If left empty, Prometheus is assumed to run inside
# of the cluster and will discover API servers automatically and use the pod's
# CA certificate and bearer token file at /var/run/secrets/kubernetes.io/serviceaccount/.
[ api_server: <host> ]

# The Kubernetes role of entities that should be discovered.
role: <role>

# Optional authentication information used to authenticate to the API server.
# Note that `basic_auth`, `bearer_token` and `bearer_token_file` options are
# mutually exclusive.
# password and password_file are mutually exclusive.

# Optional HTTP basic authentication information.
basic_auth:
  [ username: <string> ]
  [ password: <secret> ]
  [ password_file: <string> ]

# Optional bearer token authentication information.
[ bearer_token: <secret> ]

# Optional bearer token file authentication information.
[ bearer_token_file: <filename> ]

# Optional proxy URL.
[ proxy_url: <string> ]

# TLS configuration.
tls_config:
  [ <tls_config> ]

# Optional namespace discovery. If omitted, all namespaces are used.
namespaces:
  names:
    [ - <string> ]

 

凡<role>必须是endpoints，service，pod，node，或 ingress。

有关 为Kubernetes配置Prometheus的详细示例，请参见此示例Prometheus配置文件。

您可能希望查看第三方Prometheus Operator，它可以自动在Kubernetes上设置Prometheus。

<marathon_sd_config>

Marathon SD配置允许使用Marathon REST API 检索刮擦目标 。Prometheus将定期检查REST端点是否有当前正在运行的任务，并为每个至少具有一个正常任务的应用程序创建目标组。

重新标记期间，目标上可以使用以下元标记：

  • __meta_marathon_app：应用程序的名称（斜杠由破折号代替）
  • __meta_marathon_image：使用的Docker映像的名称（如果可用）
  • __meta_marathon_task：Mesos任务的ID
  • __meta_marathon_app_label_<labelname>：附加到应用程序的所有马拉松标签
  • __meta_marathon_port_definition_label_<labelname>：端口定义标签
  • __meta_marathon_port_mapping_label_<labelname>：端口映射标签
  • __meta_marathon_port_index：端口索引号（例如1为PORT1）

请参阅以下有关Marathon发现的配置选项：

# List of URLs to be used to contact Marathon servers.
# You need to provide at least one server URL.
servers:
  - <string>

# Polling interval
[ refresh_interval: <duration> | default = 30s ]

# Optional authentication information for token-based authentication
# https://docs.mesosphere.com/1.11/security/ent/iam-api/#passing-an-authentication-token
# It is mutually exclusive with `auth_token_file` and other authentication mechanisms.
[ auth_token: <secret> ]

# Optional authentication information for token-based authentication
# https://docs.mesosphere.com/1.11/security/ent/iam-api/#passing-an-authentication-token
# It is mutually exclusive with `auth_token` and other authentication mechanisms.
[ auth_token_file: <filename> ]

# Sets the `Authorization` header on every request with the
# configured username and password.
# This is mutually exclusive with other authentication mechanisms.
# password and password_file are mutually exclusive.
basic_auth:
  [ username: <string> ]
  [ password: <string> ]
  [ password_file: <string> ]

# Sets the `Authorization` header on every request with
# the configured bearer token. It is mutually exclusive with `bearer_token_file` and other authentication mechanisms.
# NOTE: The current version of DC/OS marathon (v1.11.0) does not support standard Bearer token authentication. Use `auth_token` instead.
[ bearer_token: <string> ]

# Sets the `Authorization` header on every request with the bearer token
# read from the configured file. It is mutually exclusive with `bearer_token` and other authentication mechanisms.
# NOTE: The current version of DC/OS marathon (v1.11.0) does not support standard Bearer token authentication. Use `auth_token_file` instead.
[ bearer_token_file: /path/to/bearer/token/file ]

# TLS configuration for connecting to marathon servers
tls_config:
  [ <tls_config> ]

# Optional proxy URL.
[ proxy_url: <string> ]

 

默认情况下，Prometheus将刮除Marathon中列出的每个应用。如果并非所有服务都提供Prometheus指标，则可以使用Marathon标签和Prometheus重新标签来控制实际上将被擦除的实例。有关 如何设置Marathon应用程序和Prometheus配置的实际示例，请参阅Prometheus marathon-sd配置文件。

默认情况下，所有应用程序都将在Prometheus（配置文件中指定的一项）中显示为单个作业，也可以使用重新标记进行更改。

<nerve_sd_config>

Nerve SD配置允许从AirBnB的Nerve中检索刮擦目标，这些目标存储在 Zookeeper中。

重新标记期间，目标上可以使用以下元标记：

  • __meta_nerve_path：Zookeeper中端点节点的完整路径
  • __meta_nerve_endpoint_host：端点的主机
  • __meta_nerve_endpoint_port：端点的端口
  • __meta_nerve_endpoint_name：端点名称
# The Zookeeper servers.
servers:
  - <host>
# Paths can point to a single service, or the root of a tree of services.
paths:
  - <string>
[ timeout: <duration> | default = 10s ]

<serverset_sd_config>

Serverset SD配置允许从存储在Zookeeper中的Serverset检索抓取目标。服务器集通常由Finagle和 Aurora使用。

重新标记期间，以下meta标签可用于目标：

  • __meta_serverset_path：Zookeeper中服务器集成员节点的完整路径
  • __meta_serverset_endpoint_host：默认端点的主机
  • __meta_serverset_endpoint_port：默认端点的端口
  • __meta_serverset_endpoint_host_<endpoint>：给定端点的主机
  • __meta_serverset_endpoint_port_<endpoint>：给定端点的端口
  • __meta_serverset_shard：成员的分片号
  • __meta_serverset_status：成员的状态
# The Zookeeper servers.
servers:
  - <host>
# Paths can point to a single serverset, or the root of a tree of serversets.
paths:
  - <string>
[ timeout: <duration> | default = 10s ]

 

Serverset数据必须为JSON格式，当前不支持Thrift格式。

<triton_sd_config>

Triton SD配置允许从Container Monitor 发现端点检索刮取目标。

重新标记期间，以下meta标签可用于目标：

  • __meta_triton_groups：属于目标的组列表，由逗号分隔
  • __meta_triton_machine_alias：目标容器的别名
  • __meta_triton_machine_brand：目标容器的品牌
  • __meta_triton_machine_id：目标容器的UUID
  • __meta_triton_machine_image：目标容器的图像类型
  • __meta_triton_server_id：目标容器的服务器UUID
# The information to access the Triton discovery API.

# The account to use for discovering new target containers.
account: <string>

# The DNS suffix which should be applied to target containers.
dns_suffix: <string>

# The Triton discovery endpoint (e.g. 'cmon.us-east-3b.triton.zone'). This is
# often the same value as dns_suffix.
endpoint: <string>

# A list of groups for which targets are retrieved. If omitted, all containers
# available to the requesting account are scraped.
groups:
  [ - <string> ... ]

# The port to use for discovery and metric scraping.
[ port: <int> | default = 9163 ]

# The interval which should be used for refreshing target containers.
[ refresh_interval: <duration> | default = 60s ]

# The Triton discovery API version.
[ version: <int> | default = 1 ]

# TLS configuration.
tls_config:
  [ <tls_config> ]

 

<static_config>

A static_config允许指定目标列表和目标的通用标签集。这是在抓取配置中指定静态目标的规范方法。

# The targets specified by the static config.
targets:
  [ - '<host>' ]

# Labels assigned to all metrics scraped from the targets.
labels:
  [ <labelname>: <labelvalue> ... ]

 

<relabel_config>

重新标记是一种强大的工具，可以在刮擦目标之前动态重写目标的标签集。每个刮擦配置可以配置多个重新标记步骤。它们按照在配置文件中出现的顺序应用于每个目标的标签集。

最初，除了配置的每个目标标签外，目标的job 标签还设置为job_name相应的scrape配置的值。该__address__标签被设定为<host>:<port>目标的地址。重新标记后，如果在重新标记过程中未设置标签，则默认将instance标签设置为值__address__。的__scheme__和__metrics_path__标签分别被设定为目标的方案和度量路径。该__param_<name> 标签设置称为国内首家通过URL参数的值<name>。

__meta_在重新贴标签阶段，可能会加上其他带有前缀的标签。它们由提供目标的服务发现机制设置，并且在机制之间有所不同。

标签开始__会从标签集中移除目标重新标记完成后。

如果重新标记步骤仅需要临时存储标签值（作为后续重新标记步骤的输入），请使用__tmp标签名称前缀。保证该前缀不会被Prometheus自己使用。

# The source labels select values from existing labels. Their content is concatenated
# using the configured separator and matched against the configured regular expression
# for the replace, keep, and drop actions.
[ source_labels: '[' <labelname> [, ...] ']' ]

# Separator placed between concatenated source label values.
[ separator: <string> | default = ; ]

# Label to which the resulting value is written in a replace action.
# It is mandatory for replace actions. Regex capture groups are available.
[ target_label: <labelname> ]

# Regular expression against which the extracted value is matched.
[ regex: <regex> | default = (.*) ]

# Modulus to take of the hash of the source label values.
[ modulus: <uint64> ]

# Replacement value against which a regex replace is performed if the
# regular expression matches. Regex capture groups are available.
[ replacement: <string> | default = $1 ]

# Action to perform based on regex matching.
[ action: <relabel_action> | default = replace ]

 

<regex>是任何有效的 RE2正则表达式。这是必需的replace，keep，drop，labelmap，labeldrop和labelkeep行动。正则表达式固定在两端。要取消固定正则表达式，请使用.*<regex>.*。

<relabel_action> 确定要采取的重新标记操作：

  • replace：regex与串联的匹配source_labels。然后，设置 target_label于replacement与匹配组的引用（${1}，${2}，...）中replacement可以通过值取代。如果regex 不匹配，则不进行替换。
  • keep：删除regex与串联不匹配的目标source_labels。
  • drop：删除regex与串联的目标匹配的目标source_labels。
  • hashmod：设置target_label为的modulus哈希值的source_labels。
  • labelmap：regex与所有标签名称匹配。然后匹配标签的值复制到由给定的标签名称replacement与匹配组的参考（${1}，${2}，...）在replacement由他们的价值取代。
  • labeldrop：regex与所有标签名称匹配。任何匹配的标签将从标签集中删除。
  • labelkeep：regex与所有标签名称匹配。任何不匹配的标签都将从标签集中删除。

必须注意labeldrop并labelkeep确保一旦删除标签，度量标准仍会被唯一地标记。

<metric_relabel_configs>

进食前的最后一步是对样品进行公制重新标记。它具有与目标重新标记相同的配置格式和操作。指标重新标记不适用于自动生成的时间序列，例如up。

这样做的一种用途是将过于昂贵而无法摄取的时间序列列入黑名单。

<alert_relabel_configs>

警报重新标记将应用于警报，然后再将其发送到Alertmanager。它具有与目标重新标记相同的配置格式和操作。在外部标签之后应用警报重新标签。

一种用途是确保具有不同外部标签的HA对Prometheus服务器对发送相同的警报。

<alertmanager_config>

本alertmanager_config节指定Prometheus服务器向其发送警报的Alertmanager实例。它还提供了用于配置如何与这些Alertmanager通信的参数。

警报管理器可以通过static_configs参数静态配置，也可以使用受支持的服务发现机制之一动态发现。

另外，relabel_configs允许从发现的实体中选择Alertmanagers，并提供对使用的API路径的高级修改，该路径通过__alerts_path__标签公开。

# Per-target Alertmanager timeout when pushing alerts.
[ timeout: <duration> | default = 10s ]

# The api version of Alertmanager.
[ api_version: <version> | default = v1 ]

# Prefix for the HTTP path alerts are pushed to.
[ path_prefix: <path> | default = / ]

# Configures the protocol scheme used for requests.
[ scheme: <scheme> | default = http ]

# Sets the `Authorization` header on every request with the
# configured username and password.
# password and password_file are mutually exclusive.
basic_auth:
  [ username: <string> ]
  [ password: <string> ]
  [ password_file: <string> ]

# Sets the `Authorization` header on every request with
# the configured bearer token. It is mutually exclusive with `bearer_token_file`.
[ bearer_token: <string> ]

# Sets the `Authorization` header on every request with the bearer token
# read from the configured file. It is mutually exclusive with `bearer_token`.
[ bearer_token_file: /path/to/bearer/token/file ]

# Configures the scrape request's TLS settings.
tls_config:
  [ <tls_config> ]

# Optional proxy URL.
[ proxy_url: <string> ]

# List of Azure service discovery configurations.
azure_sd_configs:
  [ - <azure_sd_config> ... ]

# List of Consul service discovery configurations.
consul_sd_configs:
  [ - <consul_sd_config> ... ]

# List of DNS service discovery configurations.
dns_sd_configs:
  [ - <dns_sd_config> ... ]

# List of EC2 service discovery configurations.
ec2_sd_configs:
  [ - <ec2_sd_config> ... ]

# List of file service discovery configurations.
file_sd_configs:
  [ - <file_sd_config> ... ]

# List of GCE service discovery configurations.
gce_sd_configs:
  [ - <gce_sd_config> ... ]

# List of Kubernetes service discovery configurations.
kubernetes_sd_configs:
  [ - <kubernetes_sd_config> ... ]

# List of Marathon service discovery configurations.
marathon_sd_configs:
  [ - <marathon_sd_config> ... ]

# List of AirBnB's Nerve service discovery configurations.
nerve_sd_configs:
  [ - <nerve_sd_config> ... ]

# List of Zookeeper Serverset service discovery configurations.
serverset_sd_configs:
  [ - <serverset_sd_config> ... ]

# List of Triton service discovery configurations.
triton_sd_configs:
  [ - <triton_sd_config> ... ]

# List of labeled statically configured Alertmanagers.
static_configs:
  [ - <static_config> ... ]

# List of Alertmanager relabel configurations.
relabel_configs:
  [ - <relabel_config> ... ]

 

<remote_write>

write_relabel_configs将重新标签应用于样本，然后再将其发送到远程端点。在外部标签之后应用写重新标记。这可以用来限制发送哪些样本。

有一个小样演示如何使用此功能。

# The URL of the endpoint to send samples to.
url: <string>

# Timeout for requests to the remote write endpoint.
[ remote_timeout: <duration> | default = 30s ]

# List of remote write relabel configurations.
write_relabel_configs:
  [ - <relabel_config> ... ]

# Sets the `Authorization` header on every remote write request with the
# configured username and password.
# password and password_file are mutually exclusive.
basic_auth:
  [ username: <string> ]
  [ password: <string> ]
  [ password_file: <string> ]

# Sets the `Authorization` header on every remote write request with
# the configured bearer token. It is mutually exclusive with `bearer_token_file`.
[ bearer_token: <string> ]

# Sets the `Authorization` header on every remote write request with the bearer token
# read from the configured file. It is mutually exclusive with `bearer_token`.
[ bearer_token_file: /path/to/bearer/token/file ]

# Configures the remote write request's TLS settings.
tls_config:
  [ <tls_config> ]

# Optional proxy URL.
[ proxy_url: <string> ]

# Configures the queue used to write to remote storage.
queue_config:
  # Number of samples to buffer per shard before we block reading of more
  # samples from the WAL. It is recommended to have enough capacity in each
  # shard to buffer several requests to keep throughput up while processing
  # occasional slow remote requests.
  [ capacity: <int> | default = 500 ]
  # Maximum number of shards, i.e. amount of concurrency.
  [ max_shards: <int> | default = 1000 ]
  # Minimum number of shards, i.e. amount of concurrency.
  [ min_shards: <int> | default = 1 ]
  # Maximum number of samples per send.
  [ max_samples_per_send: <int> | default = 100]
  # Maximum time a sample will wait in buffer.
  [ batch_send_deadline: <duration> | default = 5s ]
  # Initial retry delay. Gets doubled for every retry.
  [ min_backoff: <duration> | default = 30ms ]
  # Maximum retry delay.
  [ max_backoff: <duration> | default = 100ms ]

 

有 此功能的集成列表 。

<remote_read>

# The URL of the endpoint to query from.
url: <string>

# An optional list of equality matchers which have to be
# present in a selector to query the remote read endpoint.
required_matchers:
  [ <labelname>: <labelvalue> ... ]

# Timeout for requests to the remote read endpoint.
[ remote_timeout: <duration> | default = 1m ]

# Whether reads should be made for queries for time ranges that
# the local storage should have complete data for.
[ read_recent: <boolean> | default = false ]

# Sets the `Authorization` header on every remote read request with the
# configured username and password.
# password and password_file are mutually exclusive.
basic_auth:
  [ username: <string> ]
  [ password: <string> ]
  [ password_file: <string> ]

# Sets the `Authorization` header on every remote read request with
# the configured bearer token. It is mutually exclusive with `bearer_token_file`.
[ bearer_token: <string> ]

# Sets the `Authorization` header on every remote read request with the bearer token
# read from the configured file. It is mutually exclusive with `bearer_token`.
[ bearer_token_file: /path/to/bearer/token/file ]

# Configures the remote read request's TLS settings.
tls_config:
  [ <tls_config> ]

# Optional proxy URL.
[ proxy_url: <string> ]

 

有 此功能的集成列表 。

定义记录规则

配置规则

Prometheus支持两种类型的规则，可以对其进行配置，然后定期进行评估：记录规则和警报规则。要在Prometheus中包括规则，请创建一个包含必要规则语句的文件，并让Prometheus通过Prometheus配置中的rule_files字段加载该文件。规则文件使用YAML。

可以通过发送SIGHUP到Prometheus进程在运行时重新加载规则文件。仅当所有规则文件的格式正确时，才应用更改。

语法检查规则

要在不启动Prometheus服务器的情况下快速检查规则文件在语法上是否正确，请安装并运行Prometheus的promtool命令行实用工具：

go get github.com/prometheus/prometheus/cmd/promtool
promtool check rules /path/to/example.rules.yml

当该文件在语法上有效时，检查器将已解析的规则的文本表示形式打印到标准输出，然后以0返回状态退出。

如果存在任何语法错误或无效的输入参数，则会将错误消息打印为标准错误，并以1返回状态退出。

记录规则

记录规则使您可以预先计算经常需要或计算量大的表达式，并将其结果保存为一组新的时间序列。因此，查询预计算结果通常比每次需要原始表达式都要快得多。这对于仪表板特别有用，仪表板每次刷新时都需要重复查询相同的表达式。

记录和警报规则存在于规则组中。组中的规则以规则的时间间隔顺序运行。

规则文件的语法为：

groups:
  [ - <rule_group> ]

一个简单的示例规则文件将是：

groups:
  - name: example
    rules:
    - record: job:http_inprogress_requests:sum
      expr: sum(http_inprogress_requests) by (job)

<rule_group>

# The name of the group. Must be unique within a file.
name: <string>

# How often rules in the group are evaluated.
[ interval: <duration> | default = global.evaluation_interval ]

rules:
  [ - <rule> ... ]

<rule>

记录规则的语法为：

# The name of the time series to output to. Must be a valid metric name.
record: <string>

# The PromQL expression to evaluate. Every evaluation cycle this is
# evaluated at the current time, and the result recorded as a new set of
# time series with the metric name as given by 'record'.
expr: <string>

# Labels to add or overwrite before storing the result.
labels:
  [ <labelname>: <labelvalue> ]

警报规则的语法为：

# The name of the alert. Must be a valid metric name.
alert: <string>

# The PromQL expression to evaluate. Every evaluation cycle this is
# evaluated at the current time, and all resultant time series become
# pending/firing alerts.
expr: <string>

# Alerts are considered firing once they have been returned for this long.
# Alerts which have not yet fired for long enough are considered pending.
[ for: <duration> | default = 0s ]

# Labels to add or overwrite for each alert.
labels:
  [ <labelname>: <tmpl_string> ]

# Annotations to add to each alert.
annotations:
  [ <labelname>: <tmpl_string> ]

警报规则

警报规则使您可以基于Prometheus表达式语言表达式定义警报条件，并将有关触发警报的通知发送到外部服务。只要警报表达式在给定的时间点生成一个或多个矢量元素，警报就被视为这些元素的标签集处于活动状态。

定义警报规则

警报规则在Prometheus中的配置方式与记录规则相同。

带有警报的示例规则文件为：

groups:
- name: example
  rules:
  - alert: HighRequestLatency
    expr: job:request_latency_seconds:mean5m{job="myjob"} > 0.5
    for: 10m
    labels:
      severity: page
    annotations:
      summary: High request latency

可选for子句使Prometheus在第一次遇到新的表达式输出矢量元素与将警报计为对此元素的触发进行计数之间等待一段时间。在这种情况下，Prometheus将在每次发出警报10分钟之前检查警报是否继续处于活动状态。处于活动状态但尚未触发的元素处于挂起状态。

该labels子句允许指定一组附加到警报的附加标签。任何现有的冲突标签都将被覆盖。标签值可以模板化。

该annotations子句指定了一组信息标签，可用于存储更长的附加信息，例如警报描述或运行手册链接。注释值可以模板化。

模板化

标签和注释值可以使用控制台模板进行模板化。该$labels 变量保存警报实例的标签键/值对。可以通过$externalLabels变量访问已组态的外部标签。该 $value变量保存警报实例的评估值。

# To insert a firing element's label values:
{{ $labels.<labelname> }}
# To insert the numeric expression value of the firing element:
{{ $value }}

例子：

groups:
- name: example
  rules:

  # Alert for any instance that is unreachable for >5 minutes.
  - alert: InstanceDown
    expr: up == 0
    for: 5m
    labels:
      severity: page
    annotations:
      summary: "Instance {{ $labels.instance }} down"
      description: "{{ $labels.instance }} of job {{ $labels.job }} has been down for more than 5 minutes."

  # Alert for any instance that has a median request latency >1s.
  - alert: APIHighRequestLatency
    expr: api_http_request_latencies_second{quantile="0.5"} > 1
    for: 10m
    annotations:
      summary: "High request latency on {{ $labels.instance }}"
      description: "{{ $labels.instance }} has a median request latency above 1s (current value: {{ $value }}s)"

在运行时检查警报

要手动检查哪些警报处于活动状态（挂起或触发），请导航到Prometheus实例的“警报”选项卡。这将向您显示当前每个定义的警报均处于活动状态的确切标签集。

对于未决和触发警报，Prometheus还存储表格的合成时间序列ALERTS{alertname="<alert name>", alertstate="pending|firing", <additional alert labels>}。1只要警报处于指示的活动（挂起或触发）状态，样本值就设置为，如果不再如此，则将系列标记为陈旧。

发送警报通知

Prometheus的警报规则擅长于确定当前已发生的问题，但它们并不是完整的通知解决方案。在简单的警报定义之上，还需要另一层来添加摘要，通知速率限制，静默和警报依赖性。在Prometheus的生态系统中， Alertmanager担当了这个角色。因此，Prometheus可以配置为定期将有关警报状态的信息发送到Alertmanager实例，该实例随后负责调度正确的通知。
可以将Prometheus 配置为通过其服务发现集成自动发现可用的Alertmanager实例。

范本范例

Prometheus支持在警报的注释和标签以及服务的控制台页面中进行模板化。模板具有对本地数据库运行查询，遍历数据，使用条件语句，格式化数据等功能。Prometheus模板语言基于Go模板系统。

简单的警报字段模板

alert: InstanceDown
expr: up == 0
for: 5m
labels:
  severity: page
annotations:
  summary: "Instance {{$labels.instance}} down"
  description: "{{$labels.instance}} of job {{$labels.job}} has been down for more than 5 minutes."

警报字段模板将在每次触发的每个规则迭代期间执行，因此请保持所有查询和模板的轻量级。如果您需要更复杂的警报模板，建议改为链接到控制台。

简单迭代

这将显示实例列表以及它们是否启动：

{{ range query "up" }}
  {{ .Labels.instance }} {{ .Value }}
{{ end }}

特殊.变量包含每次循环迭代的当前样本值。

显示一个值

{{ with query "some_metric{instance='someinstance'}" }}
  {{ . | first | value | humanize }}
{{ end }}

Go和Go的模板语言都是强类型的，因此必须检查返回的样本以避免执行错误。例如，如果刮刮或规则评估尚未运行，或者主机已关闭，则可能发生这种情况。

包含的prom_query_drilldown模板可以处理此问题，允许格式化结果并链接到表达式浏览器。

使用控制台URL参数

{{ with printf "node_memory_MemTotal{job='node',instance='%s'}" .Params.instance | query }}
  {{ . | first | value | humanize1024 }}B
{{ end }}

如果按进行访问console.html?instance=hostname，.Params.instance将求值为hostname。

高级迭代

<table>
{{ range printf "node_network_receive_bytes{job='node',instance='%s',device!='lo'}" .Params.instance | query | sortByLabel "device"}}
  <tr><th colspan=2>{{ .Labels.device }}</th></tr>
  <tr>
    <td>Received</td>
    <td>{{ with printf "rate(node_network_receive_bytes{job='node',instance='%s',device='%s'}[5m])" .Labels.instance .Labels.device | query }}{{ . | first | value | humanize }}B/s{{end}}</td>
  </tr>
  <tr>
    <td>Transmitted</td>
    <td>{{ with printf "rate(node_network_transmit_bytes{job='node',instance='%s',device='%s'}[5m])" .Labels.instance .Labels.device | query }}{{ . | first | value | humanize }}B/s{{end}}</td>
  </tr>{{ end }}
</table>

在这里，我们遍历所有网络设备并显示每个网络设备的网络流量。

由于该range操作未指定变量，.Params.instance因此在循环内部不可用，因为.现在循环变量不可用。

定义可重用模板

Prometheus支持定义可重复使用的模板。与控制台库支持结合使用时，此功能特别强大 ，允许在各个控制台之间共享模板。

{{/* Define the template */}}
{{define "myTemplate"}}
  do something
{{end}}

{{/* Use the template */}}
{{template "myTemplate"}}

模板仅限于一个参数。该args函数可用于包装多个参数。

{{define "myMultiArgTemplate"}}
  First argument: {{.arg0}}
  Second argument: {{.arg1}}
{{end}}
{{template "myMultiArgTemplate" (args 1 2)}}

模板参考

Prometheus支持在警报的注释和标签以及服务的控制台页面中进行模板化。模板具有对本地数据库运行查询，遍历数据，使用条件语句，格式化数据等功能。Prometheus模板语言基于Go模板系统。

数据结构

处理时间序列数据的主要数据结构是样本，定义为：

type sample struct {
        Labels map[string]string
        Value  float64
}

样品的度量名称被编码在地图的特殊__name__标签中Labels。

[]sample 表示样本列表。

interface{} Go中的代码类似于C中的void指针。

功能

除了Go模板提供的默认功能外，Prometheus还提供了一些功能，可简化模板中查询结果的处理。

如果在管道中使用函数，则管道值将作为最后一个参数传递。

查询

名称争论退货笔记
询问 请求参数 []样品 查询数据库，不支持返回范围向量。
第一 []样品 样品 相当于 index a 0
标签 标签，样品 串 相当于 index sample.Labels label
值 样品 float64 相当于 sample.Value
sortByLabel 标签，[]样本 []样品 按给定标签对样本进行排序。很稳定。

first，label以及value旨在使查询结果中的管道易于使用。

号码

名称争论退货笔记
人性化 数 串 使用度量前缀将数字转换为更易读的格式。
人性化1024 数 串 类似于humanize，但是使用1024作为基础，而不是1000。
人性化持续时间 数 串 将持续时间（以秒为单位）转换为更具可读性的格式。
人性化百分比 数 串 将比率值转换为100的分数。
人性化时间戳 数 串 将以秒为单位的Unix时间戳转换为更具可读性的格式。

人性化功能旨在产生合理的输出以供人类使用，并且不能保证在Prometheus版本之间返回相同的结果。

弦乐

名称争论退货笔记
标题 串 串 strings.Title，大写每个单词的第一个字符。
上层 串 串 strings.ToUpper，将所有字符转换为大写。
降低 串 串 strings.ToLower，将所有字符转换为小写。
比赛 图案，文字 布尔值 regexp.MatchString测试未锚定的 regexp匹配。
reReplaceAll 图案替换文字 串 Regexp.ReplaceAllString Regexp替换，未锚定。
graphLink expr 串 返回表达式浏览器中该表达式的图形视图的路径。
tableLink expr 串 在表达式浏览器中返回表达式的表格视图（“控制台”）的路径。

其他

名称争论退货笔记
args []接口{} map [string] interface {} 这会将对象列表转换为具有键arg0，arg1等的映射。这旨在允许将多个参数传递给模板。
汤普 字符串，[]界面{} 没有 类似于内置template，但允许使用非文字作为模板名称。注意，假定结果是安全的，并且不会自动转义。仅在控制台中可用。
安全HTML 串 串 将字符串标记为HTML，不需要自动转义。

模板类型差异

每种类型的模板都提供了可用于参数化模板的不同信息，并且还有一些其他区别。

警报字段模板

.Value，.Labels和分别ExternalLabels包含警报值，警报标签和全局配置的外部标签。为了方便起见$value，它们也显示为$labels，和$externalLabels变量。

控制台模板

控制台在上公开/consoles/，并从-web.console.templates标志所指向的目录中获取。

控制台模板使用html / template呈现 ，该模板提供自动转义。要绕过自动转义，请使用safe*功能。

URL参数可在中作为映射使用.Params。要访问具有相同名称的多个URL参数，.RawParams是每个参数的列表值的映射。URL路径可在中使用.Path，但/consoles/ 前缀除外。全局配置的外部标签为 .ExternalLabels。还有所有四个惯用变量： $rawParams，$params，$path，和$externalLabels。

控制台还可以访问标记所指向的目录{{define "templateName"}}...{{end}}中的*.lib文件中定义的所有模板-web.console.libraries。由于这是共享的名称空间，因此请注意避免与其他用户发生冲突。模板名称以prom，_prom和开头， __保留给Prometheus使用，上面列出的功能也是如此。

规则的单元测试

您可以promtool用来测试您的规则。

# For a single test file.
./promtool test rules test.yml

# If you have multiple test files, say test1.yml,test2.yml,test2.yml
./promtool test rules test1.yml test2.yml test3.yml

 

测试文件格式

# This is a list of rule files to consider for testing. Globs are supported.
rule_files:
  [ - <file_name> ]

# optional, default = 1m
evaluation_interval: <duration>

# The order in which group names are listed below will be the order of evaluation of
# rule groups (at a given evaluation time). The order is guaranteed only for the groups mentioned below.
# All the groups need not be mentioned below.
group_eval_order:
  [ - <group_name> ]

# All the tests are listed here.
tests:
  [ - <test_group> ]

 

<test_group>

# Series data
interval: <duration>
input_series:
  [ - <series> ]

# Unit tests for the above data.

# Unit tests for alerting rules. We consider the alerting rules from the input file.
alert_rule_test:
  [ - <alert_test_case> ]

# Unit tests for PromQL expressions.
promql_expr_test:
  [ - <promql_test_case> ]

# External labels accessible to the alert template.
external_labels:
  [ <labelname>: <string> ... ]

 

<series>

# This follows the usual series notation '<metric name>{<label name>=<label value>, ...}'
# Examples:
#      series_name{label1="value1", label2="value2"}
#      go_goroutines{job="prometheus", instance="localhost:9090"}
series: <string>

# This uses expanding notation.
# Expanding notation:
#     'a+bxc' becomes 'a a+b a+(2*b) a+(3*b) … a+(c*b)'
#     'a-bxc' becomes 'a a-b a-(2*b) a-(3*b) … a-(c*b)'
# Examples:
#     1. '-2+4x3' becomes '-2 2 6 10'
#     2. ' 1-2x4' becomes '1 -1 -3 -5 -7'
values: <string>

 

<alert_test_case>

Prometheus允许您为不同的警报规则使用相同的警报名称。因此，在此单元测试中，您必须在单个警报名称下列出警报名称的所有触发警报的并集<alert_test_case>。

# The time elapsed from time=0s when the alerts have to be checked.
eval_time: <duration>

# Name of the alert to be tested.
alertname: <string>

# List of expected alerts which are firing under the given alertname at
# given evaluation time. If you want to test if an alerting rule should
# not be firing, then you can mention the above fields and leave 'exp_alerts' empty.
exp_alerts:
  [ - <alert> ]

 

<alert>

# These are the expanded labels and annotations of the expected alert.
# Note: labels also include the labels of the sample associated with the
# alert (same as what you see in `/alerts`, without series `__name__` and `alertname`)
exp_labels:
  [ <labelname>: <string> ]
exp_annotations:
  [ <labelname>: <string> ]

 

<promql_test_case>

# Expression to evaluate
expr: <string>

# The time elapsed from time=0s when the expression has to be evaluated.
eval_time: <duration>

# Expected samples at the given evaluation time.
exp_samples:
  [ - <sample> ]

 

<sample>

# Labels of the sample in usual series notation '<metric name>{<label name>=<label value>, ...}'
# Examples:
#      series_name{label1="value1", label2="value2"}
#      go_goroutines{job="prometheus", instance="localhost:9090"}
labels: <string>

# The expected value of the PromQL expression.
value: <number>

 

例

这是通过测试的单元测试的示例输入文件。test.yml是遵循上述语法并alerts.yml包含警报规则的测试文件。

随着alerts.yml在同一目录下，运行./promtool test rules test.yml。

test.yml

# This is the main input for unit testing.
# Only this file is passed as command line argument.

rule_files:
    - alerts.yml

evaluation_interval: 1m

tests:
    # Test 1.
    - interval: 1m
      # Series data.
      input_series:
          - series: 'up{job="prometheus", instance="localhost:9090"}'
            values: '0 0 0 0 0 0 0 0 0 0 0 0 0 0 0'
          - series: 'up{job="node_exporter", instance="localhost:9100"}'
            values: '1+0x6 0 0 0 0 0 0 0 0' # 1 1 1 1 1 1 1 0 0 0 0 0 0 0 0
          - series: 'go_goroutines{job="prometheus", instance="localhost:9090"}'
            values: '10+10x2 30+20x5' # 10 20 30 30 50 70 90 110 130
          - series: 'go_goroutines{job="node_exporter", instance="localhost:9100"}'
            values: '10+10x7 10+30x4' # 10 20 30 40 50 60 70 80 10 40 70 100 130

      # Unit test for alerting rules.
      alert_rule_test:
          # Unit test 1.
          - eval_time: 10m
            alertname: InstanceDown
            exp_alerts:
                # Alert 1.
                - exp_labels:
                      severity: page
                      instance: localhost:9090
                      job: prometheus
                  exp_annotations:
                      summary: "Instance localhost:9090 down"
                      description: "localhost:9090 of job prometheus has been down for more than 5 minutes."
      # Unit tests for promql expressions.
      promql_expr_test:
          # Unit test 1.
          - expr: go_goroutines > 5
            eval_time: 4m
            exp_samples:
                # Sample 1.
                - labels: 'go_goroutines{job="prometheus",instance="localhost:9090"}'
                  value: 50
                # Sample 2.
                - labels: 'go_goroutines{job="node_exporter",instance="localhost:9100"}'
                  value: 50

 

alerts.yml

# This is the rules file.

groups:
- name: example
  rules:

  - alert: InstanceDown
    expr: up == 0
    for: 5m
    labels:
        severity: page
    annotations:
        summary: "Instance {{ $labels.instance }} down"
        description: "{{ $labels.instance }} of job {{ $labels.job }} has been down for more than 5 minutes."

  - alert: AnotherInstanceDown
    expr: up == 0
    for: 10m
    labels:
        severity: page
    annotations:
        summary: "Instance {{ $labels.instance }} down"
        description: "{{ $labels.instance }} of job {{ $labels.job }} has been down for more than 5 minutes." 

查询普罗米修斯

Prometheus提供了一种称为PromQL（Prometheus查询语言）的功能查询语言，使用户可以实时选择和汇总时间序列数据。表达式的结果可以显示为图形，可以在Prometheus的表达式浏览器中显示为表格数据，也可以由外部系统通过HTTP API使用。

例子

本文档仅供参考。为了学习，从几个示例开始可能会更容易。

表达语言数据类型

在Prometheus的表达语言中，一个表达式或子表达式可以计算为以下四种类型之一：

  • 即时向量 -一组时间序列，每个时间序列包含一个样本，所有样本共享相同的时间戳
  • 范围向量 -一组时间序列，其中包含每个时间序列随时间变化的一系列数据点
  • 标量 -一个简单的数字浮点值
  • String-一个简单的字符串值；目前未使用

根据用例（例如，在绘制图形或显示表达式的输出时），由于用户指定的表达式的结果，其中只有某些类型是合法的。例如，返回即时向量的表达式是唯一可以直接绘制图形的类型。

文字

字符串文字

可以在单引号，双引号或反引号中将字符串指定为文字。

PromQL遵循与Go相同的转义规则。在单引号或双引号反斜杠开头的转义序列，其可以随后a，b，f， n，r，t，v或\。可使用八进制（来提供特定的字符\nnn）或十六进制（\xnn，\unnnn和\Unnnnnnnn）。

反引号内不会处理任何转义。与Go不同，Prometheus不会在反引号内丢弃换行符。

例：

"this is a string"
'these are unescaped: \n \\ \t'
`these are not unescaped: \n ' " \t`

浮点文字

标量浮点值可以从字面上写为以下形式的数字 [-](digits)[.(digits)]。

-2.43

时间序列选择器

即时向量选择器

即时矢量选择器允许在给定的时间戳（即时）上选择一组时间序列和每个样本的单个采样值：以最简单的形式，仅指定度量名称。这将导致一个即时向量，其中包含具有该度量名称的所有时间序列的元素。

本示例选择所有具有http_requests_total度量标准名称的时间序列：

http_requests_total

通过在花括号（{}）中添加逗号分隔的标签匹配器列表，可以进一步过滤这些时间序列。

本示例仅选择那些具有http_requests_total 度量标准名称的时间序列，同时将其job标签设置为，prometheus并将其 group标签设置为canary：

http_requests_total{job="prometheus",group="canary"}

也可以否定地匹配标签值，或将标签值与正则表达式匹配。存在以下标签匹配运算符：

  • =：选择与提供的字符串完全相同的标签。
  • !=：选择不等于提供的字符串的标签。
  • =~：选择与提供的字符串进行正则表达式匹配的标签。
  • !~：选择不与提供的字符串进行正则表达式匹配的标签。

例如，此选择所有http_requests_total的时间序列staging， testing以及development环境和HTTP比其他方法GET。

http_requests_total{environment=~"staging|testing|development",method!="GET"}

匹配空标签值的标签匹配器还会选择所有根本没有设置特定标签的时间序列。正则表达式匹配完全锚定。同一标签名称可能有多个匹配器。

向量选择器必须指定一个名称或至少一个与空字符串不匹配的标签匹配器。以下表达式是非法的：

{job=~".*"} # Bad!

相反，这些表达式都是有效的，因为它们都具有与空标签值不匹配的选择器。

{job=~".+"}              # Good!
{job=~".*",method="get"} # Good!

通过与内部__name__标签匹配，标签匹配器也可以应用于度量标准名称 。例如，该表达式http_requests_total等效于 {__name__="http_requests_total"}。比其他的匹配器=（!=，=~，!~）也可以使用。以下表达式选择名称以开头的所有度量job:：

{__name__=~"job:.*"}

Prometheus中的所有正则表达式都使用RE2语法。

范围向量选择器

范围向量文字的工作方式与即时向量文字相同，不同之处在于，它们从当前瞬间选择了一定范围的样本。从句法上讲，范围持续时间附加在[]向量选择器末尾的方括号（）中，以指定应为每个结果范围向量元素提取多远的时间值。

持续时间指定为数字，紧随其后的是以下单位之一：

  • s -秒
  • m - 分钟
  • h - 小时
  • d - 天
  • w -周
  • y -年

在此示例中，我们选择所有时间序列在过去5分钟内记录的所有值，这些时间序列的指标名称http_requests_total和job标签设置为prometheus：

http_requests_total{job="prometheus"}[5m]

偏移量修改器

所述offset改性剂可以改变时间为查询中的个别时刻和范围矢量偏移。

例如，以下表达式返回http_requests_total相对于当前查询评估时间的过去5分钟的值 ：

http_requests_total offset 5m

请注意，offset修饰符始终需要立即跟随选择器，即以下内容将是正确的：

sum(http_requests_total{method="GET"} offset 5m) // GOOD.

虽然以下是不正确的：

sum(http_requests_total{method="GET"}) offset 5m // INVALID.

范围向量的工作原理相同。这将返回http_requests_total一周前的5分钟费率 ：

rate(http_requests_total[5m] offset 1w)

子查询

子查询允许您针对给定的范围和分辨率运行即时查询。子查询的结果是范围向量。

句法： <instant_query> '[' <range> ':' [<resolution>] ']' [ offset <duration> ]

  • <resolution>是可选的。默认值为全局评估间隔。

经营者

Prometheus支持许多二进制和聚合运算符。这些在表达式语言运算符页面中进行了详细描述。

功能

Prometheus支持几种对数据进行操作的功能。这些在表达语言功能页面中进行了详细描述。

注释

PromQL支持以开头的行注释#。例：

    # This is a comment

陷阱

陈旧性

运行查询时，将选择采样数据的时间戳，而不依赖于实际的当前时间序列数据。这主要是为了支持诸如聚合（sum，avg等）的情况，其中多个聚合时间序列在时间上不完全一致。由于它们的独立性，Prometheus需要在这些时间戳上为每个相关时间序列分配一个值。只需在此时间戳之前获取最新样本即可。

如果目标刮擦或规则评估不再返回先前存在的时间序列的样本，则该时间序列将被标记为陈旧。如果删除了目标，则其先前返回的时间序列将在不久后标记为陈旧。

如果在某个时间序列标记为陈旧后以采样时间戳评估查询，则该时间序列不会返回任何值。如果随后在该时间序列中摄取了新样本，则它们将照常返回。

如果在采样时间戳记之前5分钟（默认情况下）未找到任何采样，则在该时间点该时间序列将不返回任何值。这实际上意味着，在最新采集的样本早于5分钟或标记为陈旧之后，时间序列将从图表中“消失”。

刮痕中包含时间戳的时间序列将不会标记为陈旧。在这种情况下，仅会应用5分钟的阈值。

避免慢查询和重载

如果查询需要处理大量数据，则对其进行图形化处理可能会超时或使服务器或浏览器超载。因此，在对未知数据构建查询时，请始终开始在Prometheus表达式浏览器的表格视图中构建查询，直到结果集看起来合理为止（最多数百个时间序列，而不是数千个）。仅当您充分过滤或汇总了数据后，才切换到图形模式。如果该表达式仍无法花费很长时间来绘制即席图形，请通过记录规则将其预先记录。

这与Prometheus的查询语言特别相关，在Prometheus的查询语言中，像这样的裸指标名称选择器api_http_requests_total可以扩展到成千上万个带有不同标签的时间序列。还请记住，即使输出只是少量时间序列，在多个时间序列上聚合的表达式也会在服务器上产生负载。这类似于将关系数据库中列的所有值相加会很慢，即使输出值只是一个数字也是如此。

经营者

二元运算符

Prometheus的查询语言支持基本的逻辑和算术运算符。对于两个即时向量之间的运算， 可以修改匹配行为。

算术二进制运算符

Prometheus中存在以下二进制算术运算符：

  • + （加成）
  • - （减法）
  • * （乘法）
  • / （师）
  • % （取模）
  • ^ （幂/幂）

在标量/标量，向量/标量和向量/向量值对之间定义了二进制算术运算符。

在两个标量之间，其行为显而易见：它们求值另一个标量，这是将运算符应用于两个标量操作数的结果。

在瞬时向量和标量之间，将运算符应用于向量中每个数据样本的值。例如，如果时间序列瞬时向量乘以2，则结果是另一个向量，其中原始向量的每个样本值都乘以2。

在两个即时向量之间，将二进制算术运算符应用于左侧向量中的每个条目，并将其 应用于右侧向量中的匹配元素。结果被传播到结果向量中，并且分组标签成为输出标签集。指标名称已删除。在右侧向量中找不到匹配条目的条目不属于结果。

比较二进制运算符

Prometheus中存在以下二进制比较运算符：

  • == （等于）
  • != （不相等）
  • > （比...更棒）
  • < （少于）
  • >= （大于等于）
  • <= （不等）

在标量/标量，向量/标量和向量/向量值对之间定义比较运算符。默认情况下，它们会过滤。可以通过bool在运算符之后提供来修改其行为，该运算符将返回0或1 针对该值而不是进行过滤。

在两个标量之间，bool必须提供修饰符，并且这些运算符将根据比较结果得出另一个标量，其为0（false）或1 （true）。

在瞬时向量和标量之间，将这些运算符应用于向量中每个数据样本的值，并false从结果向量中删除比较结果之间的向量元素。如果bool 提供了修饰符，那么将要放置的向量元素将具有值 0，而将被保留的向量元素将具有value 1。

在两个即时向量之间，这些运算符默认情况下充当过滤器，应用于匹配的条目。表达式不正确或在表达式另一侧找不到匹配项的向量元素将从结果中删除，而其他元素则传播到结果向量中，并且分组标签成为输出标签集。如果bool提供了修饰符，那么将被丢弃的0矢量元素将具有值1，而将被保留的矢量元素将具有值，分组标签再次成为输出标签集。

逻辑/集合二元运算符

这些逻辑/集合二进制运算符仅在即时向量之间定义：

  • and （路口）
  • or （联盟）
  • unless （补充）

vector1 and vector2会产生一个向量，该向量vector1由其元素组成， 其中的元素vector2具有完全匹配的标签集。其他元素被删除。度量标准名称和值从左侧矢量继承。

vector1 or vector2会产生一个向量，其中包含的所有原始元素（标签集+值），vector1并且vector2 其中所有元素在中都没有匹配的标签集vector1。

vector1 unless vector2会产生一个向量，该向量由 vector1没有vector2完全匹配的标签集的元素组成。两个向量中的所有匹配元素都将被删除。

向量匹配

向量之间的运算会尝试在左侧向量中为左侧的每个条目找到匹配的元素。匹配行为有两种基本类型：一对一和多对一/一对多。

一对一向量匹配

一对一地从操作的每一侧找到一对唯一的条目。在默认情况下，这是遵循format的操作vector1 <operator> vector2。如果两个条目具有完全相同的一组标签和相应的值，则它们匹配。的ignoring关键字允许忽略匹配时某些标签，而 on关键字允许减少该组被认为标签来提供的列表中：

<vector expr> <bin-op> ignoring(<label list>) <vector expr>
<vector expr> <bin-op> on(<label list>) <vector expr>

输入示例：

method_code:http_errors:rate5m{method="get", code="500"}  24
method_code:http_errors:rate5m{method="get", code="404"}  30
method_code:http_errors:rate5m{method="put", code="501"}  3
method_code:http_errors:rate5m{method="post", code="500"} 6
method_code:http_errors:rate5m{method="post", code="404"} 21

method:http_requests:rate5m{method="get"}  600
method:http_requests:rate5m{method="del"}  34
method:http_requests:rate5m{method="post"} 120

查询示例：

method_code:http_errors:rate5m{code="500"} / ignoring(code) method:http_requests:rate5m

这将返回一个结果向量，其中包含最近5分钟内对每种方法的状态请求为500的HTTP请求的比例。没有ignoring(code)这些指标，就不会有匹配项，因为指标不会共享同一组标签。用方法的条目put，并del没有匹配，并且在结果不会显示出来：

{method="get"}  0.04            //  24 / 600
{method="post"} 0.05            //   6 / 120

多对一和一对多向量匹配

多对一和一对多匹配是指“一个”侧的每个矢量元素都可以与“许多”侧的多个元素匹配的情况。必须使用group_left或group_right修饰符明确要求此操作，其中左/右确定哪个向量具有更高的基数。

<vector expr> <bin-op> ignoring(<label list>) group_left(<label list>) <vector expr>
<vector expr> <bin-op> ignoring(<label list>) group_right(<label list>) <vector expr>
<vector expr> <bin-op> on(<label list>) group_left(<label list>) <vector expr>
<vector expr> <bin-op> on(<label list>) group_right(<label list>) <vector expr>

组修饰符随附的标签列表包含“一”侧的其他标签，这些标签将包含在结果指标中。对于on标签只能出现在列表之一中。结果向量的每个时间序列都必须是唯一可识别的。

分组修饰符只能用于 比较和 算术。默认情况下and，as unless和 or操作与正确向量中的所有可能条目匹配。

查询示例：

method_code:http_errors:rate5m / ignoring(code) group_left method:http_requests:rate5m

在这种情况下，左向量每个method标签值包含一个以上的条目。因此，我们使用来指示这一点group_left。现在，右侧的元素与method左侧具有相同标签的多个元素匹配：

{method="get", code="500"}  0.04            //  24 / 600
{method="get", code="404"}  0.05            //  30 / 600
{method="post", code="500"} 0.05            //   6 / 120
{method="post", code="404"} 0.175           //  21 / 120

多对一和一对多匹配是应仔细考虑的高级用例。通常，正确使用会产生ignoring(<labels>)所需的结果。

集合运算符

Prometheus支持以下内置的聚合运算符，这些运算符可用于聚合单个即时向量的元素，从而产生具有聚合值的较少元素的新向量：

  • sum （计算尺寸总和）
  • min （选择最小尺寸）
  • max （选择最大尺寸）
  • avg （计算尺寸的平均值）
  • stddev （计算总体尺寸的标准偏差）
  • stdvar （计算总体标准方差）
  • count （计算向量中元素的数量）
  • count_values （计数具有相同值的元素数）
  • bottomk （按样本值最小的k个元素）
  • topk （按样本值最大k个元素）
  • quantile （计算整个尺寸的φ分位数（0≤φ≤1））

这些运算符既可以用于汇总所有标签维，也可以通过包含withoutor by子句来保留不同的维。这些子句可以在表达式之前或之后使用。

<aggr-op> [without|by (<label list>)] ([parameter,] <vector expression>)

要么

<aggr-op>([parameter,] <vector expression>) [without|by (<label list>)]

label list是未加引号的标签的列表，其中可能包含尾随逗号（即两者）(label1, label2)并且(label1, label2,)是有效语法。

without从结果向量中删除列出的标签，而所有其他标签保留在输出中。by相反，并丢弃该by子句中未列出的标签，即使它们的标签值在向量的所有元素之间都相同。

parameter只需要为count_values，quantile，topk和 bottomk。

count_values每个唯一样本值输出一个时间序列。每个系列都有一个附加标签。该标签的名称由聚合参数指定，标签值为唯一的样本值。每个时间序列的值是样本值出现的次数。

topk与bottomk其他聚合器的不同之处在于，输入样本的一个子集（包括原始标签）在结果向量中返回。by并且without仅用于存储输入向量。

例：

如果指标的http_requests_total时间序列由application，instance和group标签呈扇形 散开，我们可以通过以下方式计算每个应用程序和组在所有实例中可见的HTTP请求总数：

sum without (instance) (http_requests_total)

等效于：

 sum by (application, group) (http_requests_total)

如果我们只对在所有 应用程序中看到的HTTP请求总数感兴趣，则可以简单地编写：

sum(http_requests_total)

要计算运行每个构建版本的二进制文件的数量，我们可以编写：

count_values("version", build_version)

为了获得所有实例中最大的5个HTTP请求计数，我们可以编写：

topk(5, http_requests_total)

二进制运算符优先级

下面的列表显示了Prometheus中二进制运算符的优先级，从最高到最低。

  1. ^
  2. *，/，%
  3. +， -
  4. ==，!=，<=，<，>=，>
  5. and， unless
  6. or

优先级相同的运算符是左关联的。例如， 2 * 3 % 2等效于(2 * 3) % 2。但是^是正确的关联，所以2 ^ 3 ^ 2等效于2 ^ (3 ^ 2)。

功能

一些函数具有默认参数，例如year(v=vector(time()) instant-vector)。这意味着有一个参数v是一个即时向量，如果不提供该参数，它将默认为expression的值 vector(time())。

abs()

abs(v instant-vector) 返回所有样本值均转换为绝对值的输入向量。

absent()

absent(v instant-vector) 如果传递给它的向量具有任何元素，则返回一个空向量；如果传递给它的向量没有元素，则返回值为1的1元素向量。

这对于在给定度量标准名称和标签组合不存在任何时间序列时发出警报非常有用。

absent(nonexistent{job="myjob"})
# => {job="myjob"}

absent(nonexistent{job="myjob",instance=~".*"})
# => {job="myjob"}

absent(sum(nonexistent{job="myjob"}))
# => {}

在前两个示例中，absent()尝试聪明地从输入向量中导出1元素输出向量的标签。

absent_over_time()

absent_over_time(v range-vector) 如果传递给它的范围向量有任何元素，则返回一个空向量；如果传递给它的范围向量没有元素，则返回值为1的1元素向量。

这对于在给定的度量标准名称和标签组合在一定时间内没有时间序列时发出警报是很有用的。

absent_over_time(nonexistent{job="myjob"}[1h])
# => {job="myjob"}

absent_over_time(nonexistent{job="myjob",instance=~".*"}[1h])
# => {job="myjob"}

absent_over_time(sum(nonexistent{job="myjob"})[1h:])
# => {}

在前两个示例中，absent_over_time()尝试聪明地从输入向量中导出1元素输出向量的标签。

ceil()

ceil(v instant-vector)将所有元素的样本值四舍五入v到最接近的整数。

changes()

对于每个输入时间序列，changes(v range-vector)返回其值在提供的时间范围内变化的次数作为即时向量。

clamp_max()

clamp_max(v instant-vector, max scalar)将所有元素的样本值钳位为的v上限max。

clamp_min()

clamp_min(v instant-vector, min scalar)将所有元素的样本值钳制在v一个下限内min。

day_of_month()

day_of_month(v=vector(time()) instant-vector)返回UTC中每个给定时间的月份。返回值是1到31。

day_of_week()

day_of_week(v=vector(time()) instant-vector)返回UTC中每个给定时间的星期几。返回的值是从0到6，其中0表示星期日等。

days_in_month()

days_in_month(v=vector(time()) instant-vector)返回UTC中每个给定时间的月份中的天数。返回值是28到31。

delta()

delta(v range-vector)计算范围向量中每个时间序列元素的第一个值与最后一个值之间的差v，并返回具有给定增量和等效标签的即时向量。根据范围矢量选择器中的指定，可以将增量外推以覆盖整个时间范围，因此即使采样值都是整数，也可以得到非整数结果。

以下示例表达式返回现在和2小时前之间的CPU温度差异：

delta(cpu_temp_celsius{host="zeus"}[2h])

delta 只能与压力表一起使用。

deriv()

deriv(v range-vector)v使用简单的线性回归来计算范围向量中时间序列的每秒导数。

deriv 只能与压力表一起使用。

exp()

exp(v instant-vector)计算中的所有元素的指数函数v。特殊情况是：

  • Exp(+Inf) = +Inf
  • Exp(NaN) = NaN

floor()

floor(v instant-vector)将所有元素的样本值四舍五入v到最接近的整数。

histogram_quantile()

histogram_quantile(φ float, b instant-vector)计算φ -分位数（0≤φ≤1）从桶b一个的 直方图。（有关φ分位数的详细说明以及通常使用直方图度量类型的信息，请参见 直方图和摘要。）中的样本b是每个存储桶中观察值的计数。每个样本必须有一个标签le，其中标签值表示存储桶的包含上限。（不带标签的样本将被忽略。）直方图度量标准类型会 自动提供带有_bucket后缀和适当标签的时间序列。

使用此rate()功能可以指定分位数计算的时间窗口。

示例：称为直方图度量http_request_duration_seconds。要计算最近10m的请求持续时间的90％，请使用以下表达式：

histogram_quantile(0.9, rate(http_request_duration_seconds_bucket[10m]))

计算中的每个标签组合的分位数 http_request_duration_seconds。要进行聚合，请sum()在rate()函数周围使用聚合器。由于le标签是必需的 histogram_quantile()，因此必须将其包含在by子句中。以下表达式通过以下方式汇总第90个百分点job：

histogram_quantile(0.9, sum(rate(http_request_duration_seconds_bucket[10m])) by (job, le))

要汇总所有内容，请仅指定le标签：

histogram_quantile(0.9, sum(rate(http_request_duration_seconds_bucket[10m])) by (le))

该histogram_quantile()函数通过假设存储桶内的线性分布来内插分位数。最高存储桶的上限必须为+Inf。（否则，NaN返回。）如果分位数位于最高存储桶中，则返回第二高存储桶的上限。如果该存储桶的上限大于0，则将最低存储桶的下限假定为0。在这种情况下，通常在该存储桶中应用线性插值。否则，将为位于最低存储桶中的分位数返回最低存储桶的上限。

如果b包含少于两个存储桶，NaN则返回。对于φ<0，-Inf返回。如果φ> 1，+Inf则返回。

holt_winters()

holt_winters(v range-vector, sf scalar, tf scalar)根据中的范围为时间序列生成平滑值v。平滑因子越低sf，对旧数据的重视程度越高。趋势因子越高tf，考虑的数据趋势就越多。二者sf并tf必须在0和1之间。

holt_winters 只能与压力表一起使用。

hour()

hour(v=vector(time()) instant-vector)返回UTC中每个给定时间的一天中的小时。返回值是从0到23。

idelta()

idelta(v range-vector)计算范围向量中最后两个样本之间的差v，并返回具有给定增量和等效标签的即时向量。

idelta 只能与压力表一起使用。

increase()

increase(v range-vector)计算范围向量中时间序列的增加。单调性中断（例如由于目标重新启动而导致的计数器重置）会自动进行调整。根据范围向量选择器中的指定，可以推断出增加的时间以覆盖整个时间范围，因此，即使计数器仅以整数增量增加，也可能会获得非整数结果。

以下示例表达式返回范围向量中每个时间序列在最近5分钟内测得的HTTP请求数：

increase(http_requests_total{job="api-server"}[5m])

increase仅应与计数器一起使用。它是语法糖rate(v)乘以指定时间范围窗下的秒数，应主要用于人类可读性。rate在记录规则中使用，以便在每秒的基础上始终跟踪增长情况。

irate()

irate(v range-vector)计算范围向量中时间序列的每秒瞬时增加率。这基于最后两个数据点。单调性中断（例如由于目标重新启动而导致的计数器重置）会自动进行调整。

以下示例表达式返回范围向量中每个时间序列的两个最近数据点的HTTP请求的每秒速率，该速率最多可向后查询5分钟：

irate(http_requests_total{job="api-server"}[5m])

irate仅应在绘制易变，快速移动的计数器时使用。使用rate警报和缓慢移动的柜台，因为在房价短暂变化可以重设FOR条款和图表完全由罕见尖峰难以阅读。

请注意，当irate()与 聚集运算符（例如sum()）或随时间推移聚集的函数（以结尾的任何函数_over_time）组合时，请始终irate()先执行，然后进行聚合。否则，irate()当目标重新启动时，无法检测到计数器重置。

label_join()

对于中的每个时间序列v，label_join(v instant-vector, dst_label string, separator string, src_label_1 string, src_label_2 string, ...)将所有src_labels using 的所有值结合separator在一起，并返回带有dst_label包含结合值的标签的时间序列。src_labels此功能可以有任意多个。

此示例将返回一个向量，其中每个时间序列都有一个foo标签，并在标签上a,b,c添加了值：

label_join(up{job="api-server",src1="a",src2="b",src3="c"}, "foo", ",", "src1", "src2", "src3")

label_replace()

对于其中的每个时间序列v，label_replace(v instant-vector, dst_label string, replacement string, src_label string, regex string)将正则表达式regex与标签匹配src_label。如果匹配，则返回时间序列，并dst_label用的扩展名替换 标签replacement。$1用第一个匹配的子组替换，$2再用第二个匹配的子组替换。如果正则表达式不匹配，则时间序列不变。

此示例将返回一个向量，其中每个时间序列都有一个foo 标签，并在标签上a添加了值：

label_replace(up{job="api-server",service="a:c"}, "foo", "$1", "service", "(.*):.*")

ln()

ln(v instant-vector)计算中所有元素的自然对数v。特殊情况是：

  • ln(+Inf) = +Inf
  • ln(0) = -Inf
  • ln(x < 0) = NaN
  • ln(NaN) = NaN

log2()

log2(v instant-vector)计算中的所有元素的二进制对数v。特殊情况与中的情况相同ln。

log10()

log10(v instant-vector)计算中所有元素的十进制对数v。特殊情况与中的情况相同ln。

minute()

minute(v=vector(time()) instant-vector)返回UTC中每个给定时间的小时分钟。返回值是从0到59。

month()

month(v=vector(time()) instant-vector)返回UTC中每个给定时间的一年中的月份。返回的值是从1到12，其中1表示一月等。

predict_linear()

predict_linear(v range-vector, t scalar)使用简单的线性回归t，基于范围向量预测从现在开始的时间序列秒值 。v

predict_linear 只能与压力表一起使用。

rate()

rate(v range-vector)计算范围向量中时间序列的每秒平均平均增长率。单调性中断（例如由于目标重新启动而导致的计数器重置）会自动进行调整。而且，计算会外推到时间范围的末尾，从而允许遗漏刮擦或刮擦周期与该范围的时间段不完全对齐。

以下示例表达式返回范围向量中每个时间序列在过去5分钟内测得的HTTP请求的每秒速率：

rate(http_requests_total{job="api-server"}[5m])

rate仅应与计数器一起使用。它最适合于警报和慢速计数器的图形显示。

请注意，当rate()与聚集运算符（例如sum()）或随时间推移聚集的函数（以结尾的任何函数_over_time）组合时，请始终rate()先执行，然后进行聚合。否则，rate()当目标重新启动时，无法检测到计数器重置。

resets()

对于每个输入时间序列，resets(v range-vector)将提供的时间范围内的计数器重置次数作为即时向量返回。两个连续采样之间值的任何减少都将解释为计数器复位。

resets 仅应与计数器一起使用。

round()

round(v instant-vector, to_nearest=1 scalar)将所有元素的样本值四舍五入为v最接近的整数。领带通过四舍五入解决。可选to_nearest参数允许指定样本值应四舍五入到的最接近倍数。该倍数也可以是分数。

scalar()

给定一个单元素输入向量，scalar(v instant-vector)返回该单个元素的样本值作为标量。如果输入向量不完全具有一个元素，scalar则将返回NaN。

sort()

sort(v instant-vector) 返回按其样本值升序排列的向量元素。

sort_desc()

与相同sort，但以降序排列。

sqrt()

sqrt(v instant-vector)计算中的所有元素的平方根v。

time()

time()返回自1970年1月1日UTC以来的秒数。请注意，这实际上并不返回当前时间，而是返回要计算表达式的时间。

timestamp()

timestamp(v instant-vector) 返回给定向量的每个样本的时间戳记，作为自1970年1月1日UTC以来的秒数。

该功能已在Prometheus 2.0中添加

vector()

vector(s scalar)s以没有标签的向量形式返回标量。

year()

year(v=vector(time()) instant-vector) 以UTC为单位返回给定时间的年份。

<aggregation>_over_time()

以下函数允许随着时间的推移聚合给定范围向量的每个序列，并返回具有每个序列聚合结果的即时向量：

  • avg_over_time(range-vector)：指定间隔内所有点的平均值。
  • min_over_time(range-vector)：指定间隔中所有点的最小值。
  • max_over_time(range-vector)：指定间隔内所有点的最大值。
  • sum_over_time(range-vector)：指定时间间隔内所有值的总和。
  • count_over_time(range-vector)：指定时间间隔内所有值的计数。
  • quantile_over_time(scalar, range-vector)：指定间隔内值的φ分位数（0≤φ≤1）。
  • stddev_over_time(range-vector)：指定间隔内值的总体标准偏差。
  • stdvar_over_time(range-vector)：指定间隔内值的总体标准方差。

请注意，即使在整个时间间隔内这些值的间隔不相等，指定时间间隔内的所有值在聚合中的权重也相同。

查询示例

简单的时间序列选择

返回所有带有指标的时间序列http_requests_total：

http_requests_total

返回所有时间序列以及指标http_requests_total和给定 job和handler标签：

http_requests_total{job="apiserver", handler="/api/comments"}

返回相同向量的整个时间范围（在本例中为5分钟），使其成为范围向量：

http_requests_total{job="apiserver", handler="/api/comments"}[5m]

请注意，无法直接绘制导致范围向量的表达式，而是在表达式浏览器的表格视图（“控制台”）中查看。

使用正则表达式，您只能选择名称与特定模式匹配的作业的时间序列，在这种情况下，所有以结尾的作业server：

http_requests_total{job=~".*server"}

Prometheus中的所有正则表达式都使用RE2语法。

要选择除4xx之外的所有HTTP状态代码，可以运行：

http_requests_total{status!~"4.."}

子查询

返回http_requests_total过去30分钟内指标的5分钟速率，分辨率为1分钟。

rate(http_requests_total[5m])[30m:1m]

这是一个嵌套子查询的示例。该deriv函数的子查询使用默认分辨率。请注意，不必要地使用子查询是不明智的。

max_over_time(deriv(rate(distance_covered_total[5s])[30s:5s])[10m:])

使用函数，运算符等

返回所有http_requests_total 度量标准名称的时间序列的每秒速率，以最近5分钟为单位：

rate(http_requests_total[5m])

假设http_requests_total时间序列都具有标签job （按作业名称进行扇出）和instance（按作业实例进行扇出），我们可能希望对所有实例的比率求和，因此得到的输出时间序列较少，但仍保留job维度：

sum by (job) (
  rate(http_requests_total[5m])
)

如果我们有两个具有相同维标签的不同度量，则可以对它们应用二元运算符，并且具有相同标签集的两侧的元素都将匹配并传播到输出。例如，此表达式为每个实例返回MiB中未使用的内存（在虚构的群集调度程序上，它公开了有关其运行的实例的这些指标）：

(instance_memory_limit_bytes - instance_memory_usage_bytes) / 1024 / 1024

相同的表达式，但由应用程序求和，可以这样写：

sum by (app, proc) (
  instance_memory_limit_bytes - instance_memory_usage_bytes
) / 1024 / 1024

如果相同的虚拟群集调度程序针对每个实例公开了以下CPU使用率指标：

instance_cpu_time_ns{app="lion", proc="web", rev="34d0f99", env="prod", job="cluster-manager"}
instance_cpu_time_ns{app="elephant", proc="worker", rev="34d0f99", env="prod", job="cluster-manager"}
instance_cpu_time_ns{app="turtle", proc="api", rev="4d3a513", env="prod", job="cluster-manager"}
instance_cpu_time_ns{app="fox", proc="widget", rev="4d3a513", env="prod", job="cluster-manager"}
...

...我们可以按应用程序（app）和进程类型（proc）将前3个CPU用户分组，如下所示：

topk(3, sum by (app, proc) (rate(instance_cpu_time_ns[5m])))

假设此指标每个运行实例包含一个时间序列，则可以像这样计算每个应用程序的运行实例数：

count by (app) (instance_cpu_time_ns)

HTTP API

/api/v1在Prometheus服务器上可以访问当前稳定的HTTP API 。任何不间断的添加都将添加到该端点下。

格式概述

API响应格式为JSON。每个成功的API请求都会返回一个2xx 状态码。

到达API处理程序的无效请求会返回JSON错误对象和以下HTTP响应代码之一：

  • 400 Bad Request 参数丢失或不正确时。
  • 422 Unprocessable Entity无法执行表达式时（RFC4918）。
  • 503 Service Unavailable 查询超时或中止时。

2xx对于到达API端点之前发生的错误，可能会返回其他非代码。

如果存在不会阻止请求执行的错误，则可能会返回一系列警告。成功收集的所有数据都将在数据字段中返回。

JSON响应信封格式如下：

{
  "status": "success" | "error",
  "data": <data>,

  // Only set if status is "error". The data field may still hold
  // additional data.
  "errorType": "<string>",
  "error": "<string>",

  // Only if there were warnings while executing the request.
  // There will still be data in the data field.
  "warnings": ["<string>"]
}

输入时间戳可以以RFC3339格式提供，也可以以 Unix时间戳（以秒为单位）提供，可选的小数位用于亚秒级精度。输出时间戳始终以秒为单位表示为Unix时间戳。

可以重复的查询参数名称以[]。结尾。

<series_selector>占位符指的是Prometheus 时间序列选择器，例如http_requests_total或， http_requests_total{method=~"(GET|POST)"}并且需要进行URL编码。

<duration>占位符是指形式为Prometheus的持续时间字符串 [0-9]+[smhdwy]。例如，5m指持续时间为5分钟。

<bool>占位符指的是布尔值（字符串true和false）。

表达式查询

查询语言表达式可以在单个瞬间或一段时间内求值。以下各节介绍了每种类型的表达式查询的API端点。

即时查询

以下端点在单个时间点评估即时查询：

GET /api/v1/query
POST /api/v1/query

网址查询参数：

  • query=<string>：Prometheus表达式查询字符串。
  • time=<rfc3339 | unix_timestamp>：评估时间戳。可选的。
  • timeout=<duration>：评估超时。可选的。默认为，并以该-query.timeout标志的值为上限。

如果time省略该参数，则使用当前服务器时间。

您可以使用POST方法和 Content-Type: application/x-www-form-urlencoded标头直接在请求正文中对这些参数进行URL编码。当指定可能违反服务器端URL字符限制的大型查询时，此功能很有用。

data查询结果的部分具有以下格式：

{
  "resultType": "matrix" | "vector" | "scalar" | "string",
  "result": <value>
}

<value>是指查询结果数据，其格式取决于resultType。请参阅表达式查询结果格式。

下面的示例计算的表达up在时间 2015-07-01T20:10:51.781Z：

$ curl 'http://localhost:9090/api/v1/query?query=up&time=2015-07-01T20:10:51.781Z'
{
   "status" : "success",
   "data" : {
      "resultType" : "vector",
      "result" : [
         {
            "metric" : {
               "__name__" : "up",
               "job" : "prometheus",
               "instance" : "localhost:9090"
            },
            "value": [ 1435781451.781, "1" ]
         },
         {
            "metric" : {
               "__name__" : "up",
               "job" : "node",
               "instance" : "localhost:9100"
            },
            "value" : [ 1435781451.781, "0" ]
         }
      ]
   }
}

范围查询

以下端点在一段时间内评估表达式查询：

GET /api/v1/query_range
POST /api/v1/query_range

网址查询参数：

  • query=<string>：Prometheus表达式查询字符串。
  • start=<rfc3339 | unix_timestamp>：开始时间戳。
  • end=<rfc3339 | unix_timestamp>：结束时间戳记。
  • step=<duration | float>：以duration格式或浮点秒数查询分辨率步长。
  • timeout=<duration>：评估超时。可选的。默认为，并以该-query.timeout标志的值为上限。

您可以使用POST方法和 Content-Type: application/x-www-form-urlencoded标头直接在请求正文中对这些参数进行URL编码。当指定可能违反服务器端URL字符限制的大型查询时，此功能很有用。

data查询结果的部分具有以下格式：

{
  "resultType": "matrix",
  "result": <value>
}

有关<value>占位符的格式，请参见范围向量结果格式。

下面的示例up在30秒范围内以15秒的查询分辨率对表达式求值。

$ curl 'http://localhost:9090/api/v1/query_range?query=up&start=2015-07-01T20:10:30.781Z&end=2015-07-01T20:11:00.781Z&step=15s'
{
   "status" : "success",
   "data" : {
      "resultType" : "matrix",
      "result" : [
         {
            "metric" : {
               "__name__" : "up",
               "job" : "prometheus",
               "instance" : "localhost:9090"
            },
            "values" : [
               [ 1435781430.781, "1" ],
               [ 1435781445.781, "1" ],
               [ 1435781460.781, "1" ]
            ]
         },
         {
            "metric" : {
               "__name__" : "up",
               "job" : "node",
               "instance" : "localhost:9091"
            },
            "values" : [
               [ 1435781430.781, "0" ],
               [ 1435781445.781, "0" ],
               [ 1435781460.781, "1" ]
            ]
         }
      ]
   }
}

查询元数据

通过标签匹配器查找序列

以下端点返回与某个标签集匹配的时间序列列表。

GET /api/v1/series
POST /api/v1/series

网址查询参数：

  • match[]=<series_selector>：重复的序列选择器参数，用于选择要返回的序列。match[]必须至少提供一个参数。
  • start=<rfc3339 | unix_timestamp>：开始时间戳。
  • end=<rfc3339 | unix_timestamp>：结束时间戳记。

您可以使用POST方法和 Content-Type: application/x-www-form-urlencoded标头直接在请求正文中对这些参数进行URL编码。当指定大量或动态数量的序列选择器可能违反服务器端URL字符限制时，此功能很有用。

该data查询结果的部分由包含其识别每个系列标签名称/值对对象的列表中。

以下示例返回与选择器up或匹配的所有系列 process_start_time_seconds{job="prometheus"}。

$ curl -g 'http://localhost:9090/api/v1/series?' --data-urlencode 'match[]=up' --data-urlencode 'match[]=process_start_time_seconds{job="prometheus"}'
{
   "status" : "success",
   "data" : [
      {
         "__name__" : "up",
         "job" : "prometheus",
         "instance" : "localhost:9090"
      },
      {
         "__name__" : "up",
         "job" : "node",
         "instance" : "localhost:9091"
      },
      {
         "__name__" : "process_start_time_seconds",
         "job" : "prometheus",
         "instance" : "localhost:9090"
      }
   ]
}

获取标签名称

以下端点返回标签名称的列表：

GET /api/v1/labels
POST /api/v1/labels

该dataJSON响应的部分是字符串标签名称的列表。

这是一个例子。

$ curl 'localhost:9090/api/v1/labels'
{
    "status": "success",
    "data": [
        "__name__",
        "call",
        "code",
        "config",
        "dialer_name",
        "endpoint",
        "event",
        "goversion",
        "handler",
        "instance",
        "interval",
        "job",
        "le",
        "listener_name",
        "name",
        "quantile",
        "reason",
        "role",
        "scrape_job",
        "slice",
        "version"
    ]
}

查询标签值

以下端点返回提供的标签名称的标签值的列表：

GET /api/v1/label/<label_name>/values

该dataJSON响应的部分是字符串标签值的列表。

本示例查询标签的所有标签值job：

$ curl http://localhost:9090/api/v1/label/job/values
{
   "status" : "success",
   "data" : [
      "node",
      "prometheus"
   ]
}

表达式查询结果格式

表达式查询可能在result 该data节的属性中返回以下响应值。<sample_value>占位符是数字样本值。JSON不支持的特殊浮点值，例如NaN，Inf和-Inf，因此采样值转移所报JSON字符串，而不是原始数据。

范围向量

范围向量作为结果类型返回matrix。相应的 result属性具有以下格式：

[
  {
    "metric": { "<label_name>": "<label_value>", ... },
    "values": [ [ <unix_time>, "<sample_value>" ], ... ]
  },
  ...
]

即时向量

即时向量将作为结果类型返回vector。相应的 result属性具有以下格式：

[
  {
    "metric": { "<label_name>": "<label_value>", ... },
    "value": [ <unix_time>, "<sample_value>" ]
  },
  ...
]

标量

标量结果作为结果类型返回scalar。相应的 result属性具有以下格式：

[ <unix_time>, "<scalar_value>" ]

弦乐

字符串结果作为结果类型返回string。相应的 result属性具有以下格式：

[ <unix_time>, "<string_value>" ]

目标

以下端点返回Prometheus目标发现的当前状态的概述：

GET /api/v1/targets

默认情况下，活动目标和已删除目标都是响应的一部分。 labels表示重新贴标签后的标签集。 discoveredLabels表示重新标记发生之前在服务发现期间检索到的未修改标签。

$ curl http://localhost:9090/api/v1/targets
{
  "status": "success",
  "data": {
    "activeTargets": [
      {
        "discoveredLabels": {
          "__address__": "127.0.0.1:9090",
          "__metrics_path__": "/metrics",
          "__scheme__": "http",
          "job": "prometheus"
        },
        "labels": {
          "instance": "127.0.0.1:9090",
          "job": "prometheus"
        },
        "scrapePool": "prometheus",
        "scrapeUrl": "http://127.0.0.1:9090/metrics",
        "lastError": "",
        "lastScrape": "2017-01-17T15:07:44.723715405+01:00",
        "lastScrapeDuration": 0.050688943,
        "health": "up"
      }
    ],
    "droppedTargets": [
      {
        "discoveredLabels": {
          "__address__": "127.0.0.1:9100",
          "__metrics_path__": "/metrics",
          "__scheme__": "http",
          "job": "node"
        },
      }
    ]
  }
}

所述state查询参数允许调用者滤波器通过主动或丢弃目标，（例如，state=active，state=dropped，state=any）。请注意，对于已滤除的目标，仍然返回空数组。其他值将被忽略。

$ curl 'http://localhost:9090/api/v1/targets?state=active'
{
  "status": "success",
  "data": {
    "activeTargets": [
      {
        "discoveredLabels": {
          "__address__": "127.0.0.1:9090",
          "__metrics_path__": "/metrics",
          "__scheme__": "http",
          "job": "prometheus"
        },
        "labels": {
          "instance": "127.0.0.1:9090",
          "job": "prometheus"
        },
        "scrapePool": "prometheus",
        "scrapeUrl": "http://127.0.0.1:9090/metrics",
        "lastError": "",
        "lastScrape": "2017-01-17T15:07:44.723715405+01:00",
        "lastScrapeDuration": 50688943,
        "health": "up"
      }
    ],
    "droppedTargets": []
  }
}

规则

该/rulesAPI端点返回报警和记录当前加载规则的列表。此外，它还返回由每个警报规则的Prometheus实例触发的当前活动警报。

由于/rules端点是相当新的，因此它没有与总体API v1相同的稳定性保证。

GET /api/v1/rules

URL查询参数：- type=alert|record：仅返回警报规则（例如type=alert）或记录规则（例如type=record）。如果该参数不存在或为空，则不执行任何过滤。

$ curl http://localhost:9090/api/v1/rules

{
    "data": {
        "groups": [
            {
                "rules": [
                    {
                        "alerts": [
                            {
                                "activeAt": "2018-07-04T20:27:12.60602144+02:00",
                                "annotations": {
                                    "summary": "High request latency"
                                },
                                "labels": {
                                    "alertname": "HighRequestLatency",
                                    "severity": "page"
                                },
                                "state": "firing",
                                "value": "1e+00"
                            }
                        ],
                        "annotations": {
                            "summary": "High request latency"
                        },
                        "duration": 600,
                        "health": "ok",
                        "labels": {
                            "severity": "page"
                        },
                        "name": "HighRequestLatency",
                        "query": "job:request_latency_seconds:mean5m{job=\"myjob\"} > 0.5",
                        "type": "alerting"
                    },
                    {
                        "health": "ok",
                        "name": "job:http_inprogress_requests:sum",
                        "query": "sum(http_inprogress_requests) by (job)",
                        "type": "recording"
                    }
                ],
                "file": "/rules.yaml",
                "interval": 60,
                "name": "example"
            }
        ]
    },
    "status": "success"
}

警报

该/alerts端点返回所有活动警报的列表。

由于/alerts端点是相当新的，因此它没有与总体API v1相同的稳定性保证。

GET /api/v1/alerts

$ curl http://localhost:9090/api/v1/alerts

{
    "data": {
        "alerts": [
            {
                "activeAt": "2018-07-04T20:27:12.60602144+02:00",
                "annotations": {},
                "labels": {
                    "alertname": "my-alert"
                },
                "state": "firing",
                "value": "1e+00"
            }
        ]
    },
    "status": "success"
}

查询目标元数据

以下端点返回有关当前从目标中抓取的指标的元数据。这是实验性的，将来可能会改变。

GET /api/v1/targets/metadata

网址查询参数：

  • match_target=<label_selectors>：通过标签集匹配目标的标签选择器。如果保留为空，则选择所有目标。
  • metric=<string>：要为其检索元数据的指标名称。如果保留为空，则将检索所有度量标准元数据。
  • limit=<number>：要匹配的最大目标数。

该data查询结果的部分由包含度量元数据和对象的标贴纸组对象的列表。

以下示例go_goroutines从带有标签的前两个目标返回该指标的所有元数据条目job="prometheus"。

curl -G http://localhost:9091/api/v1/targets/metadata \
    --data-urlencode 'metric=go_goroutines' \
    --data-urlencode 'match_target={job="prometheus"}' \
    --data-urlencode 'limit=2'
{
  "status": "success",
  "data": [
    {
      "target": {
        "instance": "127.0.0.1:9090",
        "job": "prometheus"
      },
      "type": "gauge",
      "help": "Number of goroutines that currently exist.",
      "unit": ""
    },
    {
      "target": {
        "instance": "127.0.0.1:9091",
        "job": "prometheus"
      },
      "type": "gauge",
      "help": "Number of goroutines that currently exist.",
      "unit": ""
    }
  ]
}

以下示例返回带有label的所有目标的所有指标的元数据instance="127.0.0.1:9090。

curl -G http://localhost:9091/api/v1/targets/metadata \
    --data-urlencode 'match_target={instance="127.0.0.1:9090"}'
{
  "status": "success",
  "data": [
    // ...
    {
      "target": {
        "instance": "127.0.0.1:9090",
        "job": "prometheus"
      },
      "metric": "prometheus_treecache_zookeeper_failures_total",
      "type": "counter",
      "help": "The total number of ZooKeeper failures.",
      "unit": ""
    },
    {
      "target": {
        "instance": "127.0.0.1:9090",
        "job": "prometheus"
      },
      "metric": "prometheus_tsdb_reloads_total",
      "type": "counter",
      "help": "Number of times the database reloaded block data from disk.",
      "unit": ""
    },
    // ...
  ]
}

查询指标元数据

它返回有关当前从目标中删除的指标的元数据。但是，它不提供任何目标信息。这被认为是实验性的，将来可能会改变。

GET /api/v1/metadata

网址查询参数：

  • limit=<number>：要返回的最大指标数量。
  • metric=<string>：指标名称，用于过滤元数据。如果保留为空，则将检索所有度量标准元数据。

data查询结果的部分由一个对象组成，其中每个键是一个度量标准名称，每个值是一个唯一元数据对象的列表，该度量标准名称在所有目标中都公开。

以下示例返回两个指标。请注意，该指标http_requests_total在列表中有多个对象。至少一个目标的值HELP与其余目标不匹配。

curl -G http://localhost:9090/api/v1/metadata?limit=2

{
  "status": "success",
  "data": {
    "cortex_ring_tokens": [
      {
        "type": "gauge",
        "help": "Number of tokens in the ring",
        "unit": ""
      }
    ],
    "http_requests_total": [
      {
        "type": "counter",
        "help": "Number of HTTP requests",
        "unit": ""
      },
      {
        "type": "counter",
        "help": "Amount of HTTP requests",
        "unit": ""
      }
    ]
  }
}

以下示例仅返回该指标的元数据http_requests_total。

curl -G http://localhost:9090/api/v1/metadata?metric=http_requests_total

{
  "status": "success",
  "data": {
    "http_requests_total": [
      {
        "type": "counter",
        "help": "Number of HTTP requests",
        "unit": ""
      },
      {
        "type": "counter",
        "help": "Amount of HTTP requests",
        "unit": ""
      }
    ]
  }
}

警报经理

以下端点返回Prometheus alertmanager发现的当前状态的概述：

GET /api/v1/alertmanagers

激活和已删除的Alertmanagers都是响应的一部分。

$ curl http://localhost:9090/api/v1/alertmanagers
{
  "status": "success",
  "data": {
    "activeAlertmanagers": [
      {
        "url": "http://127.0.0.1:9090/api/v1/alerts"
      }
    ],
    "droppedAlertmanagers": [
      {
        "url": "http://127.0.0.1:9093/api/v1/alerts"
      }
    ]
  }
}

状态

以下状态端点公开了当前的Prometheus配置。

设定档

以下端点返回当前加载的配置文件：

GET /api/v1/status/config

该配置作为转储的YAML文件返回。由于YAML库的限制，不包括YAML注释。

$ curl http://localhost:9090/api/v1/status/config
{
  "status": "success",
  "data": {
    "yaml": "<content of the loaded config file in YAML>",
  }
}

标志

以下端点返回配置了Prometheus的标志值：

GET /api/v1/status/flags

所有值均为结果类型string。

$ curl http://localhost:9090/api/v1/status/flags
{
  "status": "success",
  "data": {
    "alertmanager.notification-queue-capacity": "10000",
    "alertmanager.timeout": "10s",
    "log.level": "info",
    "query.lookback-delta": "5m",
    "query.max-concurrency": "20",
    ...
  }
}

v2.2的新功能

运行时信息

以下端点返回有关Prometheus服务器的各种运行时信息属性：

GET /api/v1/status/runtimeinfo

返回的值具有不同的类型，具体取决于运行时属性的性质。

$ curl http://localhost:9090/api/v1/status/runtimeinfo
{
  "status": "success",
  "data": {
    "startTime": "2019-11-02T17:23:59.301361365+01:00",
    "CWD": "/",
    "reloadConfigSuccess": true,
    "lastConfigTime": "2019-11-02T17:23:59+01:00",
    "chunkCount": 873,
    "timeSeriesCount": 873,
    "corruptionCount": 0,
    "goroutineCount": 48,
    "GOMAXPROCS": 4,
    "GOGC": "",
    "GODEBUG": "",
    "storageRetention": "15d"
  }
}

注意：在Prometheus版本之间，确切的返回运行时属性可能会更改，恕不另行通知。

v2.14的新功能

建造信息

以下端点返回有关Prometheus服务器的各种构建信息属性：

GET /api/v1/status/buildinfo

所有值均为结果类型string。

$ curl http://localhost:9090/api/v1/status/buildinfo
{
  "status": "success",
  "data": {
    "version": "2.13.1",
    "revision": "cb7cbad5f9a2823a622aaa668833ca04f50a0ea7",
    "branch": "master",
    "buildUser": "julius@desktop",
    "buildDate": "20191102-16:19:59",
    "goVersion": "go1.13.1"
  }
}

注意：在Prometheus版本之间，返回的确切构建属性可能会有所更改，恕不另行通知。

v2.14的新功能

TSDB统计

以下端点返回有关Prometheus TSDB的各种基数统计信息：

GET /api/v1/status/tsdb
  • seriesCountByMetricName： 这将提供指标名称及其系列计数的列表。
  • labelValueCountByLabelName：这将提供标签名称及其值计数的列表。
  • memoryInBytesByLabelName这将提供标签名称和以字节为单位使用的内存的列表。内存使用量是通过将给定标签名称的所有值的长度相加得出的。
  • seriesCountByLabelPair这将提供标签值对及其系列计数的列表。
$ curl http://localhost:9090/api/v1/status/tsdb
{
  "status": "success",
  "data": {
    "seriesCountByMetricName": [
      {
        "name": "net_conntrack_dialer_conn_failed_total",
        "value": 20
      },
      {
        "name": "prometheus_http_request_duration_seconds_bucket",
        "value": 20
      }
    ],
    "labelValueCountByLabelName": [
      {
        "name": "__name__",
        "value": 211
      },
      {
        "name": "event",
        "value": 3
      }
    ],
    "memoryInBytesByLabelName": [
      {
        "name": "__name__",
        "value": 8266
      },
      {
        "name": "instance",
        "value": 28
      }
    ],
    "seriesCountByLabelValuePair": [
      {
        "name": "job=prometheus",
        "value": 425
      },
      {
        "name": "instance=localhost:9090",
        "value": 425
      }
    ]
  }
}

v2.15的新功能

TSDB管理员API

这些API为高级用户提供了数据库功能。除非--web.enable-admin-api设置，否则不会启用这些API 。

我们还公开了一个gRPC API，其定义可以在此处找到。这是实验性的，将来可能会改变。

快照

快照将所有当前数据的快照创建到snapshots/<datetime>-<rand>TSDB的数据目录下，并将该目录作为响应返回。它可以选择跳过仅存在于head块中并且尚未压缩到磁盘的快照数据。

POST /api/v1/admin/tsdb/snapshot
PUT /api/v1/admin/tsdb/snapshot

网址查询参数：

  • skip_head=<bool>：跳过起始块中存在的数据。可选的。
$ curl -XPOST http://localhost:9090/api/v1/admin/tsdb/snapshot
{
  "status": "success",
  "data": {
    "name": "20171210T211224Z-2be650b6d019eb54"
  }
}

快照现在位于 <data-dir>/snapshots/20171210T211224Z-2be650b6d019eb54

v2.1中的新增功能，并支持v2.9中的PUT

删除系列

DeleteSeries删除一个时间范围内选定系列的数据。实际数据仍然存在于磁盘上，并在以后的压缩中进行清理，或者可以通过单击Clean Tombstones端点进行显式清理。

如果成功，204则返回a。

POST /api/v1/admin/tsdb/delete_series
PUT /api/v1/admin/tsdb/delete_series

网址查询参数：

  • match[]=<series_selector>：重复标签匹配器参数，用于选择要删除的系列。match[]必须至少提供一个参数。
  • start=<rfc3339 | unix_timestamp>：开始时间戳。可选，默认为最短时间。
  • end=<rfc3339 | unix_timestamp>：结束时间戳记。可选，默认为最大可能时间。

不提及开始时间和结束时间将清除数据库中匹配序列的所有数据。

例：

$ curl -X POST \
  -g 'http://localhost:9090/api/v1/admin/tsdb/delete_series?match[]=up&match[]=process_start_time_seconds{job="prometheus"}'

v2.1中的新增功能，并支持v2.9中的PUT

干净的墓碑

CleanTombstones从磁盘上删除已删除的数据，并清理现有的逻辑删除。删除系列后可以使用它来释放空间。

如果成功，204则返回a。

POST /api/v1/admin/tsdb/clean_tombstones
PUT /api/v1/admin/tsdb/clean_tombstones

这不带参数或主体。

$ curl -XPOST http://localhost:9090/api/v1/admin/tsdb/clean_tombstones

v2.1中的新增功能，并支持v2.9中的PUT

存储

Prometheus包括本地磁盘时间序列数据库，但也可以选择与远程存储系统集成。

本地存储

Prometheus的本地时间序列数据库以自定义格式在磁盘上存储时间序列数据。

磁盘上的布局

摄入的样品分为两个小时。每个两个小时的时间段包含一个目录，该目录包含一个或多个块文件，该文件包含该时间窗口的所有时间序列样本，以及元数据文件和索引文件（用于将度量名称和标签索引到块文件中的时间序列） ）。通过API删除系列时，删除记录存储在单独的逻辑删除文件中（而不是立即从块文件中删除数据）。

当前传入样本的块保留在内存中，尚未完全保留。它通过预写日志（WAL）防止崩溃，当Prometheus服务器在崩溃后重新启动时可以重放该日志。预写日志文件wal以128MB的段存储在目录中。这些文件包含尚未压缩的原始数据，因此它们比常规的块文件大得多。Prometheus将至少保留3个预写日志文件，但是高流量服务器可能会看到三个以上的WAL文件，因为它需要保留至少两个小时的原始数据。

Prometheus服务器的数据目录的目录结构如下所示：

./data
├── 01BKGV7JBM69T2G1BGBGM6KB12
│   └── meta.json
├── 01BKGTZQ1SYQJTR4PB43C8PD98
│   ├── chunks
│   │   └── 000001
│   ├── tombstones
│   ├── index
│   └── meta.json
├── 01BKGTZQ1HHWHV8FBJXW1Y3W0K
│   └── meta.json
├── 01BKGV7JC0RY8A6MACW02A2PJD
│   ├── chunks
│   │   └── 000001
│   ├── tombstones
│   ├── index
│   └── meta.json
└── wal
    ├── 00000002
    └── checkpoint.000001

请注意，本地存储的局限性在于它不是集群或复制的。因此，面对磁盘或节点中断，它不是任意可伸缩的或持久的，应该像对待任何其他类型的单节点数据库一样对待它。建议将RAID用于磁盘可用性，快照用于备份，容量计划等，以提高耐用性。通过适当的存储耐久性和计划，可以在本地存储中存储多年的数据。

或者，可以通过远程读/写API使用外部存储。这些系统的耐用性，性能和效率差异很大，因此需要仔细评估。

有关文件格式的更多详细信息，请参见TSDB format。

压实

最初的两个小时的块最终会在后台压缩为更长的块。

压缩将创建较大的块，最多保留时间的10％，即31天，以较小者为准。

运营方面

Prometheus具有几个允许配置本地存储的标志。最重要的是：

  • --storage.tsdb.path：这确定Prometheus在何处写入其数据库。默认为data/。
  • --storage.tsdb.retention.time：这确定何时删除旧数据。默认为15d。storage.tsdb.retention如果此标志设置为默认值以外的其他值，则覆盖。
  • --storage.tsdb.retention.size：[EXPERIMENTAL]这确定存储块可以使用的最大字节数（请注意，这不包括WAL大小，该大小可能很大）。最旧的数据将首先被删除。默认为0或禁用。该标志是实验性的，可以在将来的版本中进行更改。支持的单位：KB，MB，GB，PB。例如：“ 512MB”
  • --storage.tsdb.retention：已弃用此标志，而推荐使用storage.tsdb.retention.time。
  • --storage.tsdb.wal-compression：此标志启用预写日志（WAL）的压缩。根据您的数据，可以预期WAL大小将减少一半，而额外的CPU负载却很少。请注意，如果启用此标志，然后将Prometheus降级到2.11.0以下的版本，则您将需要删除WAL，因为它将不可读。

平均而言，普罗米修斯每个样本仅使用大约1-2个字节。因此，要计划Prometheus服务器的容量，可以使用以下粗略公式：

needed_disk_space = retention_time_seconds * ingested_samples_per_second * bytes_per_sample

要调整每秒摄取的样本的速率，可以减少抓取的时间序列数（每个目标更少的目标或更少的序列），或者可以增加抓取时间间隔。但是，由于压缩了一个系列中的样本，减少系列数可能更有效。

如果您的本地存储由于某种原因而损坏，最好的选择是关闭Prometheus并删除整个存储目录。Prometheus的本地存储不支持不兼容POSIX的文件系统，可能会发生损坏，无法恢复。NFS仅是潜在的POSIX，大多数实现不是。您可以尝试删除单个块目录来解决该问题，这意味着每个块目录损失的时间窗口大约为两个小时。同样，Prometheus的本地存储并不意味着持久的长期存储。

如果同时指定了时间和大小保留策略，则在那一刻将使用第一个触发的策略。

过期的块清除将在后台进行。删除过期的块可能最多需要两个小时。过期的块在清除之前必须完全过期。

远程存储集成

Prometheus的本地存储在可伸缩性和持久性方面受到单个节点的限制。Prometheus并没有尝试解决Prometheus本身中的群集存储，而是提供了一组允许与远程存储系统集成的接口。

总览

Prometheus通过两种方式与远程存储系统集成：

  • Prometheus可以将提取的样本以标准格式写入远程URL。
  • Prometheus可以以标准格式从远程URL读取（返回）样本数据。

远程读写架构

读写协议都使用基于HTTP的快速压缩协议缓冲区编码。该协议尚未被认为是稳定的API，当可以安全地假定Prometheus和远程存储之间的所有跃点都支持HTTP / 2时，该协议将来可能会更改为在HTTP / 2上使用gRPC。

有关在Prometheus中配置远程存储集成的详细信息，请参阅Prometheus配置文档的“ 远程写入”和“ 远程读取”部分。

有关请求和响应消息的详细信息，请参阅远程存储协议缓冲区定义。

请注意，在读取路径上，Prometheus仅从远端获取一组标签选择器和时间范围的原始系列数据。PromQL对原始数据的所有评估仍然在Prometheus本身中进行。这意味着远程读取查询具有一定的可伸缩性限制，因为所有必需的数据都需要先加载到查询的Prometheus服务器中，然后再在其中进行处理。但是，暂时认为支持PromQL的完全分布式评估是不可行的。

现有集成

要了解有关与远程存储系统的现有集成的更多信息，请参阅集成文档。

联邦

联合允许Prometheus服务器从另一台Prometheus服务器抓取选定的时间序列。

用例

联盟有不同的用例。通常，它用于实现可扩展的Prometheus监视设置或将相关指标从一项服务的Prometheus引入另一项服务。

分层联盟

分层联合使Prometheus可以扩展到具有数十个数据中心和数百万个节点的环境。在此用例中，联合拓扑类似于一棵树，更高级别的Prometheus服务器从大量从属服务器收集聚合的时间序列数据。

例如，一个设置可能包含许多每个数据中心的Prometheus服务器，这些服务器收集详细信息的数据（实例级别的向下钻取），以及一组全局Prometheus服务器，它们仅收集和存储聚合的数据（作业级别的向下钻取） ）从这些本地服务器。这提供了汇总的全局视图和详细的局部视图。

跨服务联合

在跨服务联合中，将一项服务的Prometheus服务器配置为从另一项服务的Prometheus服务器抓取所选数据，以针对单个服务器内的两个数据集启用警报和查询。

例如，运行多个服务的群集调度程序可能会公开有关在群集上运行的服务实例的资源使用情况信息（例如内存和CPU使用情况）。另一方面，在该群集上运行的服务将仅公开特定于应用程序的服务指标。通常，这两组指标由单独的Prometheus服务器抓取。使用联盟，包含服务级别指标的Prometheus服务器可以从集群Prometheus中获取有关其特定服务的集群资源使用指标，以便可以在该服务器内使用这两组指标。

配置联盟

在任何给定的Prometheus服务器上，/federate端点都允许检索该服务器中选定时间序列集的当前值。match[]必须至少指定一个 URL参数才能选择要公开的系列。每个 match[]参数都需要指定一个 即时矢量选择器，例如 up或{job="api-server"}。如果match[]提供了多个参数，则选择所有匹配系列的并集。

要将度量标准从一台服务器联合到另一台服务器，请将目标Prometheus服务器配置为从/federate源服务器的端点进行爬网，同时还启用honor_labelsscrape选项（不覆盖源服务器暴露的任何标签）并传递所需的match[] 参数。例如，以下代码将从Prometheus服务器开始的scrape_configs任何带有标签job="prometheus"或度量标准名称的系列联合到刮取Prometheus中：job:source-prometheus-{1,2,3}:9090

scrape_configs:
  - job_name: 'federate'
    scrape_interval: 15s

    honor_labels: true
    metrics_path: '/federate'

    params:
      'match[]':
        - '{job="prometheus"}'
        - '{__name__=~"job:.*"}'

    static_configs:
      - targets:
        - 'source-prometheus-1:9090'
        - 'source-prometheus-2:9090'
        - 'source-prometheus-3:9090'

管理API

Prometheus提供了一组管理API，以简化自动化和集成。

健康检查

GET /-/healthy

该端点始终返回200，应用于检查Prometheus的运行状况。

准备检查

GET /-/ready

当Prometheus准备服务流量（即响应查询）时，此端点返回200。

重装

PUT  /-/reload
POST /-/reload

该端点触发Prometheus配置和规则文件的重新加载。默认情况下它是禁用的，可以通过该--web.enable-lifecycle标志启用。

或者，可以通过向SIGHUPPrometheus进程发送a 来触发配置重载。

放弃

PUT  /-/quit
POST /-/quit

该端点触发Prometheus的正常关闭。默认情况下它是禁用的，可以通过该--web.enable-lifecycle标志启用。

或者，可以通过向SIGTERMPrometheus进程发送a 来触发正常关闭。

 

PROMETHEUS 2.0迁移指南

符合我们的稳定性承诺，Prometheus 2.0版本包含许多向后不兼容的更改。本文档提供了从Prometheus 1.8迁移到Prometheus 2.0的指南。

标志

Prometheus命令行标志的格式已更改。现在，所有标志不再使用单破折号，而是使用双破折号。公共标志（--config.file， --web.listen-address和--web.external-url）仍然是相同的，但除此之外，几乎所有与存储相关的标志已被删除。

一些值得注意的标志已被删除：

  • -alertmanager.url在Prometheus 2.0中，用于配置静态Alertmanager URL的命令行标志已被删除。现在必须通过服务发现来发现Alertmanager，请参阅Alertmanager服务发现。

  • -log.format 在Prometheus 2.0中，日志只能流式传输为标准错误。

  • -query.staleness-delta已重命名为--query.lookback-delta; Prometheus 2.0引入了一种处理陈旧性的新机制，请参见陈旧性。

  • -storage.local.*Prometheus 2.0引入了新的存储引擎，因为与旧引擎有关的所有标志都已删除。有关新引擎的信息，请参阅存储。

  • -storage.remote.*Prometheus 2.0删除了已经不赞成使用的远程存储标志，如果提供了它们，将无法启动。要写入InfluxDB，Graphite或OpenTSDB，请使用相关的存储适配器。

Alertmanager服务发现

Prometheus 1.4中引入了Alertmanager服务发现，使Prometheus可以使用与抓取目标相同的机制来动态发现Alertmanager副本。在Prometheus 2.0中，静态Alertmanager配置的命令行标志已删除，因此以下命令行标志：

./prometheus -alertmanager.url=http://alertmanager:9093/

将在prometheus.yml配置文件中替换为以下内容：

alerting:
  alertmanagers:
  - static_configs:
    - targets:
      - alertmanager:9093

您还可以在Alertmanager配置中使用所有常规的Prometheus服务发现集成和重新标记。该代码片段指示Prometheus在default名称空间中使用标签name: alertmanager和非空端口搜索Kubernetes Pod 。

alerting:
  alertmanagers:
  - kubernetes_sd_configs:
      - role: pod
    tls_config:
      ca_file: /var/run/secrets/kubernetes.io/serviceaccount/ca.crt
    bearer_token_file: /var/run/secrets/kubernetes.io/serviceaccount/token
    relabel_configs:
    - source_labels: [__meta_kubernetes_pod_label_name]
      regex: alertmanager
      action: keep
    - source_labels: [__meta_kubernetes_namespace]
      regex: default
      action: keep
    - source_labels: [__meta_kubernetes_pod_container_port_number]
      regex:
      action: drop

记录规则和警报

配置警报和记录规则的格式已更改为YAML。旧格式的记录规则和警报示例：

job:request_duration_seconds:histogram_quantile99 =
  histogram_quantile(0.99, sum(rate(request_duration_seconds_bucket[1m])) by (le, job))

ALERT FrontendRequestLatency
  IF job:request_duration_seconds:histogram_quantile99{job="frontend"} > 0.1
  FOR 5m
  ANNOTATIONS {
    summary = "High frontend request latency",
  }

看起来像这样：

groups:
- name: example.rules
  rules:
  - record: job:request_duration_seconds:histogram_quantile99
    expr: histogram_quantile(0.99, sum(rate(request_duration_seconds_bucket[1m]))
      BY (le, job))
  - alert: FrontendRequestLatency
    expr: job:request_duration_seconds:histogram_quantile99{job="frontend"} > 0.1
    for: 5m
    annotations:
      summary: High frontend request latency

为了帮助进行更改，该promtool工具提供了一种自动转换规则的模式。给定一个.rules文件，它将.rules.yml以新格式输出文件。例如：

$ promtool update rules example.rules

请注意，您将需要使用2.0版而非1.8版的promtool。

存储

Prometheus 2.0中的数据格式已完全更改，并且与1.8不向后兼容。为了保留对历史监视数据的访问权限，我们建议您与Prometheus 2.0实例并行运行至少运行1.8.1版本的非抓取Prometheus实例，并让新服务器通过远程读取协议从旧服务器读取现有数据。

您的Prometheus 1.8实例应使用以下标志和仅包含external_labels设置（如果有）的配置文件启动：

$ ./prometheus-1.8.1.linux-amd64/prometheus -web.listen-address ":9094" -config.file old.yml

然后可以使用以下标志（在同一台计算机上）启动Prometheus 2.0：

$ ./prometheus-2.0.0.linux-amd64/prometheus --config.file prometheus.yml

其中prometheus.yml除了包含现有的完整配置，该节：

remote_read:
  - url: "http://localhost:9094/api/v1/read"

PromQL

以下功能已从PromQL中删除：

  • drop_common_labels函数- without应该使用聚合修饰符代替。
  • keep_common聚合修饰符- by应该改用修饰符。
  • count_scalar功能-用例可以通过absent()操作中的标签更好地处理或正确传播标签。

有关更多详细信息，请参见问题＃3060。

杂

Prometheus非root用户

现在已构建Prometheus Docker映像，以非root用户身份运行Prometheus。如果您希望Prometheus UI / API在低端口号（例如，端口80）上侦听，则需要覆盖它。对于Kubernetes，您将使用以下YAML：

apiVersion: v1
kind: Pod
metadata:
  name: security-context-demo-2
spec:
  securityContext:
    runAsUser: 0
...

有关 更多详细信息，请参见为Pod或容器配置安全上下文。

如果您使用的是Docker，则将使用以下代码段：

docker run -u root -p 80:80 prom/prometheus:v2.0.0-rc.2  --web.listen-address :80

普罗米修斯生命周期

如果您使用Prometheus /-/reloadHTTP端点在更改时自动重新加载Prometheus配置，则出于安全原因在Prometheus 2.0中默认禁用这些端点。要启用它们，请设置--web.enable-lifecycle标志。

API稳定性保证

Prometheus承诺API会在主要版本中保持稳定，并努力避免破坏关键功能的更改。某些功能（例如装饰性的，仍在开发中或依赖于第三方服务的功能）不在此范围内。

对于2.x来说稳定的事情是：

  • 查询语言和数据模型
  • 警报和记录规则
  • 摄取展示格式
  • v1 HTTP API（由仪表板和UI使用）
  • 配置文件格式（减去服务发现远程读/写，请参见下文）
  • 规则/警报文件格式
  • 控制台模板语法和语义

对于2.x来说不稳定的事情是：

  • 列为实验性或可能更改的任何功能，包括：
  • 服务发现集成，但static_configs和file_sd_configs
  • Go属于服务器的软件包的API
  • Web UI生成的HTML
  • Prometheus本身的/ metrics端点中的指标
  • 精确的磁盘格式。但是，潜在的更改将由Prometheus向前兼容并透明地处理
  • 日志格式

只要您不使用任何标记为试验性/不稳定的功能，通常就可以在没有任何操作调整的情况下执行主要版本内的升级，并且几乎不会有任何损坏的风险。任何重大更改将CHANGE在发行说明中标记为。

可视化

 表情浏览器

表达式浏览器可在/graphPrometheus服务器上找到，该表达式浏览器使您可以输入任何表达式，并随时间在表中或以图形方式查看其结果。

这主要用于临时查询和调试。对于图形，请使用 Grafana或控制台模板。

GRAFANA对PROMETHEUS的支持

Grafana支持查询Prometheus。自Grafana 2.5.0（2015-10-28）开始包含Prometheus的Grafana数据源。

下面显示了示例Grafana仪表板，该仪表板查询Prometheus以获取数据：

Grafana屏幕截图

正在安装

要安装Grafana，请参阅Grafana官方文档。

使用

默认情况下，Grafana将在http：// localhost：3000上监听 。默认登录名是“ admin” /“ admin”。

创建Prometheus数据源

要创建Prometheus数据源：

  1. 单击Grafana徽标以打开侧边栏菜单。
  2. 单击边栏中的“数据源”。
  3. 点击“添加新”。
  4. 选择“ Prometheus”作为类型。
  5. 设置适当的Prometheus服务器网址（例如，http://localhost:9090/）
  6. 根据需要调整其他数据源设置（例如，关闭代理访问）。
  7. 单击“添加”以保存新的数据源。

下面显示了示例数据源配置：

数据源配置

创建普罗米修斯图

遵循添加新Grafana图的标准方法。然后：

  1. 单击图形标题，然后单击“编辑”。
  2. 在“指标”标签下，选择您的Prometheus数据源（右下）。
  3. 在“查询”字段中输入任何Prometheus表达式，同时使用“指标”字段通过自动补全查找指标。
  4. 要格式化时间序列的图例名称，请使用“图例格式”输入。例如，要仅显示返回的查询结果的method和status标签，并用破折号分隔，可以使用图例格式字符串 {{method}} - {{status}}。
  5. 调整其他图形设置，直到可以使用图形为止。

下面显示了Prometheus图配置示例：普罗米修斯图的创建

从Grafana.com导入预构建的仪表板

Grafana.com维护着一组共享仪表板 ，这些仪表板可以下载并与Grafana的独立实例一起使用。使用Grafana.com的“过滤器”选项仅浏览仪表板中的“ Prometheus”数据源。

当前，您必须手动编辑下载的JSON文件并更正 datasource:条目，以反映为Prometheus服务器选择的Grafana数据源名称。使用“仪表板”→“主页”→“导入”选项将已编辑的仪表板文件导入到您的Grafana安装中。

控制台模板

控制台模板允许使用Go模板语言创建任意控制台。这些是从Prometheus服务器提供的。

控制台模板是创建可在源代码管理中轻松管理的模板的最强大方法。不过，这是一条学习曲线，因此刚接触这种监视方式的用户应首先尝试使用 Grafana。

入门

Prometheus附带了一组示例控制台，助您一臂之力。这些可以在/consoles/index.html.example正在运行的Prometheus上找到，并且如果Prometheus正在用job="node"标签抓取Node Exporters时将显示Node Exporter控制台 。

示例控制台包含5个部分：

  1. 顶部的导航栏
  2. 左侧菜单
  3. 底部的时间控制
  4. 中心的主要内容，通常是图形
  5. 右边的桌子

导航栏用于链接到其他系统，例如其他Prometheis 1，文档以及对您有意义的任何其他内容。该菜单用于在同一Prometheus服务器中进行导航，这对于能够快速打开另一个选项卡中的控制台以关联信息非常有用。两者都在中配置 console_libraries/menu.lib。

时间控件允许更改图表的持续时间和范围。控制台URL可以共享，其他URL将显示相同的图形。

主要内容通常是图形。提供了一个可配置的JavaScript图形库，该库将处理来自Prometheus的请求数据，并通过Rickshaw进行呈现。

最后，可以使用右侧的表格以比图表更紧凑的形式显示统计信息。

控制台示例

这是一个基本的控制台。它在右侧表中显示了任务数，任务数，平均CPU使用率和平均内存使用率。主要内容有一个“每秒查询”图。

{{template "head" .}}

{{template "prom_right_table_head"}}
<tr>
  <th>MyJob</th>
  <th>{{ template "prom_query_drilldown" (args "sum(up{job='myjob'})") }}
      / {{ template "prom_query_drilldown" (args "count(up{job='myjob'})") }}
  </th>
</tr>
<tr>
  <td>CPU</td>
  <td>{{ template "prom_query_drilldown" (args
      "avg by(job)(rate(process_cpu_seconds_total{job='myjob'}[5m]))"
      "s/s" "humanizeNoSmallPrefix") }}
  </td>
</tr>
<tr>
  <td>Memory</td>
  <td>{{ template "prom_query_drilldown" (args
       "avg by(job)(process_resident_memory_bytes{job='myjob'})"
       "B" "humanize1024") }}
  </td>
</tr>
{{template "prom_right_table_tail"}}


{{template "prom_content_head" .}}
<h1>MyJob</h1>

<h3>Queries</h3>
<div id="queryGraph"></div>
<script>
new PromConsole.Graph({
  node: document.querySelector("#queryGraph"),
  expr: "sum(rate(http_query_count{job='myjob'}[5m]))",
  name: "Queries",
  yAxisFormatter: PromConsole.NumberFormatter.humanizeNoSmallPrefix,
  yHoverFormatter: PromConsole.NumberFormatter.humanizeNoSmallPrefix,
  yUnits: "/s",
  yTitle: "Queries"
})
</script>

{{template "prom_content_tail" .}}

{{template "tail"}}

在prom_right_table_head与prom_right_table_tail模板包含右手边桌。这是可选的。

prom_query_drilldown是一个模板，它将评估传递给它的表达式，对其进行格式化并在表达式浏览器中链接到该表达式。第一个参数是表达式。第二个参数是要使用的单位。第三个参数是如何格式化输出。仅第一个参数是必需的。

第三个参数的有效输出格式prom_query_drilldown：

  • 未指定：默认Go显示输出。
  • humanize：使用度量标准前缀显示结果。
  • humanizeNoSmallPrefix：对于大于1的绝对值，请使用度量前缀显示结果。对于小于1的绝对值，请显示3个有效数字。这对于避免可能由每秒产生的单位（例如每秒的单位）很有用 humanize。
  • humanize1024：使用1024（而不是1000）的底数显示人性化的结果。通常将其与B第二个参数一起使用，以产生诸如KiB和的单位MiB。
  • printf.3g：显示3位有效数字。

可以定义自定义格式。有关示例，请参见 prom.lib。

图库

图形库的调用方式为：

<div id="queryGraph"></div>
<script>
new PromConsole.Graph({
  node: document.querySelector("#queryGraph"),
  expr: "sum(rate(http_query_count{job='myjob'}[5m]))"
})
</script>

该head模板将加载所需的Javascript和CSS。

图形库的参数：

名称描述
expr 需要。要表达的图形。可以是列表。
节点 需要。要渲染到的DOM节点。
持续时间 可选的。图的持续时间。默认为1小时。
时间结束 可选的。Unixtime图表结束于。默认为现在。
宽度 可选的。图的宽度，不包括标题。默认为自动检测。
高度 可选的。图形的高度，不包括标题和图例。默认为200像素。
分 可选的。最小x轴值。默认为最低数据值。
最大值 可选的。y轴最大值。默认为最高数据值。
渲染器 可选的。图的类型。选项是line和area（堆叠图）。默认为line。
名称 可选的。图例标题中的图例和悬停详细信息。如果传递了字符串，[[ label ]]则将替换为标签值。如果传递了一个函数，它将传递一个标签映射，并且应将名称作为字符串返回。可以是列表。
标题 可选的。x轴的标题。默认为Time。
单位 可选的。y轴的单位。默认为空。
标题 可选的。y轴的标题。默认为空。
yAxisFormatter 可选的。y轴的数字格式器。默认为PromConsole.NumberFormatter.humanize。
yHoverFormatter 可选的。悬停详细信息的数字格式化程序。默认为PromConsole.NumberFormatter.humanizeExact。
colorScheme 可选的。绘图要使用的配色方案。可以是十六进制颜色代码的列表，也可以是Rickshaw支持的颜色方案名称之一。默认为'colorwheel'。

如果expr和name均为列表，则它们的长度必须相同。该名称将应用于对应表达式的图。

为有效选项yAxisFormatter和yHoverFormatter：

  • PromConsole.NumberFormatter.humanize：使用度量标准前缀格式化。
  • PromConsole.NumberFormatter.humanizeNoSmallPrefix：对于大于1的绝对值，请使用度量标准前缀格式化。对于绝对值小于1的格式，请使用3个有效数字。这对于避免可能由每秒产生的单位（例如每秒的单位）很有用 PromConsole.NumberFormatter.humanize。
  • PromConsole.NumberFormatter.humanize1024：使用1024（而不是1000）的底数来格式化人性化的结果。

安全模式

Prometheus是一个复杂的系统，具有许多组件以及与其他系统的许多集成。它可以部署在各种受信任和不受信任的环境中。

本页介绍Prometheus的一般安全性假设以及某些配置可能启用的攻击媒介。

与任何复杂的系统一样，无法保证没有错误。如果您发现安全漏洞，请私下向相关存储库的MAINTAINERS.md和CC prometheus-team@googlegroups.com中列出的维护人员报告 。我们将解决问题并与您协调发布日期，确认您的努力并根据需要提及您的名字。

普罗米修斯

假定不受信任的用户可以访问Prometheus HTTP端点和日志。他们可以访问数据库中包含的所有时间序列信息，以及各种操作/调试信息。

还假定只有受信任的用户才能更改命令行，配置文件，规则文件以及Prometheus和其他组件的运行时环境的其他方面。

哪个目标针对Prometheus抓取，多久一次以及与其他什么设置完全通过配置文件确定。管理员可以决定使用来自服务发现系统的信息，将其与重新标记结合可以将某些控制权授予可以在该服务发现系统中修改数据的任何人。

废弃的目标可能由不受信任的用户运行。默认情况下，目标不应公开模拟其他目标的数据。该 honor_labels选项删除了此保护，某些重新标记设置也可以删除。

从Prometheus 2.0开始，该--web.enable-admin-api标志控制对管理HTTP API的访问，其中包括诸如删除时间序列之类的功能。默认情况下禁用。如果启用，则可以在/api/*/admin/路径下访问管理和更改功能。该 --web.enable-lifecycle标志控制Prometheus的HTTP重新加载和关闭。默认情况下也禁用此功能。如果启用，则可以在/-/reload和/-/quit路径下访问它们。

在普罗米修斯1.x中，/-/reload并使用DELETE上/api/v1/series都与访问HTTP API的任何人访问。该/-/quit端点被默认禁用，但可以通过启用-web.enable-remote-shutdown 标志。

远程读取功能允许具有HTTP访问权限的任何人将查询发送到远程读取端点。例如，如果PromQL查询最终直接在关系数据库上运行，那么任何能够将查询发送到Prometheus（例如通过Grafana）的人都可以对该数据库运行任意SQL。

警报经理

有权访问Alertmanager HTTP端点的任何用户都可以访问其数据。他们可以创建和解决警报。他们可以创建，修改和删除静默。

通知发送到的位置由配置文件确定。使用某些模板设置，通知有可能最终到达警报定义的目的地。例如，如果通知使用警报标签作为目标电子邮件地址，则可以将警报发送到Alertmanager的任何人都可以将通知发送到任何电子邮件地址。如果警报定义的目的地是可模板化的秘密字段，则有权访问Prometheus或Alertmanager的任何人都可以查看该秘密。

在以上用例中，任何可模板化的秘密字段均用于路由通知。它们不旨在用作使用模板文件功能将机密与配置文件分离开的方法。能够在Alertmanager配置文件中配置接收器的任何人都可以泄露模板文件中存储的所有机密。例如，在大型设置中，每个团队都可能有一个他们完全控制的alertmanager配置文件片段，然后将其组合成完整的最终配置文件。

Pushgateway

有权访问Pushgateway HTTP端点的任何用户都可以创建，修改和删除其中包含的指标。由于通常honor_labels禁用了Pushgateway ，因此这意味着有权访问Pushgateway的任何人都可以在Prometheus中创建任何时间序列。

该--web.enable-admin-api标志控制对管理HTTP API的访问，该管理HTTP API包括清除所有现有度量标准组之类的功能。默认情况下禁用。如果启用，则可以在/api/*/admin/路径下访问管理功能。

出口商

导出器通常仅与具有一组预设的命令/请求的配置实例进行对话，而这些命令/请求无法通过其HTTP端点进行扩展。

还有一些导出程序，例如SNMP和Blackbox导出程序，它们从URL参数获取目标。因此，对这些导出器具有HTTP访问权限的任何人都可以使它们将请求发送到任意端点。由于它们还支持客户端身份验证，因此可能导致诸如HTTP基本身份验证密码或SNMP社区字符串之类的机密泄漏。质询响应身份验证机制（例如TLS）不受此影响。

客户图书馆

客户端库旨在包含在用户的应用程序中。

如果使用客户端库提供的HTTP处理程序，则到达该处理程序的恶意请求应该不会引起超出额外负载和无效刮擦所导致的问题。

身份验证，授权和加密

Prometheus及其组件不提供任何服务器端身份验证，授权或加密。如果您需要这样做，建议使用反向代理。

由于打算通过简单的工具（例如cURL）访问管理和更改端点，因此没有内置的 CSRF保护，因为这会破坏此类用例。因此，在使用反向代理时，您可能希望阻止此类路径以防止CSRF。

对于非变异的端点，您可能希望在反向代理中设置CORS标头， Access-Control-Allow-Origin以防止 XSS。

如果您要编写包含不信任用户（例如，URL参数到控制台模板或您自己创建的东西）的输入的PromQL查询，但这些输入不希望能够运行任意PromQL查询，请确保适当地转义了任何不受信任的输入以防止注入攻击。例如up{job="<user_input>"}，up{job=""} or some_metric{zzz=""}如果<user_input>was，则将变为"} or some_metric{zzz="。

对于使用Grafana的用户，请注意，仪表板权限不是数据源权限，因此不要限制用户以代理方式运行任意查询的能力。

各种Prometheus组件均支持客户端身份验证和加密。如果提供TLS客户端支持，则通常还会有一个名为的选项insecure_skip_verify，该选项会跳过SSL验证。

机密

非秘密信息或字段可能通过HTTP API和/或日志可用。

在Prometheus中，从服务发现中检索的元数据不被视为秘密。在整个Prometheus系统中，度量标准不被视为秘密。

配置文件中包含机密的字段（在文档中已明确标记）不会在日志中或通过HTTP API公开。机密不应该放在其他配置字段中，因为组件通常会在其HTTP端点上公开其配置。

依赖项所使用的其他来源的秘密（例如AWS_SECRET_KEY ，EC2服务发现所使用的环境变量）可能最终由于我们控制之外的代码或由于恰好暴露于存储在任何地方的功能而最终暴露出来。

拒绝服务

对于超负荷或昂贵的查询，有一些缓解措施。但是，如果提供的查询/指标太多或太昂贵，组件将崩溃。受信任的用户比恶意行为更容易意外取出组件。

用户有责任确保为组件提供足够的资源，包括CPU，RAM，磁盘空间，IOPS，文件描述符和带宽。

建议监视所有组件的故障，并让它们在故障时自动重新启动。

图书馆

本文考虑从原始源代码构建的原始二进制文件。如果您修改Prometheus源代码或在自己的代码中使用Prometheus内部构件（超出官方客户端库API），则此处提供的信息不适用。

建立过程

Prometheus的构建管道在第三方提供程序上运行，Prometheus开发团队的许多成员以及这些提供程序的人员都可以访问第三方提供程序。如果您担心二进制文件的确切来源，建议您自己构建它们，而不要依赖项目提供的预构建二进制文件。

外部审计

CNCF赞助由外部安全审计 cure53跑从2018年4月至2018年6月。

有关更多详细信息，请阅读审核的 最终报告。

整合方式

In addition to client libraries and exporters and related libraries, there are numerous other generic integration points in Prometheus. This page lists some of the integrations with these.

Not all integrations are listed here, due to overlapping functionality or still being in development. The exporter default port wiki page also happens to include a few non-exporter integrations that fit in these categories.

File Service Discovery

For service discovery mechanisms not natively supported by Prometheus, file-based service discovery provides an interface for integrating.

Remote Endpoints and Storage

The remote write and remote read features of Prometheus allow transparently sending and receiving samples. This is primarily intended for long term storage. It is recommended that you perform careful evaluation of any solution in this space to confirm it can handle your data volumes.

Alertmanager Webhook Receiver

For notification mechanisms not natively supported by the Alertmanager, the webhook receiver allows for integration.

Management

Prometheus does not include configuration management functionality, allowing you to integrate it with your existing systems or build on top of it.

  • Prometheus Operator: Manages Prometheus on top of Kubernetes
  • Promgen: Web UI and configuration generator for Prometheus and Alertmanager

Other

  • karma: alert dashboard
  • PushProx: Proxy to transverse NAT and similar network setups
  • Promregator: discovery and scraping for Cloud Foundry applications

 仪器仪表

客户端库

在监视服务之前，您需要通过Prometheus客户端库之一在其代码中添加规范。这些实现Prometheus 度量类型。

选择与您的应用程序编写语言相匹配的Prometheus客户端库。这使您可以通过应用程序实例上的HTTP端点定义和公开内部指标：

非官方的第三方客户端库：

当Prometheus抓取您实例的HTTP端点时，客户端库会将所有跟踪指标的当前状态发送到服务器。

如果没有适用于您的语言的客户端库，或者您想避免依赖关系，则您也可以自己实施一种受支持的展示格式以公开指标。

实施新的Prometheus客户端库时，请遵循有关编写客户端库的 准则。请注意，该文档仍在开发中。也请考虑咨询开发邮件列表。我们很乐意就如何使您的图书馆尽可能有用和一致提供建议。

本文档是开源的。请通过提出问题或提出请求

编写客户端库

本文档涵盖了Prometheus客户端库应提供的功能和API，目的是在各个库之间保持一致，从而简化易用案例，并避免提供可能导致用户走错路的功能。

在撰写本文时，已经支持了10种语言，因此，到目前为止，我们已经很好地了解了如何编写客户端。这些准则旨在帮助新客户端库的作者创建良好的库。

约定

必须/必须/应该/应该/应该/不具有https://www.ietf.org/rfc/rfc2119.txt中给出的含义

另外，ENCOURAGED意味着该功能是图书馆拥有的理想功能，但是如果没有该功能就可以。换句话说，很高兴。

注意事项：

  • 充分利用每种语言的功能。

  • 常见的用例应该很容易。

  • 做某事的正确方法应该是简单的方法。

  • 更复杂的用例应该是可能的。

常见的用例是（按顺序）：

  • 没有标签的计数器在库/应用程序中广泛分布。

  • 时序/摘要/直方图中的代码块。

  • 跟踪事物当前状态（及其极限）的量规。

  • 监视批处理作业。

整体结构

客户必须在内部被编写为基于回调的。客户通常应遵循此处描述的结构。

关键类是收集器。该方法具有一种返回零个或多个指标及其样本的方法（通常称为“收集”）。收集器已在CollectorRegistry中注册。通过将CollectorRegistry传递给类/方法/函数“桥”来公开数据，该类以Prometheus支持的格式返回度量。每次回收CollectorRegistry时，都必须回调到每个Collector的collect方法。

大多数用户与之交互的界面是计数器，量规，汇总和直方图收集器。这些仅代表一个度量标准，并且应涵盖用户正在编写自己的代码的绝大多数用例。

更高级的用例（例如，来自另一个监视/仪器系统的代理）需要编写自定义收集器。可能还需要有人写一个“桥接器”，它采用CollectorRegistry，并以另一种监视/仪器系统所理解的格式生成数据，从而使用户只需要考虑一个仪器系统即可。

CollectorRegistry应该提供register()/ unregister()功能，并且应该允许CollectorRegistry注册到多个CollectorRegistrys。

客户端库必须是线程安全的。

对于非OO语言（例如C），客户端库应尽可能遵循这种结构的精神。

命名

客户端库应该遵循本文档中提到的函数/方法/类的名称，并牢记它们所使用语言的命名约定。例如，set_to_current_time()对于方法名称Python来说SetToCurrentTime()是好的，但是在Go语言中更好，并且setToCurrentTime()是约定在Java中。如果名称由于技术原因（例如，不允许函数重载）而有所不同，则文档/帮助字符串应将用户指向其他名称。

库不得提供与此处给出的名称相同或相似的函数/方法/类，但具有不同的语义。

指标

“计数器”，“量规”，“摘要”和“直方图” 度量标准类型是用户的主要界面。

Counter和Gauge必须是客户端库的一部分。必须至少提供摘要和直方图之一。

这些应主要用作文件静态变量，即，与要检测的代码在同一文件中定义的全局变量。客户端库应该启用它。常见的用例是整体检测一段代码，而不是在一个对象实例的上下文中检测一段代码。用户不必担心在整个代码中遍历其指标，客户端库应为他们做到这一点（如果没有，则用户将在库周围编写包装程序以使其“更容易”-很少会这样做）顺利）。

必须有一个默认的CollectorRegistry，默认情况下，标准指标必须隐式地注册到其中，而无需用户进行任何特殊工作。必须有一种方法可以使度量标准不注册到默认的CollectorRegistry中，以供批处理作业和单元测试中使用。定制收集者也应遵循此规则。

确切如何创建度量标准因语言而异。对于某些（Java，Go）而言，构建器方法是最好的，而对于另一些（Python），函数参数足够丰富，可以一次调用。

例如，在Java Simpleclient中，我们有：

class YourClass {
  static final Counter requests = Counter.build()
      .name("requests_total")
      .help("Requests.").register();
}

这将使用默认的CollectorRegistry注册请求。通过调用 build()而不是register()度量将不会被注册（对于单元测试很方便），您还可以将CollectorRegistry传递给register()（对于批处理作业很方便）。

计数器

计数器是单调递增的计数器。它必须不允许该值减小，但是可以将其重置为0（例如通过服务器重新启动）。

计数器必须具有以下方法：

  • inc()：将计数器加1
  • inc(double v)：将计数器增加给定的数量。必须检查v> = 0。

鼓励使用计数器：

一种计数在给定代码段中引发/引发的异常的方法，并且可以选择仅计数某些类型的异常。这是Python中的count_exceptions。

计数器必须从0开始。

量规

量表代表可以上升和下降的值。

量规必须具有以下方法：

  • inc()：将量规增加1
  • inc(double v)：将量规增加给定的数量
  • dec()：将压力表减1
  • dec(double v)：将量规减小给定的数量
  • set(double v)：将量规设置为给定值

量规必须从0开始，您可以为给定量规提供从其他数字开始的方法。

量规应具有以下方法：

  • set_to_current_time()：将仪表设置为当前的unixtime（以秒为单位）。

鼓励使用量规：

一种跟踪某些代码/函数中正在进行的请求的方法。这是 track_inprogress在Python中。

一种计时代码并将仪表设定为持续时间（以秒为单位）的方法。这对于批处理作业很有用。这是Java中的startTimer / setDuration和time()Python中的 装饰器/上下文管理器。该值应与“摘要/直方图”中的模式匹配（尽管set()不是observe()）。

摘要

甲摘要样品观察随滑动时间窗（例如请求的持续时间通常的东西），并提供瞬时洞察其分布，频率和求和。

摘要必须禁止用户将“分位数”设置为标签名称，因为该名称在内部用于指定摘要分位数。鼓励提供摘要，以将分位数作为出口提供，尽管这些分位数不能汇总，而且往往很慢。摘要必须不允许分位数，因为_count/ _sum非常有用，并且必须是默认值。

摘要必须具有以下方法：

  • observe(double v)：观察给定的数量

摘要应具有以下方法：

一种以秒为单位给用户计时的方法。在Python中，这是time() 装饰器/上下文管理器。在Java中，这是startTimer / observeDuration。绝不能提供秒以外的单位（如果用户需要其他东西，他们可以手工完成）。这应遵循与“量规/直方图”相同的模式。

摘要_count/ _sum必须从0开始。

直方图

直方图允许事件的汇总分布，例如请求延迟。这是每桶计数器的核心。

直方图不得le用作用户设置的标签，因为le它在内部用于指定存储分区。

直方图必须提供一种手动选择存储桶的方法。应该提供将桶设置为linear(start, width, count)和exponential(start, factor, count)时尚的方式。计数必须排除+Inf存储桶。

直方图应具有与其他客户端库相同的默认存​​储区。指标一旦创建，便不得更改。

直方图必须具有以下方法：

  • observe(double v)：观察给定的数量

直方图应具有以下方法：

一种以秒为单位给用户计时的方法。在Python中，这是time() 装饰器/上下文管理器。在Java中，这是startTimer/ observeDuration。绝不能提供秒以外的单位（如果用户需要其他东西，他们可以手工完成）。这应该遵循与“量规/摘要”相同的模式。

直方图 _count/ _sum，并且桶必须从0开始。

其他指标注意事项

鼓励使用超出上述说明范围的度量标准提供其他功能。

如果有常见的用例，则可以简化它，只要它不会鼓励不良行为（例如，次优的度量标准/标签布局或在客户端进行计算）。

标签

标签是Prometheus 最强大的方面之一，但 很容易被滥用。因此，客户端库在如何向用户提供标签时必须非常小心。

在任何情况下，客户端库都绝对不允许用户为同一度量标准（计量器/计数器/汇总/直方图）或库提供的任何其他收集器使用不同的标签名称。

来自定制收集器的度量标准几乎应该始终具有一致的标签名称。由于仍然有少数情况但有效的用例并非如此，因此客户端库不应对此进行验证。

虽然标签功能强大，但大多数指标都没有标签。因此，API应该允许标签但不能控制标签。

客户端库必须允许在创建标尺/计数器/摘要/直方图时可选地指定标签名称的列表。客户端库应该支持任意数量的标签名称。客户端库必须验证标签名称是否满足文档要求。

提供对度量的标注维度的访问的一般方法是通过以下 labels()方法：获取标签值的列表或从标签名称到标签值的映射，然后返回“子级”。通常 .inc()/ .dec()/ .observe()等方法然后可以对孩子叫。

labels()用户返回的Child 应该可以被用户缓存，以避免不得不再次查找-这对于延迟关键的代码很重要。

带有标签的指标应支持一种remove()签名相同的方法，该方法labels()将不再从度量标准中删除子级，而从子级clear()中删除所有子级的方法。这些使子级的缓存无效。

应该有一种用默认值初始化给定Child的方法，通常只需调用即可labels()。没有标签的度量必须总是被初始化以避免度量缺失的问题。

指标名称

指标名称必须遵循 规范。与标签名称一样，对于量具/计数器/摘要/直方图以及库提供的任何其他收集器，都必须满足此要求。

许多客户端库都提供了三部分来设置名称： namespace_subsystem_name其中只有name必填项。

除了自定义收集器正在从其他工具/监视系统代理的情况下，必须不要使用动态/生成的度量标准名称或度量标准名称的子部分。生成的/动态的度量标准名称表明您应该使用标签。

指标描述和帮助

量具/计数器/摘要/直方图必须要求提供量具描述/帮助。

客户端库随附的任何自定义收集器都必须具有关于其指标的描述/帮助。

建议将其设为必选参数，但不要检查它是否具有一定长度，就好像某人真的不想编写文档一样，我们也不会说服他们。图书馆（以及我们在生态系统中可以到达的所有地方）提供的收集器应具有良好的度量描述，以身作则。

展览会

客户必须实施博览会格式文档中概述的基于文本的 博览会格式。

如果可以在不花费大量资源成本的情况下实施公开指标，则可重现公开指标的顺序（尤其是对于人类可读格式）。

标准和运行时收集器

客户库应该提供标准导出的功能，如下所述。

这些应作为自定义收集器实现，并默认在默认的CollectorRegistry上注册。应该有一种禁用这些功能的方法，因为在某些非常特殊的用例中，它们会受到阻碍。

流程指标

这些度量标准具有前缀process_。如果使用所使用的语言或运行时获取必要的值是有问题的，甚至是不可能的，则客户端库应该宁愿忽略相应的度量标准，而不要输出伪造的，不准确的或特殊的值（例如NaN）。所有内存值以字节为单位，所有时间以unixtime / seconds为单位。

指标名称帮助字符串单元
process_cpu_seconds_total 用户和系统的CPU总时间，以秒为单位。 秒
process_open_fds 打开文件描述符的数量。 文件描述符
process_max_fds 打开文件描述符的最大数量。 文件描述符
process_virtual_memory_bytes 虚拟内存大小（以字节为单位）。 个字节
process_virtual_memory_max_bytes 最大可用虚拟内存量（以字节为单位）。 个字节
process_resident_memory_bytes 驻留内存大小（以字节为单位）。 个字节
process_heap_bytes 进程堆大小（以字节为单位）。 个字节
process_start_time_seconds 从Unix纪元开始的进程开始时间（以秒为单位）。 秒

运行时指标

此外，客户端库鼓励也提供任何有意义的度量他们的语言的运行时的条件（如：垃圾收集统计），用适当的前缀，如go_，hotspot_等。

单元测试

客户库应该有涵盖核心仪器库和说明的单元测试。

鼓励使用客户端库，以提供使用户易于对其使用规范代码进行单元测试的方法。例如， CollectorRegistry.get_sample_value在Python中。

打包和依赖

理想情况下，客户端库可以包含在任何应用程序中，以在不破坏应用程序的情况下添加一些工具。

因此，在向客户端库添加依赖项时，建议谨慎。例如，如果添加的库使用的Prometheus客户端需要库的xy版本，而应用程序在其他地方使用xz，那么这会对应用程序产生不利影响吗？

建议在可能出现这种情况的情况下，将核心工具与给定格式的度量标准的桥梁/展示分开。例如，Java simpleclient simpleclient模块没有依赖项，并且simpleclient_servlet具有HTTP位。

性能考量

由于客户端库必须是线程安全的，因此需要某种形式的并发控制，并且必须考虑多核计算机和应用程序上的性能。

根据我们的经验，性能最低的是互斥体。

处理器原子指令通常位于中间，并且通常可以接受。

避免不同的CPU改变RAM的相同位的方法效果最好，例如Java的simpleclient中的DoubleAdder。虽然有内存消耗。

如上所述，的结果labels()应该是可缓存的。倾向于使用标签进行后度量的并发映射往往相对较慢。没有标签的特殊外壳度量标准可以避免labels()类似的查找，这很有帮助。

指标在增加/减少/设置等时应避免阻塞，因为在抓取过程中不希望整个应用程序被阻塞。

鼓励对主要仪器操作（包括标签）进行基准测试。

进行博览会时应牢记资源消耗，尤其是RAM。考虑通过流传输结果减少内存占用量，并可能限制并发刮擦次数。

推动指标

有时，您将需要监视无法报废的组件。该 普罗米修斯Pushgateway允许你从推时间序列短暂的服务水平批处理作业到中介工作，这普罗米修斯能刮。结合Prometheus的基于文本的简单展示格式，即使没有客户端库，也可以轻松编写甚至是shell脚本。

出口商和整合

有许多库和服务器可帮助将第三方系统中的现有指标导出为Prometheus指标。这对于无法直接使用Prometheus指标（例如HAProxy或Linux系统统计信息）来检测给定系统的情况很有用。

第三方出口商

其中一些出口商作为Prometheus GitHub官方组织的一部分进行维护，其中一些被标记为正式出口商，其他出口商则由外部贡献和维护。

我们鼓励创建更多的出口商，但不能审查所有出口商的 最佳做法。通常，这些出口商托管在Prometheus GitHub组织之外。

该出口默认端口 维基页面已经成为出口的另一个目录中，并可能包括由于功能重叠或仍处于开发阶段是此处未列出的出口商。

该JMX出口国可以从各种基于JVM的应用程序中导出，例如卡夫卡和 卡桑德拉。

资料库

问题跟踪器和持续集成

讯息系统

存储

HTTP

蜜蜂

记录中

其他监控系统

杂

实施新的Prometheus出口商时，请遵循有关编写出口商的 指导原则。 也请考虑参考开发邮件列表。我们很乐意就如何使您的出口商尽可能有用和一致提供建议。

公开Prometheus指标的软件

一些第三方软件以Prometheus格式公开指标，因此不需要单独的导出器：

标有Direct的软件也可以直接用Prometheus客户端库进行检测。

其他第三方实用程序

本节列出了可帮助您使用某种语言来编写代码的库和其他实用程序。它们本身不是Prometheus客户端库，而是利用内部的常规Prometheus客户端库之一。对于所有独立维护的软件，我们无法审查所有软件以获得最佳实践。

WRITING EXPORTERS

如果您要编写自己的代码，则应遵循有关如何使用Prometheus客户端库进行代码编写的一般规则。当从另一个监视或仪器系统中获取度量标准时，事情往往不会那么黑。

本文档包含编写导出器或自定义收集器时应考虑的事项。涉及的理论也将对那些直接进行仪器测试的人感兴趣。

如果您正在编写导出程序，并且不清楚此处的内容，请通过IRC（Freenode上的#prometheus）或邮件列表与我们联系。

可维护性和纯度

编写导出程序时，您需要做出的主要决定是，您愿意投入多少工作才能从中获得完美的指标。

如果所讨论的系统只有很少量度的度量标准，那么使所有事情都变得完美是一个容易的选择，HAProxy导出器就是一个很好的例子。

另一方面，如果您试图在系统具有数百个随新版本而频繁变化的指标时使事情变得完美，那么您已经为许多正在进行的工作注册了自己。在MySQL的出口是在光谱的这一端。

的节点出口是这些的组合，与由模块的复杂性而变化。例如， mdadm收集器手动解析文件并公开专门为该收集器创建的指标，因此我们也可以正确获取指标。对于meminfo收集器而言，结果因内核版本而异，因此我们最终仅进行了足够的转换即可创建有效的指标。

组态

使用应用程序时，您应该针对不需要用户自定义配置的导出程序，而无需告诉应用程序在哪里。如果某些指标在大型设置中可能过于精细和昂贵，则可能还需要提供过滤这些指标的功能，例如HAProxy导出器允许按服务器统计信息过滤。同样，默认情况下可能会禁用昂贵的指标。

与其他监视系统，框架和协议配合使用时，您通常需要提供其他配置或自定义，以生成适用于Prometheus的指标。在最佳情况下，监视系统具有与Prometheus类似的数据模型，您可以自动确定如何转换指标。Cloudwatch， SNMP和 Collected就是这种情况。最多，我们需要能够让用户选择他们想要提取的指标的能力。

在其他情况下，取决于系统和基础应用程序的使用情况，来自系统的度量标准完全是非标准的。在这种情况下，用户必须告诉我们如何转换指标。该JMX出口是最明显的案例，用 石墨和 StatsD出口商也需要配置提取标签。

确保出口商无需配置即可开箱即用，并建议在需要时提供一些示例配置供转换。

YAML是标准的Prometheus配置格式，默认情况下，所有配置都应使用YAML。

指标

命名

遵循度量标准命名的最佳做法。

通常，度量标准名称应允许熟悉Prometheus而不是特定系统的人对度量标准的含义做出很好的猜测。名为的度量标准http_requests_total不是非常有用-是在传入，过滤器中或到达用户代码时对其进行测量吗？而且requests_total更糟糕的，要求的是什么类型？

使用直接检测，给定的度量标准应恰好存在于一个文件中。因此，在出口商和收集者中，一个度量标准应该恰好适用于一个子系统并相应地命名。

除编写自定义收集器或导出器时外，永远不要以程序方式生成度量标准名称。

应用程序的度量标准名称通常应以出口者名称为前缀，例如haproxy_up。

指标必须使用基本单位（例如，秒，字节），并保留将其转换为图形工具更易读的内容。无论最终使用什么单位，度量标准名称中的单位都必须与使用中的单位匹配。同样，公开比率，而不是百分比。更好的是，为比率的两个分量中的每个分量指定一个计数器。

度量标准名称不应包含与它们一起导出的标签，例如by_type，因为如果标签被聚合掉，则没有意义。

一个例外是，当您通过多个指标导出带有不同标签的相同数据时，在这种情况下，通常这是区分它们的最明智的方法。对于直接检测，仅当导出带有所有标签的单个度量标准的基数过高时，才应该出现这种情况。

Prometheus度量标准和标签名称以编写snake_case。转换camelCase到snake_case是可取的，但这样做会自动并不总是产生的东西像好的结果 myTCPExample还是isNaN如此，有时，最好给他们留下原样。

暴露的指标不应包含冒号，这些保留给用户定义的记录规则，以便在聚合时使用。

仅[a-zA-Z0-9:_]在度量标准名称中有效，任何其他字符都应清除为下划线。

的_sum，_count，_bucket和_total后缀由摘要，柱状图和计数器使用。除非您要制作其中之一，否则请避免使用这些后缀。

_total 是计数器的约定，如果使用COUNTER类型，则应使用它。

在process_和scrape_前缀被保留。如果它们遵循匹配的语义，则可以在这些前缀上添加自己的前缀。例如，普罗米修斯（Prometheus）scrape_duration_seconds花费了多长时间才得到报废，因此，最好还有一个以出口商为中心的度量标准，例如jmx_scrape_duration_seconds，说出特定出口商花费多长时间来完成任务。对于可以访问PID的过程统计信息，Go和Python都提供了收集器来为您处理。HAProxy导出器就是一个很好的例子。

当您有成功的请求计数和失败的请求计数时，最好的公开方法是针对总请求的一个度量标准和针对失败请求的另一个度量标准。这使得计算故障率变得容易。不要使用带有失败或成功标签的度量标准。同样，对于缓存命中或未命中，最好有一个指标作为总指标，而另一个指标为命中指标。

考虑使用监视的人将对度量名称进行代码或网络搜索的可能性。如果名称建立得很好，并且不太可能在习惯使用这些名称的人员（例如SNMP和网络工程师）的领域之外使用，那么将它们保持原样可能是个好主意。这种逻辑并不适用于所有导出器，例如，MySQL导出器度量标准可能被各种人使用，而不仅仅是DBA。一个HELP与原来的名称字符串可以提供大部分相同的好处使用原来的名字。

标签

阅读标签上的一般建议。

避免将其type作为标签名称使用，因为它太笼统且通常没有意义。你也应该尝试尽可能地避免有可能与目标的标签，如发生冲突的名称region，zone，cluster， availability_zone，az，datacenter，dc，owner，customer， stage，service，environment和env。但是，如果这就是应用程序所调用的资源，则最好不要通过重命名而引起混乱。

避免仅因为它们共享前缀就将它们放入一个度量标准的诱惑。除非您确定某一项指标有意义，否则多个指标会更安全。

标签le对于直方图和quantile摘要具有特殊含义。通常避免使用这些标签。

最好将读/写和发送/接收作为单独的指标，而不是作为标签。这通常是因为您一次只关心其中一个，并且使用它们更容易。

经验法则是，一个指标在求和或求平均值时应该有意义。导出器还有另外一种情况，那就是数据从根本上是表格格式的，否则，将需要用户对度量标准名称进行正则表达式才能使用。考虑一下主板上的电压传感器，尽管对它们进行数学运算是没有意义的，但将它们设置为一个度量而不是每个传感器具有一个度量是有意义的。度量标准内的所有值都应（几乎）始终具有相同的单位，例如，请考虑是否将风扇速度与电压混合在一起，并且您无法自动将它们分开。

不要这样做：

my_metric {label = a} 1
my_metric {label = b} 6
my_metric {label = total} 7

或这个：

my_metric {label = a} 1
my_metric {label = b} 6
my_metric {} 7

前者适合那些sum()超出您的指标的人，而后者适合于求和，并且很难使用。某些客户端库（例如Go）会主动尝试阻止您在自定义收集器中执行后者，而所有客户端库都应阻止您使用直接检测来执行后者。决不要做任何一个，而要依靠Prometheus聚合。

如果您的监控显示了这样的总数，请删除总数。如果由于某种原因必须保留它，例如，总计中包括未单独计数的内容，请使用不同的度量标准名称。

仪器标签应尽量少，每增加一个标签，用户在编写PromQL时就需要考虑一个标签。因此，请避免使用可以在不影响时间序列唯一性的情况下删除的仪器标签。可以通过信息指标添加有关指标的其他信息，例如，请参见下面的示例，了解如何处理版本号。

但是，在某些情况下，预计指标的几乎所有用户都需要附加信息。如果是这样，添加非唯一标签而不是信息指标是正确的解决方案。例如， mysqld_exporter的 mysqld_perf_schema_events_statements_total的digest标签是全查询模式的散列和就足够了唯一性。但是，如果没有人类可读的digest_text标签，该标签就没什么用了，长时间的查询将只包含查询模式的开头，因此不是唯一的。因此，我们最终得到了digest_text人类的digest标签和独特性的标签。

目标标签，而非静态刮擦标签

如果您发现自己想对所有指标应用相同的标签，请停止。

通常有两种情况。

第一个是用于某些标签的，具有度量标准（例如软件的版本号）将很有用。相反，请使用https://www.robustperception.io/how-to-have-labels-for-machine-roles/中描述的方法 。

第二种情况是标签实际上是目标标签。这些是区域，群集名称等，它们来自基础结构设置而不是应用程序本身。并不是说应用程序适合您的标签分类法，而是让运行Prometheus服务器的人员进行配置，并且监视同一应用程序的不同人员可能会给它使用不同的名称。

因此，这些标签通过您使用的任何服务发现都属于Prometheus的scrape配置中。在这里也可以应用机器角色的概念，因为这对于至少某些人来说可能是有用的信息。

种类

您应该尝试将指标的类型与Prometheus类型进行匹配。这通常意味着计数器和仪表。该_count和_sum 总结的也比较常见，有时你会看到位数。直方图很罕见，如果您遇到一个问题，请记住，博览会格式会公开累积值。

通常，度量标准的类型并不明显，尤其是当您自动处理一组度量标准时。通常UNTYPED 是安全的默认设置。

计数器不会下降，因此，如果您有一个来自其他可以递减的仪表系统的计数器类型，例如Dropwizard指标，则它不是计数器，而是一个量表。UNTYPED最好是在那里使用的最佳类型，GAUGE如果将其用作计数器会产生误导。

帮助字符串

当您转换指标时，用户能够追溯到原始内容以及导致转换发生的规则是很有用的。在收集器或导出器的名称中输入所应用的任何规则的ID，并将原始度量的名称和详细信息放入帮助字符串中，将极大地帮助用户。

Prometheus不喜欢一种具有不同帮助字符串的指标。如果您要从多个其他指标中选择一个指标，请选择其中一个指标以放入帮助字符串。

例如，SNMP导出器使用OID，而JMX导出器将输入示例mBean名称。该HAProxy的出口有手写的字符串。的节点出口也有各种各样的实施例。

减少有用的统计数据

mean除最小，最大和标准偏差外，某些仪器系统还公开了自应用程序启动以来的1m，5m，15m比率，平均比率（例如，在Dropwizard度量标准中称为“比率”）。

这些都应该删除，因为它们不是很有用，并且会增加混乱。普罗米修斯可以自己计算利率，并且通常可以更准确地计算利率，因为暴露的平均值通常呈指数衰减。您不知道计算最小值或最大值的时间，标准偏差在统计上是无用的，并且始终可以公开平方和，_sum以及_count是否需要计算平方 和。

分位数有相关问题，您可以选择删除或将其放在摘要中。

虚线

许多监视系统没有标签，而是执行 my.class.path.mymetric.labelvalue1.labelvalue2.labelvalue3。

该石墨和 StatsD出口商分享一个小配置语言转换这些的一种方式。其他出口商应实施相同的规定。该转换目前仅在Go中实现，并且将从分解成一个单独的库中受益。

收藏家

为出口商实施收集器时，切勿使用通常的直接检测方法，然后在每个刮板上更新指标。

而是每次都创建新的指标。在Go中，这是通过 您的方法中的MustNewConstMetric完成的 Collect()。对于Python，请参见 https://github.com/prometheus/client_python#custom-collectors ；对于Java List<MetricFamilySamples>，请在您的collect方法中生成， 有关示例，请参见 StandardExports.java。

其原因有两个。首先，可能同时发生两次刮擦，并且直接检测使用的是有效的文件级全局变量，因此您将获得竞争条件。其次，如果标签值消失了，它将仍然被导出。

可以通过直接检测对出口商本身进行检测，例如，传输的总字节数或出口商在所有报废中执行的调用。对于不与单个目标捆绑在一起的出口商（例如黑盒出口商和SMNP出口商），这些出口商仅应公开征求意见，而不应 /metrics刮擦某个特定目标。

有关刮擦本身的指标

有时，您想导出有关刮擦的指标，例如花费了多长时间或处理了多少条记录。

这些内容应以事件，刮擦和以出口商名称为前缀的度量标准名称的形式公开显示 jmx_scrape_duration_seconds。通常将_exporter排除在外，如果导出程序也可以用作收集器，则一定要排除它。

机器和过程指标

许多系统（例如Elasticsearch）都公开机器指标，例如CPU，内存和文件系统信息。当节点导出器在Prometheus生态系统中提供这些功能时，应删除此类指标。

在Java世界中，许多检测框架都公开进程级别和JVM级别的统计信息，例如CPU和GC。Java客户端和JMX导出器已经通过DefaultExports.java以首选形式包含了它们 ，因此也应该删除它们。

与其他语言和框架类似。

部署方式

每个出口商都应该准确地监视一个实例应用程序，最好直接坐在同一台机器上。这意味着您运行的每个HAProxy都会运行一个haproxy_exporter进程。对于每台配备Mesos工作程序的计算机，您都在其上运行Mesos导出程序，如果主计算机同时运行，则在主服务器上运行。

其背后的理论是，对于直接检测，这就是您要做的，并且我们正在尝试与其他布局尽可能接近。这意味着所有服务发现都在Prometheus中完成，而不是在出口商中完成。这还有一个好处，就是Prometheus拥有允许用户使用黑盒导出程序探查您的服务所需的目标信息。

有两个例外：

第一个是在应用程序旁边运行时，您的监视完全没有意义。SNMP，黑盒和IPMI导出器是其中的主要示例。IPMI和SNMP导出器通常是黑盒，无法在其上运行代码（尽管如果可以在它们上运行节点导出器，那会更好），而黑盒导出器则在其中监视诸如DNS名称，也没有任何内容可运行。在这种情况下，Prometheus仍应进行服务发现，并将要刮除的目标传递出去。有关示例，请参见黑盒和SNMP导出器。

请注意，目前只有使用Go，Python和Java客户端库编写这种类型的导出程序。

第二个例外是，您要从系统的随机实例中提取一些统计信息，而不必在意与之交谈的那个。考虑要对数据运行一些业务查询然后导出的一组MySQL副本。让出口商使用您通常的负载平衡方法与一个副本进行对话是最明智的方法。

当您监视具有主选举功能的系统时，此方法不适用，在这种情况下，您应该分别监视每个实例并处理Prometheus中的“主控权”。这是因为并不总是只有一个大师，改变普罗米修斯脚下的目标会引起奇怪。

排程

仅当Prometheus抓取度量标准时才将其从应用程序中拉出，出口商不应根据自己的计时器执行度量标准。也就是说，所有刮擦应该是同步的。

因此，您不应该在公开的指标上设置时间戳，让Prometheus负责。如果您认为需要时间戳记，则可能需要使用 Pushgateway 。

如果度量的检索成本特别高，即花费一分钟以上，则可以缓存它。这应该在HELP字符串中注明 。

Prometheus的默认刮擦超时为10秒。如果可以预期出口商会超过此数量，则应在用户文档中明确指出这一点。

推入

某些应用程序和监视系统仅推送指标，例如StatsD，Graphite和Collected。

这里有两个注意事项。

首先，您何时使指标过期？收集到的信息以及与Graphite进行对话的信息均会定期导出，并且当它们停止时，我们希望停止公开指标。收集的包含到期时间，因此我们可以使用它，而Graphite则不是，因此它是出口商的标志。

StatsD有点不同，因为它处理事件而不是度量。最好的模型是在每个应用程序旁边运行一个导出器，并在应用程序重新启动时重新启动它们，以便清除状态。

其次，这类系统倾向于允许您的用户发送增量或原始计数器。您应该尽可能地依赖原始计数器，因为这是常规的Prometheus模型。

对于服务级别的指标，例如服务级别的批处理作业，您应该让导出程序推入Pushgateway并在事件发生后退出，而不是自己处理状态。对于实例级批次指标，尚无明确的模式。这些选项要么是滥用节点导出器的文本文件收集器，要么依赖于内存中状态（如果您不需要在重新启动后保持不变，则可能是最好的选择），或者实现与文本文件收集器类似的功能。

刮擦失败

当前有两种刮刮失败模式，您正在与之交谈的应用程序没有响应或出现其他问题。

第一种是返回5xx错误。

第二个是要具有myexporter_up例如haproxy_up变量，其值取决于刮擦是否起作用，值为0或1。

后者更好，即使刮擦失败，您仍然可以获得一些有用的指标，例如提供过程统计信息的HAProxy导出程序。up尽管您无法区分导出器和应用程序都处于关闭状态，但前者通常会以一种通常的方式使用户更容易处理 。

登陆页面

如果访问时http://yourexporter/有一个简单的带有导出器名称的HTML页面以及指向该/metrics 页面的链接，则对用户来说更好。

端口号

一个用户可能在同一台计算机上有许多导出器和Prometheus组件，因此，使每个导出器和Prometheus组件具有唯一的端口号变得更加容易。

https://github.com/prometheus/prometheus/wiki/Default-port-allocations 是我们跟踪它们的地方，这是可公开编辑的。

开发出口商时，最好在公开宣布之前，获取下一个免费端口号。如果您尚未准备好发布，则可以输入用户名和WIP。

这是一个注册表，它使我们的用户的生活更加轻松，而不是致力于发展特定的出口商。对于内部应用程序的导出器，我们建议使用默认端口分配范围之外的端口。

宣布

准备好向全世界宣布出口商后，请向邮件列表发送电子邮件并发送PR，以将其添加到可用出口商列表中。

展览格式

可以使用基于文本的简单 展示格式将度量标准暴露给Prometheus 。有多种客户端库 可以为您实现这种格式。如果您的首选语言没有客户端库，则可以创建自己的客户端库。

注意： Prometheus的某些较早版本除了支持当前基于文本的格式外，还支持基于 协议缓冲区（又称Protobuf）的展示格式。但是，从2.0版开始，Prometheus不再支持基于Protobuf的格式。您可以在本文档中了解此更改背后的原因。

基于文本的格式

从Prometheus 2.0版开始，所有向Prometheus公开指标的过程都需要使用基于文本的格式。在本节中，您可以找到 有关此格式的一些基本信息以及该格式的更详细分类。

基础信息

方面描述
起始时间 2014年4月
受支持 普罗米修斯版本 >=0.4.0
传输 HTTP
编码方式 UTF-8，\n行尾
HTTP Content-Type text/plain; version=0.0.4（缺少version值将导致回退到最新的文本格式版本。）
可选的HTTP Content-Encoding gzip
优点
  • 人类可读
  • 易于组装，特别是对于简约的情况（无需嵌套）
  • 逐行可读（类型提示和文档字符串除外）
局限性
  • 详细
  • 类型和文档字符串不是语法的组成部分，这意味着几乎不存在度量标准合同验证
  • 解析费用
支持的度量原语
  • 计数器
  • 量规
  • 直方图
  • 摘要
  • 未输入

文字格式详细资料

Prometheus的基于文本的格式是面向行的。行之间用换行符（\n）分隔。最后一行必须以换行符结尾。空行将被忽略。

行格式

在一行中，令牌可以用任意数量的空格和/或制表符分隔（如果不与先前的令牌合并，则必须至少用一个分隔）。前导和尾随空格将被忽略。

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

以a #作为第一个非空白字符的行是注释。除非后面的第一个标记#为HELP或，否则将忽略它们TYPE。这些行的处理方式如下：如果令牌为HELP，则至少应该再有一个令牌，即度量名称。所有其余令牌都被视为该度量标准名称的文档字符串。HELP每行可以包含任何序列的UTF-8字符（在度量标准名称之后），但是反斜杠和换行符必须分别以\\和进行转义\n。HELP 对于任何给定的度量标准名称，只能存在一行。

如果令牌为TYPE，则还需要两个令牌。第一个是度量名称，第二或者是counter，gauge，histogram， summary，或untyped，限定类型的度量的名字。TYPE对于给定的度量标准名称，只能存在一行。TYPE度量标准名称的行必须出现在报告该度量标准名称的第一个样本之前。如果TYPE度量标准名称没有一行，则将类型设置为 untyped。

其余各行使用以下语法（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是表示不是数字，正无穷大，并且负无穷大，分别有效的值。
  • 的timestamp是一个int64（因为毫秒为单位，即，1970-01-01 00:00:00 UTC，不含闰秒）所要求的Go的表示ParseInt()功能。

分组和排序

给定指标的所有行都必须作为一个单独的组提供，其中可选行HELP和TYPE第一个行（无特定顺序）。除此之外，在重复博览会中可重现的排序是可取的，但不是必需的，即，如果计算成本过高，则不进行排序。

每行必须具有度量标准名称和标签的唯一组合。否则，摄取行为是不确定的。

直方图和摘要

该histogram和summary类型是很难在文本格式来表示。适用以下约定：

  • 名为的摘要或直方图的样本总和作为名为x的单独样本给出x_sum。
  • 名为的摘要或直方图的样本计数作为名为x的单独样本给出x_count。
  • 摘要的每个分位数以x具有相同名称x和标签的单独样本行给出{quantile="y"}。
  • 命名x为直方图的每个存储分区计数均作为单独的示例行给出，带有名称x_bucket和标签{le="y"}（其中y是存储分区的上限）。
  • 直方图必须包含的水桶{le="+Inf"}。其值必须与的值相同x_count。
  • 直方图的桶和摘要的分位数必须以其标签值（分别用于le或）的递增数字顺序出现quantile。

文字格式示例

下面是一个完整的普罗米修斯度量说明的示例，包括注释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 2693

 

历史版本

有关历史格式版本的详细信息，请参阅旧版“ 客户端数据公开格式” 文档。

相关资料

官方文档：https://prometheus.io/docs/prometheus/latest/getting_started/

posted @ 2020-03-08 16:02  麦奇  阅读(3740)  评论(0)  编辑  收藏  举报