prometheus-2
来源:官方文档。
配置文件
要指定要加载的配置文件,请使用--config.file
标志。
该文件以YAML 格式编写,由下面描述的方案定义。括号表示参数是可选的。对于非列表参数,该值设置为指定的默认值。
通用占位符定义如下:
<boolean>
: 一个布尔值,可以取值true
或false
<duration>
: 匹配正则表达式的持续时间((([0-9]+)y)?(([0-9]+)w)?(([0-9]+)d)?(([0-9]+)h)?(([0-9]+)m)?(([0-9]+)s)?(([0-9]+)ms)?|0)
,例如1d
,1h30m
,5m
,10s
<filename>
: 当前工作目录中的有效路径<float>
: 一个浮点数<host>
: 由主机名或 IP 后跟可选端口号组成的有效字符串<int>
: 一个整数值<labelname>
: 匹配正则表达式的字符串[a-zA-Z_][a-zA-Z0-9_]*
<labelvalue>
:一串unicode字符<path>
: 一个有效的 URL 路径<scheme>
: 可以取值的字符串http
或https
<secret>
: 一个常规的秘密字符串,例如密码<string>
: 常规字符串<size>
:以字节为单位的大小,例如512MB
。需要一个单位。支持的单位:B、KB、MB、GB、TB、PB、EB。<tmpl_string>
: 一个在使用前被模板扩展的字符串
表达式语言数据类型
在 Prometheus 的表达式语言中,表达式或子表达式可以计算为四种类型之一:
- 即时向量- 一组时间序列,每个时间序列包含一个样本,所有样本共享相同的时间戳
- 范围向量- 一组时间序列,其中包含每个时间序列随时间变化的一系列数据点
- 标量- 一个简单的数字浮点值
- String - 一个简单的字符串值;目前未使用
根据用例(例如,当绘制图形与显示表达式的输出时),这些类型中只有一些是合法的,作为用户指定表达式的结果。例如,返回即时向量的表达式是唯一可以直接绘制的类型。
文字Literals
字符串文字String literals
字符串可以用单引号、双引号或反引号指定为文字。
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`
浮点数Float literals
标量浮点值可以写成以下格式的文字整数或浮点数(仅包含空格以提高可读性):
[-+]?(
[0-9]*\.?[0-9]+([eE][-+]?[0-9]+)?
| 0[xX][0-9a-fA-F]+
| [nN][aA][nN]
| [iI][nN][fF]
)
例子:
23
-2.43
3.4e-9
0x8f
-Inf
NaN
时间戳选择器Time series Selectors
即时向量选择器Instant vector selectors
即时向量选择器允许在给定时间戳(即时)选择一组时间序列和每个时间序列的单个样本值:在最简单的形式中,仅指定度量名称。这会生成一个即时向量,其中包含具有此指标名称的所有时间序列的元素。
此示例选择具有http_requests_total
指标名称的所有时间序列:
http_requests_total
可以通过在花括号 ( {}
) 中附加逗号分隔的标签匹配器列表来进一步过滤这些时间序列。
此示例仅选择那些http_requests_total
指标名称也将job
标签设置为prometheus
且其 group
标签设置为的时间序列canary
:
http_requests_total{job="prometheus",group="canary"}
也可以否定匹配标签值,或将标签值与正则表达式匹配。存在以下标签匹配运算符:
=
:选择与提供的字符串完全相同的标签。!=
:选择不等于提供的字符串的标签。=~
:选择与提供的字符串正则表达式匹配的标签。!~
:选择与提供的字符串不匹配的标签。
正则表达式匹配完全锚定。的匹配项env=~"foo"
被视为env=~"^foo$"
.
例如,这会选择 、 和环境的所有时间 序列http_requests_total
以及除 以外的 HTTP 方法。staging testing developmen 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:.*"}
指标名称不能是关键字bool
、on
、ignoring
和group_left
之一group_right
。以下表达式是非法的:
on{} # Bad!
此限制的解决方法是使用__name__
标签:
{__name__="on"} # Good!
Prometheus 中的所有正则表达式都使用RE2 语法。
范围向量选择器Range Vector Selectors
范围向量文字的工作方式类似于即时向量文字,只是它们选择了从当前时刻返回的样本范围。从句法上讲,持续时间[]
附加在矢量选择器末尾的方括号 ( ) 中,以指定应为每个结果范围矢量元素获取时间回溯多长时间的值。
在这个例子中,我们选择我们在过去 5 分钟内为所有时间序列记录的所有值,这些值的指标名称http_requests_total
和job
标签设置为prometheus
:
http_requests_total{job="prometheus"}[5m]
持续时间Time Durations
持续时间被指定为一个数字,紧接着是以下单位之一:
ms
- 毫秒s
- 秒m
- 分钟h
- 小时d
- days - 假设一天总是 24 小时w
- 周 - 假设一周总是 7dy
- 年 - 假设一年总是 365 天
持续时间可以通过串联来组合。单位必须从最长到最短排序。给定的单位在一段时间内只能出现一次。
以下是有效持续时间的一些示例:
5h
1h30m
5m
10s
偏移修改器Offset modifier
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)
为了与时间向前的时间偏移进行比较,可以指定一个负偏移量:
rate(http_requests_total[5m] offset -1w)
请注意,这允许查询提前查看其评估时间。
@修饰符modifier
@
修饰符允许更改查询中单个即时和范围向量的评估时间。提供给@
修饰符的时间是一个 unix 时间戳,并用浮点文字描述。
例如,以下表达式返回 http_requests_total
at的值2021-01-04T07:40:00+00:00
:
http_requests_total @ 1609746000
请注意,@
修饰符始终需要紧跟在选择器之后,即以下内容是正确的:
sum(http_requests_total{method="GET"} @ 1609746000) // GOOD.
虽然以下内容是不正确的:
sum(http_requests_total{method="GET"}) @ 1609746000 // INVALID.
这同样适用于范围向量。这将返回 5 分钟的 http_requests_total
利率2021-01-04T07:40:00+00:00
:
rate(http_requests_total[5m] @ 1609746000)
@
修饰符在 . 的限制内支持上述浮点文字的所有表示int64
。它也可以与offset
修改器一起使用,其中偏移量相对于@
修改器时间应用,而不管首先写入哪个修改器。这 2 个查询将产生相同的结果。
# offset after @
http_requests_total @ 1609746000 offset 5m
# offset before @
http_requests_total offset 5m @ 1609746000
此外,start()
andend()
也可以用作@
修饰符的值作为特殊值。
对于范围查询,它们分别解析为范围查询的开始和结束,并在所有步骤中保持不变。
对于即时查询,start()
两者end()
都解析为评估时间。
http_requests_total @ start()
rate(http_requests_total[5m] @ end())
请注意,@
修饰符允许查询提前查看其评估时间。
子查询
子查询允许您针对给定的范围和分辨率运行即时查询。子查询的结果是一个范围向量。
句法:<instant_query> '[' <range> ':' [<resolution>] ']' [ @ <float_literal> ] [ offset <duration> ]
<resolution>
是可选的。默认值是全局评估间隔。
运营商
Prometheus 支持许多二元和聚合运算符。这些在表达式语言运算符页面中有详细描述。
功能
Prometheus 支持多种函数来操作数据。这些在表达式语言函数页面中有详细描述。
注释
PromQL 支持以 开头的行注释#
。例子:
# This is a comment
陷阱Gotchas
陈旧
运行查询时,将独立于实际的当前时间序列数据选择采样数据的时间戳。这主要是为了支持聚合(sum
、avg
等)等情况,其中多个聚合时间序列在时间上并不完全对齐。由于它们的独立性,Prometheus 需要在这些时间戳处为每个相关时间序列分配一个值。它通过简单地获取此时间戳之前的最新样本来实现。
如果目标抓取或规则评估不再返回以前存在的时间序列的样本,则该时间序列将被标记为陈旧。如果一个目标被删除,它之前返回的时间序列将很快被标记为过时的。
如果在时间序列标记为陈旧后在采样时间戳处评估查询,则不会为该时间序列返回任何值。如果随后为该时间序列摄取新样本,它们将照常返回。
如果在采样时间戳前 5 分钟未找到样本(默认情况下),则此时不会为该时间序列返回任何值。这实际上意味着时间序列在其最新收集的样本早于 5 分钟或被标记为陈旧之后从图表中“消失”。
对于在其数据中包含时间戳的时间序列,不会标记过时。在这种情况下,将仅应用 5 分钟阈值。
避免缓慢的查询和过载
如果一个查询需要对非常大量的数据进行操作,绘制它可能会超时或使服务器或浏览器过载。因此,在对未知数据构建查询时,始终在 Prometheus 表达式浏览器的表格视图中开始构建查询,直到结果集看起来合理(最多数百个,而不是数千个时间序列)。只有在充分过滤或聚合数据后,才切换到图形模式。如果表达式仍然需要很长时间才能临时绘制图表,请通过记录规则预先记录它。
这与 Prometheus 的查询语言尤其相关,其中像这样的裸度量名称选择器api_http_requests_total
可以扩展到具有不同标签的数千个时间序列。还要记住,聚合多个时间序列的表达式会在服务器上产生负载,即使输出只是少量的时间序列。这类似于在关系数据库中对列的所有值求和会很慢,即使输出值只是一个数字。
OPERATORS运算
算术二元运算符Prometheus 中存在以下二元算术运算符:
+
(添加)-
(减法)*
(乘法)/
(除法)%
(模数)^
(幂/指数)
二元算术运算符在标量/标量、向量/标量和向量/向量值对之间定义。
比较二元运算符Comparison binary operators
Prometheus 中存在以下二进制比较运算符:
==
(平等的)!=
(不等于)>
(大于)<
(少于)>=
(大于或等于)<=
(小于或等于)
它们的行为可以通过bool
在运算符之后提供来修改,这将返回0
或1
用于值而不是过滤。
逻辑/集合二元运算符Logical/set binary operators
这些逻辑/集合二元运算符仅在即时向量之间定义:
and
(intersection) 与or
(union) 或unless
(complement) 补充
矢量匹配
向量之间的操作试图为左侧的每个条目在右侧向量中找到匹配元素。匹配行为有两种基本类型:一对一和多对一/一对多。
矢量匹配关键词
这些矢量匹配关键字允许在具有不同标签集的系列之间进行匹配,提供:
on
ignoring
组修饰符Group modifiers
这些组修饰符启用多对一/一对多向量匹配:
group_left
group_right
多对一和一对多匹配是应该仔细考虑的高级用例。通常正确使用可以ignoring(<labels>)
提供预期的结果。
分组修饰符只能用于 比较和 算术。and
默认情况下,操作 asunless
和 or
操作与右向量中的所有可能条目匹配。
一对一向量匹配
一对一从操作的每一侧找到一对唯一的条目。在默认情况下,这是一个遵循格式的操作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
orgroup_right
修饰符明确请求,其中 left/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
一个标签只能出现在其中一个列表中。结果向量的每个时间序列必须是唯一可识别的。
示例查询:
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
聚合运算符
Prometheus 支持以下内置聚合运算符,可用于聚合单个即时向量的元素,从而产生具有聚合值的更少元素的新向量:
sum
(计算维度总和)min
(选择最小尺寸)max
(选择最大尺寸)avg
(计算维度的平均值)group
(结果向量中的所有值均为 1)stddev
(计算维度的总体标准偏差)stdvar
(计算维度的总体标准方差)count
(计算向量中元素的数量)count_values
(计算具有相同值的元素的数量)bottomk
(样本值最小的 k 个元素)topk
(样本值最大的 k 个元素)quantile
(计算维度上的 φ 分位数 (0 ≤ φ ≤ 1))
这些运算符既可以用于聚合所有标签维度,也可以通过包含without
orby
子句来保留不同的维度。这些子句可以用在表达式之前或之后。
<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
仅用于对输入向量进行分桶。
quantile
计算 φ 分位数,即在聚合的维度的 N 个度量值中排名第 φ*N 的值。φ 作为聚合参数提供。例如,quantile(0.5, ...)
计算中位数, quantile(0.95, ...)
第 95 个百分位数。对于 φ = NaN
,NaN
返回。对于 φ < 0,-Inf
返回。对于 φ > 1,+Inf
返回。
例子:
如果该指标具有按、和标签散开http_requests_total
的时间序列 ,我们可以通过以下方式计算所有实例中每个应用程序和组的可见 HTTP 请求总数:application``instance``group
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 中二元运算符的优先级,从高到低。
^
*
,/
,%
,atan2
+
,-
==
,!=
_<=
_<
_>=
_>
and
,unless
or
相同优先级的运算符是左结合的。例如, 2 * 3 % 2
相当于(2 * 3) % 2
. 然而^
是右结合的,所以2 ^ 3 ^ 2
等价于2 ^ (3 ^ 2)
.
原生直方图的运算符
本机直方图是一项实验性功能。必须通过功能标志启用摄取本机直方图。一旦摄取了原生直方图,就可以查询它们(即使再次禁用功能标志之后)。但是,运算符对原生直方图的支持仍然非常有限。
即使涉及直方图样本,逻辑/集合二元运算符也能按预期工作。它们只检查向量元素是否存在,不会根据元素的样本类型(浮点数或直方图)改变它们的行为。
+
完全支持两个原生直方图之间的二元运算符和sum
聚合原生直方图的聚合运算符。即使所涉及的直方图具有不同的桶布局,桶也会自动进行适当的转换,以便可以执行操作。(使用当前支持的桶模式,这总是可能的。)如果任一运算符必须对直方图样本和浮点样本的混合求和,则相应的向量元素将从输出向量中完全删除。
所有其他运算符的行为都不有意义。他们要么将直方图样本视为值为 0 的浮点样本,要么(在标量和向量之间进行算术运算的情况下)保持直方图样本不变。在本机直方图成为稳定功能之前,此行为将变为有意义的行为。
FUNCTIONS功能
一些函数有默认参数,例如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()
clamp(v instant-vector, min scalar, max scalar)
将所有元素的样本值v
限制在 的下限min
和上限max
。
特殊情况: - 返回空向量 if min > max
- 返回NaN
if min
or max
isNaN
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 表示星期日等。
day_of_year()
day_of_year(v=vector(time()) instant-vector)
以 UTC 格式返回每个给定时间的年中日期。非闰年的返回值为 1 到 365,闰年的返回值为 1 到 366。
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
通过计算新直方图对原生直方图进行操作,其中每个分量(观测值的总和和计数、桶)是 v
. v
但是,结果向量中将缺少其中包含范围内浮点数和本机直方图样本混合的每个元素。
delta
应该只与仪表和本机直方图一起使用,其中组件的行为类似于仪表(所谓的仪表直方图)。
deriv()
deriv(v range-vector)``v
使用简单线性回归计算范围向量中时间序列的每秒导数。范围向量必须至少有两个样本才能执行计算。当+Inf
或 -Inf
在距离矢量中找到时,计算的斜率和偏移值将为NaN
.
deriv
应仅与量规一起使用。
exp()
exp(v instant-vector)
计算 中所有元素的指数函数v
。特殊情况是:
Exp(+Inf) = +Inf
Exp(NaN) = NaN
floor()
floor(v instant-vector)
将所有元素的样本值v
向下舍入到最接近的整数。
histogram_count()
和histogram_sum()
这两个函数都只作用于本机直方图,这是一个实验特性。这些函数的行为可能会在 Prometheus 的未来版本中发生变化,包括将它们从 PromQL 中删除。
histogram_count(v instant-vector)
返回存储在本机直方图中的观察计数。非原生直方图的样本将被忽略,并且不会出现在返回的向量中。
同样,histogram_sum(v instant-vector)
返回存储在本机直方图中的观察值之和。
按照以下方式使用histogram_count
本机直方图计算观察率(在本例中对应于“每秒请求数”):
histogram_count(rate(http_request_duration_seconds[10m]))
的额外使用histogram_sum
可以计算观察值的平均值(在这种情况下对应于“平均请求持续时间”):
histogram_sum(rate(http_request_duration_seconds[10m]))
/
histogram_count(rate(http_request_duration_seconds[10m]))
histogram_fraction()
此功能仅作用于本机直方图,这是一项实验性功能。此函数的行为可能会在 Prometheus 的未来版本中发生变化,包括将其从 PromQL 中删除。
对于本机直方图,histogram_fraction(lower scalar, upper scalar, v instant-vector)
返回所提供的下限值和上限值之间的估计观测分数。非原生直方图的样本将被忽略,并且不会出现在返回的向量中。
例如,以下表达式计算过去一小时内花费 200 毫秒或更短时间的 HTTP 请求的比例:
histogram_fraction(0, 0.2, rate(http_request_duration_seconds[1h]))
估计的误差取决于底层原生直方图的分辨率以及提供的边界与直方图中的桶边界对齐的紧密程度。
+Inf
并且-Inf
是有效的边界值。例如,如果上面表达式中的直方图包含负面观察结果(请求持续时间不应该是这种情况),则包含所有小于或等于 0.2 的观察结果的适当下限将是-Inf
,而不是0
.
仅当提供的边界与底层本机直方图中的桶边界精确对齐时,提供的边界是包含的还是排他的才相关。在这种情况下,行为取决于直方图的模式定义。当前支持的模式都具有包含正值的上边界和独占的下边界(反之亦然)。在没有精确对齐边界的情况下,该函数使用线性插值来估计分数。由于由此产生的不确定性,边界是包容性的还是排他性的就变得无关紧要了。
histogram_quantile()
histogram_quantile(φ scalar, b instant-vector)
从传统直方图或原生直方图计算 φ 分位数 (0 ≤ φ ≤ 1) 。(有关 φ 分位数的详细说明和(常规)直方图度量类型的一般用法,请参阅直方图和摘要。)
请注意,原生直方图是一项实验性功能。在处理本机直方图时,此函数的行为可能会在 Prometheus 的未来版本中发生变化。
中的常规浮点样本b
被认为是一个或多个常规直方图的每个桶中的观察计数。每个浮动样本都必须有一个标签le
,其中标签值表示桶的包含上限。(没有此类标签的浮点样本将被静默忽略。)其他标签和度量名称用于标识属于每个常规直方图的桶。直方图度量类型 自动提供带有_bucket
后缀和适当标签的时间序列。
中的原生直方图样本b
分别作为单独的直方图处理,以从中计算分位数。
只要不出现命名冲突,b
就可以混合使用传统直方图和本机直方图。
使用该rate()
函数指定分位数计算的时间窗口。
示例:调用直方图度量http_request_duration_seconds
(因此传统直方图的桶的度量名称为 http_request_duration_seconds_bucket
)。要计算过去 10 分钟内请求持续时间的第 90 个百分位数,如果 http_request_duration_seconds
是传统直方图,请使用以下表达式:
histogram_quantile(0.9, rate(http_request_duration_seconds_bucket[10m]))
对于本机直方图,请改用以下表达式:
histogram_quantile(0.9, rate(http_request_duration_seconds[10m]))
为 中的每个标签组合计算分位数 http_request_duration_seconds
。要聚合,请sum()
在函数周围使用聚合器rate()
。由于处理常规直方图le
需要标签 ,因此必须将其包含在子句中。以下表达式聚合了常规直方图的第 90 个百分位数:histogram_quantile()``by``job
histogram_quantile(0.9, sum by (job, le) (rate(http_request_duration_seconds_bucket[10m])))
聚合原生直方图时,表达式简化为:
histogram_quantile(0.9, sum by (job) (rate(http_request_duration_seconds[10m])))
要聚合所有常规直方图,仅指定le
标签:
histogram_quantile(0.9, sum by (le) (rate(http_request_duration_seconds_bucket[10m])))
使用本机直方图,聚合所有内容照常进行,无需任何by
子句:
histogram_quantile(0.9, sum(rate(http_request_duration_seconds[10m])))
该histogram_quantile()
函数通过假设桶内的线性分布来插入分位数值。
如果b
有 0 个观察值,NaN
则返回。对于 φ < 0,-Inf
返回。对于 φ > 1,+Inf
返回。对于 φ = NaN
,NaN
返回。
以下仅与传统直方图相关:如果b
包含少于两个桶,NaN
则返回。最高桶的上限必须为+Inf
。(否则,NaN
返回。)如果分位数位于最高桶中,则返回第二高桶的上限。如果最低桶的上限大于 0,则假定最低桶的下限为 0。在这种情况下,在该桶内应用通常的线性插值。否则,为位于最低桶中的分位数返回最低桶的上限。
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
通过计算一个新的直方图来作用于原生直方图,其中每个分量(观测值的总和和计数,桶)是 v
. v
但是,结果向量中将缺少其中包含范围内浮点数和本机直方图样本混合的每个元素。
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
如果正则表达式不匹配,则返回时间序列不变。
此示例将返回带有a:c
labelservice
和a
label值的时间序列foo
:
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
,使用简单线性回归预测从现在开始的时间序列秒数的值 。范围向量必须至少有两个样本才能执行计算。当+Inf
或-Inf
在距离矢量中找到时,计算的斜率和偏移值将为NaN
.
predict_linear
应仅与量规一起使用。
rate()
rate(v range-vector)
计算范围向量中时间序列的每秒平均增长率。单调性中断(例如由于目标重启导致的计数器重置)会自动调整。此外,计算外推到时间范围的末端,允许错过刮擦或刮擦周期与范围的时间段不完全对齐。
以下示例表达式返回范围向量中每个时间序列在过去 5 分钟内测量的每秒 HTTP 请求速率:
rate(http_requests_total{job="api-server"}[5m])
rate
通过计算新直方图对原生直方图起作用,其中每个分量(观测值的总和和计数,桶)是 v
. v
但是,结果向量中将缺少其中包含范围内浮点数和本机直方图样本混合的每个元素。
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
。
sgn()
sgn(v instant-vector)
返回一个向量,所有样本值都转换为它们的符号,定义如下:如果 v 为正则为 1,如果 v 为负则为 -1,如果 v 等于零则为 0。
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 以来的秒数。
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)
:指定区间内值的总体标准方差。last_over_time(range-vector)
: 指定区间内的最新点值。present_over_time(range-vector)
:指定区间内任何系列的值 1。
请注意,指定区间中的所有值在聚合中具有相同的权重,即使这些值在整个区间内的分布不均匀也是如此。
三角函数
三角函数以弧度为单位:
acos(v instant-vector)
:计算v
(特殊情况)中所有元素的反余弦。acosh(v instant-vector)``v
:计算(特例)中所有元素的反双曲余弦值。asin(v instant-vector)
:计算v
(特殊情况)中所有元素的反正弦。asinh(v instant-vector)``v
:计算(特殊情况)中所有元素的反双曲正弦值。atan(v instant-vector)
:计算v
(特殊情况)中所有元素的反正切。atanh(v instant-vector)``v
:计算(特例)中所有元素的反双曲正切值。cos(v instant-vector)
:计算v
(特殊情况)中所有元素的余弦。cosh(v instant-vector)
:计算v
(特例)中所有元素的双曲余弦值。sin(v instant-vector)
:计算v
(特殊情况)中所有元素的正弦。sinh(v instant-vector)
:计算v
(特殊情况)中所有元素的双曲正弦值。tan(v instant-vector)
:计算v
(特殊情况)中所有元素的正切。tanh(v instant-vector)
:计算v
(特殊情况)中所有元素的双曲正切值。
以下内容对于度数和弧度之间的转换很有用:
deg(v instant-vector)
: 将 中所有元素的弧度转换为度数v
。pi()
: 返回圆周率。rad(v instant-vector)
: 将 中所有元素的度数转换为弧度v
。
查询示例
简单的时间序列选择
返回所有带有指标的时间序列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.."}
子查询
返回过去 30 分钟指标的 5 分钟速率,http_requests_total
分辨率为 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接口
当前稳定的 HTTP API 可在/api/v1
Prometheus 服务器上访问。任何不间断的添加都将添加到该端点下。
格式概述
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>"]
}
导出器和集成 EXPORTERS AND INTEGRATIONS
有许多库和服务器可帮助将现有指标从第三方系统导出为 Prometheus 指标。这对于无法直接使用 Prometheus 指标(例如,HAProxy 或 Linux 系统统计信息)检测给定系统的情况很有用。
第三方出口商
其中一些出口商作为官方Prometheus GitHub 组织的一部分进行维护,那些被标记为官方,其他出口商是外部贡献和维护的。
我们鼓励创建更多的出口商,但不能审查所有出口商的 最佳做法。通常,这些导出器托管在 Prometheus GitHub 组织之外。
导出器默认端口wiki 页面已成为导出器的 另一个目录,并且可能包括由于功能重叠或仍在开发中而未在此处列出的导出器。
JMX 导出器可以从各种基于 JVM 的应用程序导出,例如Kafka和 Cassandra。
Databases
- Aerospike exporter
- ClickHouse exporter
- Consul exporter (official)
- Couchbase exporter
- CouchDB exporter
- Druid Exporter
- Elasticsearch exporter
- EventStore exporter
- IoTDB exporter
- KDB+ exporter
- Memcached exporter (official)
- MongoDB exporter
- MongoDB query exporter
- MSSQL server exporter
- MySQL router exporter
- MySQL server exporter (official)
- OpenTSDB Exporter
- Oracle DB Exporter
- PgBouncer exporter
- PostgreSQL exporter
- Presto exporter
- ProxySQL exporter
- RavenDB exporter
- Redis exporter
- RethinkDB exporter
- SQL exporter
- Tarantool metric library
- Twemproxy
Hardware related
- apcupsd exporter
- BIG-IP exporter
- Bosch Sensortec BMP/BME exporter
- Collins exporter
- Dell Hardware OMSA exporter
- Disk usage exporter
- Fortigate exporter
- IBM Z HMC exporter
- IoT Edison exporter
- InfiniBand exporter
- IPMI exporter
- knxd exporter
- Modbus exporter
- Netgear Cable Modem Exporter
- Netgear Router exporter
- Network UPS Tools (NUT) exporter
- Node/system metrics exporter (official)
- NVIDIA GPU exporter
- ProSAFE exporter
- Waveplus Radon Sensor Exporter
- Weathergoose Climate Monitor Exporter
- Windows exporter
- Intel® Optane™ Persistent Memory Controller Exporter
Issue trackers and continuous integration
Messaging systems
- Beanstalkd exporter
- EMQ exporter
- Gearman exporter
- IBM MQ exporter
- Kafka exporter
- NATS exporter
- NSQ exporter
- Mirth Connect exporter
- MQTT blackbox exporter
- MQTT2Prometheus
- RabbitMQ exporter
- RabbitMQ Management Plugin exporter
- RocketMQ exporter
- Solace exporter
Storage
- Ceph exporter
- Ceph RADOSGW exporter
- Gluster exporter
- GPFS exporter
- Hadoop HDFS FSImage exporter
- HPE CSI info metrics provider
- HPE storage array exporter
- Lustre exporter
- NetApp E-Series exporter
- Pure Storage exporter
- ScaleIO exporter
- Tivoli Storage Manager/IBM Spectrum Protect exporter
HTTP
- Apache exporter
- HAProxy exporter (official)
- Nginx metric library
- Nginx VTS exporter
- Passenger exporter
- Squid exporter
- Tinyproxy exporter
- Varnish exporter
- WebDriver exporter
APIs
- AWS ECS exporter
- AWS Health exporter
- AWS SQS exporter
- Azure Health exporter
- BigBlueButton
- Cloudflare exporter
- Cryptowat exporter
- DigitalOcean exporter
- Docker Cloud exporter
- Docker Hub exporter
- Fastly exporter
- GitHub exporter
- Gmail exporter
- InstaClustr exporter
- Mozilla Observatory exporter
- OpenWeatherMap exporter
- Pagespeed exporter
- Rancher exporter
- Speedtest exporter
- Tankerkönig API Exporter
Logging
Other monitoring systems
- Akamai Cloudmonitor exporter
- Alibaba Cloudmonitor exporter
- AWS CloudWatch exporter (official)
- Azure Monitor exporter
- Cloud Foundry Firehose exporter
- Collectd exporter (official)
- Google Stackdriver exporter
- Graphite exporter (official)
- Heka dashboard exporter
- Heka exporter
- Huawei Cloudeye exporter
- InfluxDB exporter (official)
- ITM exporter
- JavaMelody exporter
- JMX exporter (official)
- Munin exporter
- Nagios / Naemon exporter
- New Relic exporter
- NRPE exporter
- Osquery exporter
- OTC CloudEye exporter
- Pingdom exporter
- Promitor (Azure Monitor)
- scollector exporter
- Sensu exporter
- site24x7_exporter
- SNMP exporter (official)
- StatsD exporter (official)
- TencentCloud monitor exporter
- ThousandEyes exporter
Miscellaneous
- ACT Fibernet Exporter
- BIND exporter
- BIND query exporter
- Bitcoind exporter
- Blackbox exporter (official)
- Bungeecord exporter
- BOSH exporter
- cAdvisor
- Cachet exporter
- ccache exporter
- c-lightning exporter
- DHCPD leases exporter
- Dovecot exporter
- Dnsmasq exporter
- eBPF exporter
- Ethereum Client exporter
- JFrog Artifactory Exporter
- Hostapd Exporter
- IRCd exporter
- Linux HA ClusterLabs exporter
- JMeter plugin
- JSON exporter
- Kannel exporter
- Kemp LoadBalancer exporter
- Kibana Exporter
- kube-state-metrics
- Locust Exporter
- Meteor JS web framework exporter
- Minecraft exporter module
- Minecraft exporter
- Nomad exporter
- nftables exporter
- OpenStack exporter
- OpenStack blackbox exporter
- oVirt exporter
- Pact Broker exporter
- PHP-FPM exporter
- PowerDNS exporter
- Podman exporter
- Process exporter
- rTorrent exporter
- Rundeck exporter
- SABnzbd exporter
- Script exporter
- Shield exporter
- Smokeping prober
- SMTP/Maildir MDA blackbox prober
- SoftEther exporter
- SSH exporter
- Teamspeak3 exporter
- Transmission exporter
- Unbound exporter
- WireGuard exporter
- Xen exporter
实施新的 Prometheus 导出器时,请遵循 编写导出器的指南。 同时请考虑咨询开发邮件列表。我们很乐意就如何使您的出口商尽可能有用和一致提供建议。
公开普罗米修斯指标的软件
一些第三方软件以 Prometheus 格式公开指标,因此不需要单独的导出器:
- Ansible Tower (AWX)
- App Connect Enterprise
- Ballerina
- BFE
- Caddy (direct)
- Ceph
- CockroachDB
- Collectd
- Concourse
- CRG Roller Derby Scoreboard (direct)
- Diffusion
- Docker Daemon
- Doorman (direct)
- Dovecot
- Envoy
- Etcd (direct)
- Flink
- FreeBSD Kernel
- GitLab
- Grafana
- JavaMelody
- Kong
- Kubernetes (direct)
- Linkerd
- mgmt
- MidoNet
- midonet-kubernetes (direct)
- MinIO
- PATROL with Monitoring Studio X
- Netdata
- OpenZiti
- Pomerium
- Pretix
- Quobyte (direct)
- RabbitMQ
- RobustIRC
- ScyllaDB
- Skipper
- SkyDNS (direct)
- Telegraf
- Traefik
- Vector
- VerneMQ
- Weave Flux
- Xandikos (direct)
- Zipkin
标记为direct的软件也直接使用 Prometheus 客户端库进行检测。
其他第三方实用程序
本部分列出了库和其他实用程序,可帮助您检测某种语言的代码。它们本身不是 Prometheus 客户端库,而是在后台使用普通的 Prometheus 客户端库之一。对于所有独立维护的软件,我们无法审查所有软件的最佳实践。
- Clojure: iapetos
- Go: go-metrics instrumentation library
- Go: gokit
- Go: prombolt
- Java/JVM: EclipseLink metrics collector
- Java/JVM: Hystrix metrics publisher
- Java/JVM: Jersey metrics collector
- Java/JVM: Micrometer Prometheus Registry
- Python-Django: django-prometheus
- Node.js: swagger-stats
集成INTEGRATIONS
除了客户端库和 导出器以及相关库之外,Prometheus 中还有许多其他通用集成点。此页面列出了与这些的一些集成。
由于功能重叠或仍在开发中,因此并未在此处列出所有集成。导出器默认端口 wiki 页面也恰好包含一些适合这些类别的非导出器集成。
文件服务发现File Service Discovery
对于 Prometheus 本身不支持的服务发现机制, 基于文件的服务发现提供了一个集成接口。
远程端点和存储Remote Endpoints and Storage
Prometheus的远程写入和远程读取 功能允许透明地发送和接收样本。这主要用于长期存储。建议您仔细评估此空间中的任何解决方案,以确认它可以处理您的数据量。
- AppOptics: write
- AWS Timestream: read and write
- Azure Data Explorer: read and write
- Azure Event Hubs: write
- Chronix: write
- Cortex: read and write
- CrateDB: read and write
- Elasticsearch: write
- Gnocchi: write
- Google BigQuery: read and write
- Google Cloud Spanner: read and write
- Grafana Mimir: read and write
- Graphite: write
- InfluxDB: read and write
- Instana: write
- IRONdb: read and write
- Kafka: write
- M3DB: read and write
- New Relic: write
- OpenTSDB: write
- PostgreSQL/TimescaleDB: read and write
- QuasarDB: read and write
- SignalFx: write
- Splunk: read and write
- Sysdig Monitor: write
- TiKV: read and write
- Thanos: read and write
- VictoriaMetrics: write
- Wavefront: write
Prom-migrator是一个用于在远程存储系统之间迁移数据的工具。
Alertmanager Webhook Receiver(接收器)
对于 Alertmanager 本身不支持的通知机制, webhook 接收器允许集成。
- alertmanager-webhook-logger: logs alerts
- Alertsnitch: saves alerts to a MySQL database
- Asana
- AWS SNS
- Better Uptime
- Canopsis
- DingTalk
- Discord
- GitLab
- Gotify
- GELF
- Icinga2
- iLert
- IRC Bot
- JIRAlert
- Matrix
- Phabricator / Maniphest
- prom2teams: forwards notifications to Microsoft Teams
- Ansible Tower: call Ansible Tower (AWX) API on alerts (launch jobs etc.)
- Rocket.Chat
- ServiceNow
- Signal
- SIGNL4
- SMS: supports multiple providers
- SNMP traps
- Squadcast
- Telegram bot
- xMatters
- XMPP Bot
- Zenduty
- Zoom
管理Management
Prometheus 不包含配置管理功能,允许您将其与现有系统集成或构建在其之上。
- Prometheus Operator:在 Kubernetes 之上管理 Prometheus
- Promgen:用于 Prometheus 和 Alertmanager 的 Web UI 和配置生成器
其他(other)
- karma: 警报仪表板
- PushProx:横向 NAT 和类似网络设置的代理
- Promdump:用于转储和恢复数据块的 kubectl 插件
- Promregator:Cloud Foundry 应用程序的发现和抓取
- pint:普罗米修斯规则 linter
警报概述ALERTING OVERVIEW
Prometheus 的警报分为两部分。Prometheus 服务器中的警报规则将警报发送到 Alertmanager。然后,Alertmanager 管理这些警报,包括静音、抑制、聚合以及通过电子邮件、随叫随到的通知系统和聊天平台等方法发送通知。
设置警报和通知的主要步骤是:
- 设置和配置Alertmanager
- 配置 Prometheus以与 Alertmanager 对话
- 在 Prometheus 中创建警报规则
警报管理器ALERTMANAGER
Alertmanager处理客户端应用程序(例如 Prometheus 服务器)发送的警报。它负责删除重复数据、分组并将它们路由到正确的接收器集成,例如电子邮件、PagerDuty 或 OpsGenie。它还负责警报的静音和抑制。
下面介绍 Alertmanager 实现的核心概念。请查阅配置文档以了解如何更详细地使用它们。
分组
分组将性质相似的警报分类为单个通知。当许多系统同时发生故障并且可能同时触发成百上千个警报时,这在较大的中断期间特别有用。
**示例:**当发生网络分区时,您的集群中正在运行数十个或数百个服务实例。一半的服务实例无法再访问数据库。Prometheus 中的警报规则被配置为在无法与数据库通信时为每个服务实例发送警报。结果,数百条警报被发送到 Alertmanager。
作为用户,人们只想获得一个页面,同时仍然能够准确地看到哪些服务实例受到了影响。因此,可以将 Alertmanager 配置为按集群和警报名称对警报进行分组,以便它发送一个紧凑的通知。
警报分组、分组通知的时间以及这些通知的接收者由配置文件中的路由树配置。
抑制Inhibition
抑制是一个概念,如果某些其他警报已经触发,则抑制某些警报的通知。
**示例:**正在触发一个警报,通知整个集群无法访问。Alertmanager 可以配置为在触发该特定警报时将所有其他有关该集群的警报静音。这可以防止与实际问题无关的成百上千个触发警报的通知。
客户行为Client behavior
Alertmanager 对其客户端的行为有特殊要求。这些仅与不使用 Prometheus 发送警报的高级用例相关。
高可用性High Availability
Alertmanager 支持配置以创建集群以实现高可用性。这可以使用–cluster-*标志进行配置。
重要的是不要在 Prometheus 和它的 Alertmanagers 之间负载均衡流量,而是将 Prometheus 指向所有 Alertmanagers 的列表。
警报(ALERT)配置与使用
配置
Alertmanager通过命令行标志和配置文件进行配置。虽然命令行标志配置不可变的系统参数,但配置文件定义了禁止规则、通知路由和通知接收器。
可视化编辑器可以 帮助构建路由树。
要查看所有可用的命令行标志,请运行
alertmanager -h .
Alertmanager 可以在运行时重新加载其配置。如果新配置格式不正确,则不会应用更改并记录错误。通过向进程发送 a 或向端点SIGHUP
发送 HTTP POST 请求来触发配置重新加载。/-/reload
配置文件
要指定要加载的配置文件,请使用--config.file
标志。
./alertmanager --config.file=alertmanager.yml
该文件以YAML 格式编写,由下面描述的方案定义。括号表示参数是可选的。对于非列表参数,该值设置为指定的默认值。
通用占位符定义如下:
<duration>
: 匹配正则表达式的持续时间((([0-9]+)y)?(([0-9]+)w)?(([0-9]+)d)?(([0-9]+)h)?(([0-9]+)m)?(([0-9]+)s)?(([0-9]+)ms)?|0)
,例如1d
,1h30m
,5m
,10s
<labelname>
: 匹配正则表达式的字符串[a-zA-Z_][a-zA-Z0-9_]*
<labelvalue>
:一串unicode字符<filepath>
: 当前工作目录中的有效路径<boolean>
: 一个布尔值,可以取值true
或false
<string>
: 常规字符串<secret>
: 一个常规的秘密字符串,例如密码<tmpl_string>
: 一个在使用前被模板扩展的字符串<tmpl_secret>
: 一个在使用前被模板扩展的字符串,这是一个秘密<int>
: 一个整数值
其他占位符单独指定。
提供的有效示例文件 显示了上下文中的用法。
全局配置指定在所有其他配置上下文中有效的参数。它们还用作其他配置部分的默认值。
global:
# The default SMTP From header field.
[ smtp_from: <tmpl_string> ]
# The default SMTP smarthost used for sending emails, including port number.
# Port number usually is 25, or 587 for SMTP over TLS (sometimes referred to as STARTTLS).
# Example: smtp.example.org:587
[ smtp_smarthost: <string> ]
# The default hostname to identify to the SMTP server.
[ smtp_hello: <string> | default = "localhost" ]
# SMTP Auth using CRAM-MD5, LOGIN and PLAIN. If empty, Alertmanager doesn't authenticate to the SMTP server.
[ smtp_auth_username: <string> ]
# SMTP Auth using LOGIN and PLAIN.
[ smtp_auth_password: <secret> ]
# SMTP Auth using PLAIN.
[ smtp_auth_identity: <string> ]
# SMTP Auth using CRAM-MD5.
[ smtp_auth_secret: <secret> ]
# The default SMTP TLS requirement.
# Note that Go does not support unencrypted connections to remote SMTP endpoints.
[ smtp_require_tls: <bool> | default = true ]
# The API URL to use for Slack notifications.
[ slack_api_url: <secret> ]
[ slack_api_url_file: <filepath> ]
[ victorops_api_key: <secret> ]
[ victorops_api_url: <string> | default = "https://alert.victorops.com/integrations/generic/20131114/alert/" ]
[ pagerduty_url: <string> | default = "https://events.pagerduty.com/v2/enqueue" ]
[ opsgenie_api_key: <secret> ]
[ opsgenie_api_key_file: <filepath> ]
[ opsgenie_api_url: <string> | default = "https://api.opsgenie.com/" ]
[ wechat_api_url: <string> | default = "https://qyapi.weixin.qq.com/cgi-bin/" ]
[ wechat_api_secret: <secret> ]
[ wechat_api_corp_id: <string> ]
[ telegram_api_url: <string> | default = "https://api.telegram.org" ]
# The default HTTP client configuration
[ http_config: <http_config> ]
# ResolveTimeout is the default value used by alertmanager if the alert does
# not include EndsAt, after this time passes it can declare the alert as resolved if it has not been updated.
# This has no impact on alerts from Prometheus, as they always include EndsAt.
[ resolve_timeout: <duration> | default = 5m ]
# Files from which custom notification template definitions are read.
# The last component may use a wildcard matcher, e.g. 'templates/*.tmpl'.
templates:
[ - <filepath> ... ]
# The root node of the routing tree.
route: <route>
# A list of notification receivers.
receivers:
- <receiver> ...
# A list of inhibition rules.
inhibit_rules:
[ - <inhibit_rule> ... ]
# DEPRECATED: use time_intervals below.
# A list of mute time intervals for muting routes.
mute_time_intervals:
[ - <mute_time_interval> ... ]
# A list of time intervals for muting/activating routes.
time_intervals:
[ - <time_interval> ... ]
<route>
路由块定义路由树中的节点及其子节点。如果未设置,其可选配置参数将从其父节点继承。
每个警报都在配置的顶级路由处进入路由树,该路由必须匹配所有警报(即没有任何配置的匹配器)。然后它遍历子节点。如果continue
设置为 false,它会在第一个匹配的孩子之后停止。如果continue
在匹配节点上为真,则警报将继续匹配后续的兄弟节点。如果警报不匹配节点的任何子节点(没有匹配的子节点,或不存在),则根据当前节点的配置参数处理警报。
[ receiver: <string> ]
# The labels by which incoming alerts are grouped together. For example,
# multiple alerts coming in for cluster=A and alertname=LatencyHigh would
# be batched into a single group.
#
# To aggregate by all possible labels use the special value '...' as the sole label name, for example:
# group_by: ['...']
# This effectively disables aggregation entirely, passing through all
# alerts as-is. This is unlikely to be what you want, unless you have
# a very low alert volume or your upstream notification system performs
# its own grouping.
[ group_by: '[' <labelname>, ... ']' ]
# Whether an alert should continue matching subsequent sibling nodes.
[ continue: <boolean> | default = false ]
# DEPRECATED: Use matchers below.
# A set of equality matchers an alert has to fulfill to match the node.
match:
[ <labelname>: <labelvalue>, ... ]
# DEPRECATED: Use matchers below.
# A set of regex-matchers an alert has to fulfill to match the node.
match_re:
[ <labelname>: <regex>, ... ]
# A list of matchers that an alert has to fulfill to match the node.
matchers:
[ - <matcher> ... ]
# How long to initially wait to send a notification for a group
# of alerts. Allows to wait for an inhibiting alert to arrive or collect
# more initial alerts for the same group. (Usually ~0s to few minutes.)
[ group_wait: <duration> | default = 30s ]
# How long to wait before sending a notification about new alerts that
# are added to a group of alerts for which an initial notification has
# already been sent. (Usually ~5m or more.)
[ group_interval: <duration> | default = 5m ]
# How long to wait before sending a notification again if it has already
# been sent successfully for an alert. (Usually ~3h or more).
[ repeat_interval: <duration> | default = 4h ]
# Times when the route should be muted. These must match the name of a
# mute time interval defined in the mute_time_intervals section.
# Additionally, the root node cannot have any mute times.
# When a route is muted it will not send any notifications, but
# otherwise acts normally (including ending the route-matching process
# if the `continue` option is not set.)
mute_time_intervals:
[ - <string> ...]
# Times when the route should be active. These must match the name of a
# time interval defined in the time_intervals section. An empty value
# means that the route is always active.
# Additionally, the root node cannot have any active times.
# The route will send notifications only when active, but otherwise
# acts normally (including ending the route-matching process
# if the `continue` option is not set).
active_time_intervals:
[ - <string> ...]
# Zero or more child routes.
routes:
[ - <route> ... ]
例子
# The root route with all parameters, which are inherited by the child
# routes if they are not overwritten.
route:
receiver: 'default-receiver'
group_wait: 30s
group_interval: 5m
repeat_interval: 4h
group_by: [cluster, alertname]
# All alerts that do not match the following child routes
# will remain at the root node and be dispatched to 'default-receiver'.
routes:
# All alerts with service=mysql or service=cassandra
# are dispatched to the database pager.
- receiver: 'database-pager'
group_wait: 10s
matchers:
- service=~"mysql|cassandra"
# All alerts with the team=frontend label match this sub-route.
# They are grouped by product and environment rather than cluster
# and alertname.
- receiver: 'frontend-pager'
group_by: [product, environment]
matchers:
- team="frontend"
# All alerts with the service=inhouse-service label match this sub-route.
# the route will be muted during offhours and holidays time intervals.
# even if it matches, it will continue to the next sub-route
- receiver: 'dev-pager'
matchers:
- service="inhouse-service"
mute_time_intervals:
- offhours
- holidays
continue: true
# All alerts with the service=inhouse-service label match this sub-route
# the route will be active only during offhours and holidays time intervals.
- receiver: 'on-call-pager'
matchers:
- service="inhouse-service"
active_time_intervals:
- offhours
- holidays
<time_interval>
Atime_interval
指定一个命名的时间间隔,可以在路由树中引用该时间间隔以在一天的特定时间静音/激活特定路由。
name: <string>
time_intervals:
[ - <time_interval> ... ]
<time_interval>
Atime_interval
包含时间间隔的实际定义。该语法支持以下字段:
- times:
[ - <time_range> ...]
weekdays:
[ - <weekday_range> ...]
days_of_month:
[ - <days_of_month_range> ...]
months:
[ - <month_range> ...]
years:
[ - <year_range> ...]
所有字段都是列表。在每个非空列表中,必须至少满足一个元素才能匹配该字段。如果未指定字段,则任何值都将匹配该字段。对于匹配完整时间间隔的瞬间,所有字段都必须匹配。一些字段支持范围和负索引,详情如下。所有定义都采用 UTC,目前不支持其他时区。
time_range
范围包括开始时间和结束时间,以便轻松表示在小时边界开始/结束的时间。例如,开始时间:‘17:00’ 和结束时间:‘24:00’ 将从 17:00 开始并在 24:00 之前结束。它们是这样指定的:
times:
- start_time: HH:MM
end_time: HH:MM
weekday_range`:星期几的列表,一周从星期日开始到星期六结束。应按名称指定日期(例如“星期日”)。为方便起见,范围也接受以下形式:并且两端都包含在内。例如: `['monday:wednesday','saturday', 'sunday']
days_of_month_range
:一个月中的数字天数列表。天数从 1 开始。也可以接受从月末开始的负值,例如,一月的 -1 表示一月 31 日。例如:['1:5', '-3:-1']
. 延长超过月初或月底将导致它被钳制。例如,指定 ['1:31']
二月期间会将实际结束日期限制为 28 或 29,具体取决于闰年。包容两端。
month_range
:由不区分大小写的名称(例如“January”)或数字标识的日历月列表,其中 January = 1。也接受范围。例如,['1:3', 'may:august', 'december']
。包容两端。
year_range
: 年份的数字列表。范围被接受。例如,['2020:2022', '2030']
。包容两端。
<inhibit_rule>
当存在与另一组匹配器匹配的警报(源)时,禁止规则使匹配一组匹配器的警报(目标)静音。对于列表中的标签名称,目标和源警报必须具有相同的标签值equal
。
从语义上讲,缺少标签和具有空值的标签是同一回事。equal
因此,如果源警报和目标警报中都缺少 中列出的所有标签名称,则将应用禁止规则。
为防止警报抑制自身,同时匹配规则的目标端和源端的警报不能被条件相同的警报(包括自身)抑制。但是,我们建议以警报从不匹配双方的方式选择目标和源匹配器。更容易推理并且不会触发这种特殊情况。
# DEPRECATED: Use target_matchers below.
# Matchers that have to be fulfilled in the alerts to be muted.
target_match:
[ <labelname>: <labelvalue>, ... ]
# DEPRECATED: Use target_matchers below.
target_match_re:
[ <labelname>: <regex>, ... ]
# A list of matchers that have to be fulfilled by the target
# alerts to be muted.
target_matchers:
[ - <matcher> ... ]
# DEPRECATED: Use source_matchers below.
# Matchers for which one or more alerts have to exist for the
# inhibition to take effect.
source_match:
[ <labelname>: <labelvalue>, ... ]
# DEPRECATED: Use source_matchers below.
source_match_re:
[ <labelname>: <regex>, ... ]
# A list of matchers for which one or more alerts have
# to exist for the inhibition to take effect.
source_matchers:
[ - <matcher> ... ]
# Labels that must have an equal value in the source and target
# alert for the inhibition to take effect.
[ equal: '[' <labelname>, ... ']' ]
<http_config>
Ahttp_config
允许配置接收方用来与基于 HTTP 的 API 服务通信的 HTTP 客户端。
# Note that `basic_auth` and `authorization` options are mutually exclusive.
# Sets the `Authorization` header with the configured username and password.
# password and password_file are mutually exclusive.
basic_auth:
[ username: <string> ]
[ password: <secret> ]
[ password_file: <string> ]
# Optional the `Authorization` header configuration.
authorization:
# Sets the authentication type.
[ type: <string> | default: Bearer ]
# Sets the credentials. It is mutually exclusive with
# `credentials_file`.
[ credentials: <secret> ]
# Sets the credentials with the credentials read from the configured file.
# It is mutually exclusive with `credentials`.
[ credentials_file: <filename> ]
# Optional OAuth 2.0 configuration.
# Cannot be used at the same time as basic_auth or authorization.
oauth2:
[ <oauth2> ]
# Optional proxy URL.
[ proxy_url: <string> ]
# Configure whether HTTP requests follow HTTP 3xx redirects.
[ follow_redirects: <bool> | default = true ]
# Configures the TLS settings.
tls_config:
[ <tls_config> ]
oauth2
使用客户端凭据授权类型的 OAuth 2.0 身份验证。Alertmanager 使用给定的客户端访问和密钥从指定端点获取访问令牌。
client_id: <string>
[ client_secret: <secret> ]
# Read the client secret from a file.
# It is mutually exclusive with `client_secret`.
[ client_secret_file: <filename> ]
# Scopes for the token request.
scopes:
[ - <string> ... ]
# The URL to fetch the token from.
token_url: <string>
# Optional parameters to append to the token URL.
endpoint_params:
[ <string>: <string> ... ]
<tls_config>
Atls_config
允许配置 TLS 连接。
# CA certificate to validate the server certificate with.
[ ca_file: <filepath> ]
# Certificate and key files for client cert authentication to the server.
[ cert_file: <filepath> ]
[ key_file: <filepath> ]
# ServerName extension to indicate the name of the server.
# http://tools.ietf.org/html/rfc4366#section-3.1
[ server_name: <string> ]
# Disable validation of the server certificate.
[ insecure_skip_verify: <boolean> | default = false]
<receiver>
Receiver 是一个或多个通知集成的命名配置。
注意:作为取消过去对新接收器的暂停的一部分,人们同意,除了现有要求之外,新的通知集成将需要有一个具有推送访问权限的承诺维护者。
# The unique name of the receiver.
name: <string>
# Configurations for several notification integrations.
email_configs:
[ - <email_config>, ... ]
opsgenie_configs:
[ - <opsgenie_config>, ... ]
pagerduty_configs:
[ - <pagerduty_config>, ... ]
pushover_configs:
[ - <pushover_config>, ... ]
slack_configs:
[ - <slack_config>, ... ]
sns_configs:
[ - <sns_config>, ... ]
victorops_configs:
[ - <victorops_config>, ... ]
webhook_configs:
[ - <webhook_config>, ... ]
wechat_configs:
[ - <wechat_config>, ... ]
telegram_configs:
[ - <telegram_config>, ... ]
<email_config>
# Whether to notify about resolved alerts.
[ send_resolved: <boolean> | default = false ]
# The email address to send notifications to.
to: <tmpl_string>
# The sender's address.
[ from: <tmpl_string> | default = global.smtp_from ]
# The SMTP host through which emails are sent.
[ smarthost: <string> | default = global.smtp_smarthost ]
# The hostname to identify to the SMTP server.
[ hello: <string> | default = global.smtp_hello ]
# SMTP authentication information.
[ auth_username: <string> | default = global.smtp_auth_username ]
[ auth_password: <secret> | default = global.smtp_auth_password ]
[ auth_secret: <secret> | default = global.smtp_auth_secret ]
[ auth_identity: <string> | default = global.smtp_auth_identity ]
# The SMTP TLS requirement.
# Note that Go does not support unencrypted connections to remote SMTP endpoints.
[ require_tls: <bool> | default = global.smtp_require_tls ]
# TLS configuration.
tls_config:
[ <tls_config> ]
# The HTML body of the email notification.
[ html: <tmpl_string> | default = '{{ template "email.default.html" . }}' ]
# The text body of the email notification.
[ text: <tmpl_string> ]
# Further headers email header key/value pairs. Overrides any headers
# previously set by the notification implementation.
[ headers: { <string>: <tmpl_string>, ... } ]
<opsgenie_config>
OpsGenie 通知通过OpsGenie API发送。
# Whether to notify about resolved alerts.
[ send_resolved: <boolean> | default = true ]
# The API key to use when talking to the OpsGenie API.
[ api_key: <secret> | default = global.opsgenie_api_key ]
# The filepath to API key to use when talking to the OpsGenie API. Conflicts with api_key.
[ api_key_file: <filepath> | default = global.opsgenie_api_key_file ]
# The host to send OpsGenie API requests to.
[ api_url: <string> | default = global.opsgenie_api_url ]
# Alert text limited to 130 characters.
[ message: <tmpl_string> | default = '{{ template "opsgenie.default.message" . }}' ]
# A description of the alert.
[ description: <tmpl_string> | default = '{{ template "opsgenie.default.description" . }}' ]
# A backlink to the sender of the notification.
[ source: <tmpl_string> | default = '{{ template "opsgenie.default.source" . }}' ]
# A set of arbitrary key/value pairs that provide further detail
# about the alert.
# All common labels are included as details by default.
[ details: { <string>: <tmpl_string>, ... } ]
# List of responders responsible for notifications.
responders:
[ - <responder> ... ]
# Comma separated list of tags attached to the notifications.
[ tags: <tmpl_string> ]
# Additional alert note.
[ note: <tmpl_string> ]
# Priority level of alert. Possible values are P1, P2, P3, P4, and P5.
[ priority: <tmpl_string> ]
# Whether to update message and description of the alert in OpsGenie if it already exists
# By default, the alert is never updated in OpsGenie, the new message only appears in activity log.
[ update_alerts: <boolean> | default = false ]
# Optional field that can be used to specify which domain alert is related to.
[ entity: <tmpl_string> ]
# Comma separated list of actions that will be available for the alert.
[ actions: <tmpl_string> ]
# The HTTP client's configuration.
[ http_config: <http_config> | default = global.http_config ]
<responder>
# Exactly one of these fields should be defined.
[ id: <tmpl_string> ]
[ name: <tmpl_string> ]
[ username: <tmpl_string> ]
# "team", "teams, "user", "escalation" or "schedule".
type: <tmpl_string>
<pagerduty_config>
PagerDuty 通知通过PagerDuty API发送。PagerDuty 提供了有关如何集成的文档。与 Alertmanager 的 v0.11 有重要区别,并且对 PagerDuty 的 Events API v2 有更好的支持。
# Whether to notify about resolved alerts.
[ send_resolved: <boolean> | default = true ]
# The following two options are mutually exclusive.
# The PagerDuty integration key (when using PagerDuty integration type `Events API v2`).
routing_key: <tmpl_secret>
# The PagerDuty integration key (when using PagerDuty integration type `Prometheus`).
service_key: <tmpl_secret>
# The URL to send API requests to
[ url: <string> | default = global.pagerduty_url ]
# The client identification of the Alertmanager.
[ client: <tmpl_string> | default = '{{ template "pagerduty.default.client" . }}' ]
# A backlink to the sender of the notification.
[ client_url: <tmpl_string> | default = '{{ template "pagerduty.default.clientURL" . }}' ]
# A description of the incident.
[ description: <tmpl_string> | default = '{{ template "pagerduty.default.description" .}}' ]
# Severity of the incident.
[ severity: <tmpl_string> | default = 'error' ]
# A set of arbitrary key/value pairs that provide further detail
# about the incident.
[ details: { <string>: <tmpl_string>, ... } | default = {
firing: '{{ template "pagerduty.default.instances" .Alerts.Firing }}'
resolved: '{{ template "pagerduty.default.instances" .Alerts.Resolved }}'
num_firing: '{{ .Alerts.Firing | len }}'
num_resolved: '{{ .Alerts.Resolved | len }}'
} ]
# Images to attach to the incident.
images:
[ <image_config> ... ]
# Links to attach to the incident.
links:
[ <link_config> ... ]
# The part or component of the affected system that is broken.
[ component: <tmpl_string> ]
# A cluster or grouping of sources.
[ group: <tmpl_string> ]
# The class/type of the event.
[ class: <tmpl_string> ]
# The HTTP client's configuration.
[ http_config: <http_config> | default = global.http_config ]
<image_config>
这些字段记录在PagerDuty API 文档中。
href: <tmpl_string>
source: <tmpl_string>
alt: <tmpl_string>
<link_config>
这些字段记录在PagerDuty API 文档中。
href: <tmpl_string>
text: <tmpl_string>
<pushover_config>
Pushover 通知通过Pushover API发送。
# Whether to notify about resolved alerts.
[ send_resolved: <boolean> | default = true ]
# The recipient user's user key.
user_key: <secret>
# Your registered application's API token, see https://pushover.net/apps
# You can also register a token by cloning this Prometheus app:
# https://pushover.net/apps/clone/prometheus
token: <secret>
# Notification title.
[ title: <tmpl_string> | default = '{{ template "pushover.default.title" . }}' ]
# Notification message.
[ message: <tmpl_string> | default = '{{ template "pushover.default.message" . }}' ]
# A supplementary URL shown alongside the message.
[ url: <tmpl_string> | default = '{{ template "pushover.default.url" . }}' ]
# Priority, see https://pushover.net/api#priority
[ priority: <tmpl_string> | default = '{{ if eq .Status "firing" }}2{{ else }}0{{ end }}' ]
# How often the Pushover servers will send the same notification to the user.
# Must be at least 30 seconds.
[ retry: <duration> | default = 1m ]
# How long your notification will continue to be retried for, unless the user
# acknowledges the notification.
[ expire: <duration> | default = 1h ]
# The HTTP client's configuration.
[ http_config: <http_config> | default = global.http_config ]
<slack_config>
Slack 通知通过Slack webhooks发送。通知包含一个附件。
# Whether to notify about resolved alerts.
[ send_resolved: <boolean> | default = false ]
# The Slack webhook URL. Either api_url or api_url_file should be set.
# Defaults to global settings if none are set here.
[ api_url: <secret> | default = global.slack_api_url ]
[ api_url_file: <filepath> | default = global.slack_api_url_file ]
# The channel or user to send notifications to.
channel: <tmpl_string>
# API request data as defined by the Slack webhook API.
[ icon_emoji: <tmpl_string> ]
[ icon_url: <tmpl_string> ]
[ link_names: <boolean> | default = false ]
[ username: <tmpl_string> | default = '{{ template "slack.default.username" . }}' ]
# The following parameters define the attachment.
actions:
[ <action_config> ... ]
[ callback_id: <tmpl_string> | default = '{{ template "slack.default.callbackid" . }}' ]
[ color: <tmpl_string> | default = '{{ if eq .Status "firing" }}danger{{ else }}good{{ end }}' ]
[ fallback: <tmpl_string> | default = '{{ template "slack.default.fallback" . }}' ]
fields:
[ <field_config> ... ]
[ footer: <tmpl_string> | default = '{{ template "slack.default.footer" . }}' ]
[ mrkdwn_in: '[' <string>, ... ']' | default = ["fallback", "pretext", "text"] ]
[ pretext: <tmpl_string> | default = '{{ template "slack.default.pretext" . }}' ]
[ short_fields: <boolean> | default = false ]
[ text: <tmpl_string> | default = '{{ template "slack.default.text" . }}' ]
[ title: <tmpl_string> | default = '{{ template "slack.default.title" . }}' ]
[ title_link: <tmpl_string> | default = '{{ template "slack.default.titlelink" . }}' ]
[ image_url: <tmpl_string> ]
[ thumb_url: <tmpl_string> ]
# The HTTP client's configuration.
[ http_config: <http_config> | default = global.http_config ]
<action_config>
这些字段记录在消息附件和交互式消息的 Slack API 文档中。
text: <tmpl_string>
type: <tmpl_string>
# Either url or name and value are mandatory.
[ url: <tmpl_string> ]
[ name: <tmpl_string> ]
[ value: <tmpl_string> ]
[ confirm: <action_confirm_field_config> ]
[ style: <tmpl_string> | default = '' ]
<action_confirm_field_config>
这些字段记录在Slack API 文档中。
text: <tmpl_string>
[ dismiss_text: <tmpl_string> | default '' ]
[ ok_text: <tmpl_string> | default '' ]
[ title: <tmpl_string> | default '' ]
<field_config>
这些字段记录在Slack API 文档中。
title: <tmpl_string>
value: <tmpl_string>
[ short: <boolean> | default = slack_config.short_fields ]
<sns_config>
# Whether to notify about resolved alerts.
[ send_resolved: <boolean> | default = true ]
# The SNS API URL i.e. https://sns.us-east-2.amazonaws.com.
# If not specified, the SNS API URL from the SNS SDK will be used.
[ api_url: <tmpl_string> ]
# Configures AWS's Signature Verification 4 signing process to sign requests.
sigv4:
[ <sigv4_config> ]
# SNS topic ARN, i.e. arn:aws:sns:us-east-2:698519295917:My-Topic
# If you don't specify this value, you must specify a value for the phone_number or target_arn.
# If you are using a FIFO SNS topic you should set a message group interval longer than 5 minutes
# to prevent messages with the same group key being deduplicated by the SNS default deduplication window
[ topic_arn: <tmpl_string> ]
# Subject line when the message is delivered to email endpoints.
[ subject: <tmpl_string> | default = '{{ template "sns.default.subject" .}}' ]
# Phone number if message is delivered via SMS in E.164 format.
# If you don't specify this value, you must specify a value for the topic_arn or target_arn.
[ phone_number: <tmpl_string> ]
# The mobile platform endpoint ARN if message is delivered via mobile notifications.
# If you don't specify this value, you must specify a value for the topic_arn or phone_number.
[ target_arn: <tmpl_string> ]
# The message content of the SNS notification.
[ message: <tmpl_string> | default = '{{ template "sns.default.message" .}}' ]
# SNS message attributes.
attributes:
[ <string>: <string> ... ]
# The HTTP client's configuration.
[ http_config: <http_config> | default = global.http_config ]
<sigv4_config>
# The AWS region. If blank, the region from the default credentials chain is used.
[ region: <string> ]
# The AWS API keys. Both access_key and secret_key must be supplied or both must be blank.
# 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 authenticate.
[ profile: <string> ]
# AWS Role ARN, an alternative to using AWS API keys.
[ role_arn: <string> ]
<matcher>
匹配器是一个字符串,其语法受 PromQL 和 OpenMetrics 启发。匹配器的语法由三个标记组成:
- 有效的 Prometheus 标签名称。
=
、!=
、=~
或之一!~
。=
表示等于,!=
表示字符串不相等,=~
用于正则表达式的相等,用于正则表达式!~
的不相等。它们的含义与 PromQL 选择器中已知的含义相同。- UTF-8 字符串,可以用双引号引起来。在每个标记之前或之后,可能有任意数量的空格。
第三个标记可能是空字符串。在第三个标记中,OpenMetrics 转义规则适用:\"
双引号、\n
换行符、\\
文字反斜杠。未转义"
不得出现在第三个标记内(仅作为第一个或最后一个字符)。但是,文字换行符是可以容忍的,就像\
没有后跟\
, n
, 或的单个字符一样"
。在这种情况下,它们充当字面上的反斜杠。
匹配器以 AND 连接在一起,这意味着在针对给定警报上的标签进行测试时,所有匹配器都必须评估为“真”。例如,带有这些标签的警报:
{"alertname":"Watchdog","severity":"none"}
不会匹配这个匹配器列表:
matchers:
- alertname = Watchdog
- severity =~ "warning|critical"
在配置中,多个匹配器组合在一个 YAML 列表中。但是,也可以在单个 YAML 字符串中组合多个匹配器,再次使用受 PromQL 启发的语法。在这样的字符串中,前导{
和/或尾随}
是可选的,在进一步解析之前将被修剪。各个匹配器在字符串的引号部分之外用逗号分隔。这些逗号可能被空格包围。未转义双引号内的部分字符串"…"
被认为是引号(逗号在那里不充当分隔符)。如果使用单个反斜杠对双引号进行转义\
,则出于识别输入字符串的引号部分的目的,它们将被忽略。如果是输入字符串,修剪可选的尾随后}
, 以逗号结尾,后跟可选的空格,此逗号和空格将被删除。
以下是有效字符串匹配器的一些示例:
-
下面显示的是两个相等匹配器组合在一个长格式的 YAML 列表中。
matchers: - foo = bar - dings !=bums
-
与示例 1 类似,下面显示的是两个等式匹配器组合在一个短格式 YAML 列表中。
matchers: [ foo = bar, dings != bums ]
如下所示,在简写形式中,一般最好将列表元素用引号括起来,避免出现逗号等特殊字符的问题:
matchers: [ "foo = bar,baz", "dings != bums" ]
-
您还可以将两个匹配器放入一个类似 PromQL 的字符串中。整个字符串的单引号在这里效果最好。
matchers: [ '{foo="bar",dings!="bums"}' ]
-
为避免对 YAML 字符串引用和转义产生任何混淆,您可以使用 YAML 块引用,然后只需担心块内的 OpenMetrics 转义。下面显示了一个在标签值中包含正则表达式和不同引号的复杂示例:
matchers: - | {quote=~"She said: \"Hi, all!( How're you…)?\""}
<victorops_config>
VictorOps 通知通过VictorOps API发出
# Whether to notify about resolved alerts.
[ send_resolved: <boolean> | default = true ]
# The API key to use when talking to the VictorOps API.
[ api_key: <secret> | default = global.victorops_api_key ]
# The VictorOps API URL.
[ api_url: <string> | default = global.victorops_api_url ]
# A key used to map the alert to a team.
routing_key: <tmpl_string>
# Describes the behavior of the alert (CRITICAL, WARNING, INFO).
[ message_type: <tmpl_string> | default = 'CRITICAL' ]
# Contains summary of the alerted problem.
[ entity_display_name: <tmpl_string> | default = '{{ template "victorops.default.entity_display_name" . }}' ]
# Contains long explanation of the alerted problem.
[ state_message: <tmpl_string> | default = '{{ template "victorops.default.state_message" . }}' ]
# The monitoring tool the state message is from.
[ monitoring_tool: <tmpl_string> | default = '{{ template "victorops.default.monitoring_tool" . }}' ]
# The HTTP client's configuration.
[ http_config: <http_config> | default = global.http_config ]
<webhook_config>
Webhook 接收器允许配置通用接收器。
# Whether to notify about resolved alerts.
[ send_resolved: <boolean> | default = true ]
# The endpoint to send HTTP POST requests to.
url: <string>
# The HTTP client's configuration.
[ http_config: <http_config> | default = global.http_config ]
# The maximum number of alerts to include in a single webhook message. Alerts
# above this threshold are truncated. When leaving this at its default value of
# 0, all alerts are included.
[ max_alerts: <int> | default = 0 ]
Alertmanager 将以以下 JSON 格式向配置的端点发送 HTTP POST 请求:
{
"version": "4",
"groupKey": <string>, // key identifying the group of alerts (e.g. to deduplicate)
"truncatedAlerts": <int>, // how many alerts have been truncated due to "max_alerts"
"status": "<resolved|firing>",
"receiver": <string>,
"groupLabels": <object>,
"commonLabels": <object>,
"commonAnnotations": <object>,
"externalURL": <string>, // backlink to the Alertmanager.
"alerts": [
{
"status": "<resolved|firing>",
"labels": <object>,
"annotations": <object>,
"startsAt": "<rfc3339>",
"endsAt": "<rfc3339>",
"generatorURL": <string>, // identifies the entity that caused the alert
"fingerprint": <string> // fingerprint to identify the alert
},
...
]
}
有一个 与此功能集成的列表。
<wechat_config>
微信通知通过微信 API发送。
# Whether to notify about resolved alerts.
[ send_resolved: <boolean> | default = false ]
# The API key to use when talking to the WeChat API.
[ api_secret: <secret> | default = global.wechat_api_secret ]
# The WeChat API URL.
[ api_url: <string> | default = global.wechat_api_url ]
# The corp id for authentication.
[ corp_id: <string> | default = global.wechat_api_corp_id ]
# API request data as defined by the WeChat API.
[ message: <tmpl_string> | default = '{{ template "wechat.default.message" . }}' ]
# Type of the message type, supported values are `text` and `markdown`.
[ message_type: <string> | default = 'text' ]
[ agent_id: <string> | default = '{{ template "wechat.default.agent_id" . }}' ]
[ to_user: <string> | default = '{{ template "wechat.default.to_user" . }}' ]
[ to_party: <string> | default = '{{ template "wechat.default.to_party" . }}' ]
[ to_tag: <string> | default = '{{ template "wechat.default.to_tag" . }}' ]
<telegram_config>
# Whether to notify about resolved alerts.
[ send_resolved: <boolean> | default = true ]
# The Telegram API URL i.e. https://api.telegram.org.
# If not specified, default API URL will be used.
[ api_url: <string> | default = global.telegram_api_url ]
# Telegram bot token
[ bot_token: <string> ]
# ID of the chat where to send the messages.
[ chat_id: <int> ]
# Message template
[ message: <tmpl_string> default = '{{ template "telegram.default.message" .}}' ]
# Disable telegram notifications
[ disable_notifications: <boolean> | default = false ]
# Parse mode for telegram message, supported values are MarkdownV2, Markdown, HTML and empty string for plain text.
[ parse_mode: <string> | default = "MarkdownV2" ]
# The HTTP client's configuration.
[ http_config: <http_config> | default = global.http_config ]
发送警报
*免责声明*:Prometheus 自动负责发送由其配置的警报规则生成的警报。强烈建议在 Prometheus 中配置基于时间序列数据的警报规则,而不是实现直接客户端。
Alertmanager 有两个 API,v1 和 v2,都在侦听警报。v1 的方案在下面的代码片段中进行了描述。v2 的方案被指定为可以在Alertmanager 存储库中找到的 OpenAPI 规范。只要客户端仍然处于活动状态(通常在 30 秒到 3 分钟的数量级),它们就会不断地重新发送警报。客户端可以通过 POST 请求将警报列表推送到 Alertmanager。
每个警报的标签用于识别警报的相同实例并执行重复数据删除。注释始终设置为最近收到的注释,并且不标识警报。
startsAt
和时间戳都是endsAt
可选的。如果startsAt
省略,则当前时间由 Alertmanager 分配。endsAt
仅当警报的结束时间已知时才设置。否则,它将被设置为自上次收到警报以来的可配置超时时间。
该generatorURL
字段是一个唯一的反向链接,用于标识客户端中此警报的引发实体。
[
{
"labels": {
"alertname": "<requiredAlertName>",
"<labelname>": "<labelvalue>",
...
},
"annotations": {
"<labelname>": "<labelvalue>",
},
"startsAt": "<rfc3339>",
"endsAt": "<rfc3339>",
"generatorURL": "<generator_url>"
},
...
]