简介

Prometheus使用扫盲，包含基础的概念和操作说明，基于官网和个人测试。

versoin: 2.14

官网

GitHub

安装

prometheus安装运行非常方便，下载后解压，运行根目录下的可执行程序prometheus即可。

启动参数

常用启动参数说明

管理API

参见MANAGEMENT API

本地存储

（1）存储方式

​ 样本被分组存储，每组存储两个小时的样本和元数据、索引，样本以一个或多个chunk文件存储，执行数据删除时首先执行的是逻辑删除，而非物理删除。

.
├── 01DWGZHP8QP5WC7XJF3ECEEYH1  //分组
│   ├── chunks                  //样本
│   │   └── 000001
│   ├── index                   //索引
│   ├── meta.json               //元数据 
│   └── tombstones
├── 01DWH1PBH94RF9E5H9JV1JV040
│   ├── chunks
│   │   └── 000001
│   ├── index
│   ├── meta.json
│   └── tombstones
├── lock
├── queries.active
└── wal                          //预写入日志
    ├── 00000004
    ├── 00000005
    ├── 00000006
    ├── 00000007
    ├── 00000008
    └── checkpoint.000003
        └── 00000000

（2）预写入日志（WAL）

​ chunk中写入的数据首先保存在内存里，未直接持久化。通过write-ahead-log (WAL) 预写入日志可以确保在prometheus崩溃后重新启动时回放日志，恢复数据。默认128MB的segments，支持压缩（需手动开启），最大支持10%时间的block增长，或者21天，先到为准。

注：压缩功能是2.12版本开始引入，因wal格式内容发生变化，如果回退至2.11或以下的版本，需删除wal。

可通过–storage.tsdb.wal-segment-size设置wal的segments大小。

参见Local storage、Compaction

配置

Prometheus配置

具体配置项内容较多，主要描述整体配置模块及主要作用，参数明细参见官方描述。

# 配置全局指标采集周期、超时、告警采集频率等
global:
  
# 全局告警规则文件文件列表
rule_files:

# 指标数据采集，包含多个job_name，配置对应的地址、采集接口等
scrape_configs:
 
# 关联告警模块Alertmanager的相关配置
alerting:

# 使用三方模块存储数据时的远程写配置
remote_write:

# 使用三方模块存储数据时的远程读配置
remote_read:

规则配置

prometheus规则配置包括两种规则：

• recording rules：记录规则，用于对指定计算的预处理，通过服务端定时执行，客户端在查询时就不需要根据PromQL表达式实时计算，可以直接返回结果。
• alerting rules：告警规则，配置满足某一特定规则后触发告警。

规则文件在服务启动时会自动校验配置文件的语法、格式，同时提供离线工具校验promtool（prometheus安装根目录下）:

./promtool check rules /path/to/example.rules.yml

groups:
  # [ - <rule_group> ],一组规则
  
  # 执行频率，可选，默认global.evaluation_interval
  interval: 15s
  # 当前配置文件中唯一名称
  - name: example
    # 规则
    rules:
    
    # recording rules
    # record指标名称
    - record: job:http_inprogress_requests:sum
      # PromQL表达式
      expr: sum(http_inprogress_requests) by (job)
      # 记录规则结果中标签，新增/覆盖原始
      labels:
        type: recording
        
    # alerting rules
    # alert指标名称
    - alert: HighRequestLatency
      # PromQL表达式
      expr: job:request_latency_seconds:mean5m{job="myjob"} > 0.5
      # 满足告警条件持续多久后，触发告警
      for: 10m
      # 告警标签，新增/覆盖原始
      labels:
        severity: page
      # 告警注释
      annotations:
        summary: High request latency

PromQL

概述

返回类型

Prometheus通过自身提供的PromQL语法查询或统计，查询的结果包含四种数据类型：

• Instant vector ：瞬时向量，一组时序数据，每个时序数据包含唯一的样本，如*_tatal{}、*_count{}
• Range vector：范围向量，一组时序数据，每个时序数据包含范围内的样本，如*{}[1m]
• Scalar ：标量，浮点数字，如sum()、count()
• String：字符串，未使用

参见Expression language data types

时序选择器

（1）瞬时向量

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

针对瞬时向量http_requests_total，通过{}描述一组选择器，等同SQL中where条件，支持四种操作符：

=等于、!=不等于、=~ 正则匹配、!~ 正则不匹配

支持的正则表达式语法RE2

（2）范围向量

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

范围向量通过[]描述查询的范围，等同SQL的between，支持以下六种时间单位：

s秒、m 分、h时、d天、w周、y年

（3）偏移量

sum(http_requests_total{method="GET"} offset 5m)
rate(http_requests_total[5m] offset 1w)

通过offset查询指定偏移范围的数据，必须紧跟在选择器之后，不合法使用：

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

参见Time series Selectors

子查询

针对给定的范围和颗粒度进行瞬时向量查询，结果为范围向量：

rate(http_requests_total[5m])[20m:2m]

解析：

1. 范围：20m
2. 颗粒度：2m
3. 瞬时向量：http_requests_total[5m]
4. 范围向量：20m内，每隔2m的5m增长率

操作符

二元运算符

（1）算数运算符：

+加、-减、*乘、/除、%取余、^乘方

可用在以下操作：

• 两个scalar
• instant vector和scalar，instant vector中每个样本的值都会与scalar进行运算
• 两个instant vector，取两个vector的样本交集进行运算，结果存放在新的vector中，结果的指标名称将被删除。

（2）比较运算符：

==等于、!=不等于、> 大于、<小于、>=大于等于、<=小于等于

默认情况下，比较的运算结果，是返回两个向量中满足比较的样本，可通过运算符后加关键字bool来改变比较的结果，0表示false，1表示true，支持以下几种类型的比较：

• 两个scalar，必须在运算符后添加bool，返回0/1
• instant vector和scalar，scalar与instant vector中每个样本进行比较。当使用bool时，返回instant vector中全量样本的比较结果；未使用bool时，仅返回满足比较的样本。
• 两个instant vector，取两个vector的样本交集进行比较。当使用bool时，返回所有交集样本的比较结果（0或1）；未使用bool时，仅返回满足比较的样本内容（交集但不匹配也不会返回）。

（3）逻辑运算符

and与、or或、unless补

说明：v1 unless v2所获取的结果是v1中有，v2中没有的，返回内容是v1中的样本。

（4）优先级

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

优先级自上至下，运算顺序从左到右，^除外，从右到左。

向量匹配

（1）one-to-one

两个向量在操作时vector1 <operator> vector2，默认匹配是按照标签和标签值全部匹配时才可以进行运算，使用ignoring关键字忽略一组匹配的标签，使用on关键字仅匹配指定的一组标签。

# 忽略le标签，匹配handler标签
prometheus_http_response_size_bytes_bucket{handler="/",le="100"} / ignoring (le) prometheus_http_response_size_bytes_count

# 使用handler匹配
prometheus_http_response_size_bytes_bucket{handler="/",le="100"} / on (handler) prometheus_http_response_size_bytes_count

（2）many-to-one / one-to-many

比较复杂，多数情况使用ignoring就可以处理，不做描述。

聚合运算

• sum(v instant-vector) 和
• min(v instant-vector) 最小值
• max(v instant-vector) 最大值
• avg(v instant-vector) 平均值
• stddev(v instant-vector) 标准差
• stdvar(v instant-vector) 标准方差
• count(v instant-vector) 样本数量
• count_values(lable_name string, v instant-vector) 计算向量样本中各个value出现的次数
• bottomk(k scalar, v instant-vector) 取最小k个value
• topk(k scalar, v instant-vector) 取最大的k个value
• quantile(φ scalar, v instant-vector) 计算分位数

使用without排除结果中的标签，by根据指定标签分组统计，仅适用输入向量的处理，语法：

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

例：

# 指标prometheus_http_response_size_bytes_bucket根据handler标签分组求和
sum by (handler) (prometheus_http_response_size_bytes_bucket) 

# 指标prometheus_http_response_size_bytes_bucket排除handler标签后，分组求和
sum(prometheus_http_response_size_bytes_bucket) without (handler)

函数

• abs(v instant-vector)：返回给定瞬时向量的所有样本的绝对值
• absent(v instant-vector)：如果给定瞬时向量包含样本，则返回空；如果给定向量为空，则返回不包含指标名的样本，value为1
• ceil(v instant-vector)：瞬时向量值向上取整
• changes(v range-vector)：返回给定范围向量的值变化次数，即value的枚举数
• clamp_max(v instant-vector, max scalar)：设定给定瞬时向量的上限值：低于给定max保持原值，高于max则为max
• clamp_min(v instant-vector, min scalar)：设定给定瞬时向量的下限值：高于给定min保持原值，低于min则为min
• day_of_month(v=vector(time()) instant-vector)：返回给定的UTC时间是当月的第几天，取值1-31
• day_of_week(v=vector(time()) instant-vector)：返回给定的UTC时间是本周的第几天，取值0-6，0为周日
• days_in_month(v=vector(time()) instant-vector)：返回给定的UTC时间的月份有多少天，取值28-31
• delta(v range-vector)：计算范围向量中第一个值和最后一个值的差值，用于gauge
• deriv(v range-vector)：使用简单线性回归计算范围向量中时间序列的二阶导数，用于gauge
• exp(v instant-vector)：返回给定瞬时向量值的指数函数值，即e^value，value很大时返回+Inf。特殊情况：Exp(+Inf) = +Inf、Exp(NaN) = NaN
• floor(v instant-vector)：瞬时向量向下取整
• histogram_quantile(φ float, b instant-vector)：计算给定瞬时向量的百分位数（0<=φ<=1）,用于直方图(histogram)的bucket百分位数计算。如果直方图buckets少于2，返回NaN，如果给定的百分位数φ<0，返回-Inf；φ>1，返回+Inf
• holt_winters(v range-vector, sf scalar, tf scalar)：生成给定向量的平滑值，平滑因子sf越低老数据越重要，趋势因子tf越高趋势数据越重要，用于gauge
• hour(v=vector(time()) instant-vector)：返回给定的UTC时间的小时，取值0-23
• idelta(v range-vector)：计算范围向量最后两个值的差，用于gauge
• increase(v range-vector)：计算范围向量最后一个值减去第一个值的差，仅应用于counter，打破单调性时（如由于目标重启导致的计数器重置）会自动调整。
• irate(v range-vector)：计算范围向量的瞬时增长率，样本最后两个值的增长率，仅适用于计算快速变化的值，趋势分析使用rate()，打破单调性时（如由于目标重启导致的计数器重置）会自动调整
• label_join(v instant-vector, dst_label string, separator string, src_label_1 string, src_label_2 string, ...)：对瞬时向量中每一个样本，将src_lable(范围向量中指标的标签)的value使用separator拼接，结果存放在新标签dst_label中，相当于给原始样本新增了一个dst_label
• label_replace(v instant-vector, dst_label string, replacement string, src_label string, regex string)：对瞬时向量的每个样本，满足正则regex匹配的标签src_label，将指定的正则子组replacement（用$1、$2...表示）放入目标标签dst_label
• ln(v instant-vector)：瞬时向量样本自然对数(e)，特殊情况：ln(+Inf) = +Inf、ln(0) = -Inf、ln(x < 0) = NaN、ln(NaN) = NaN
• log2(v instant-vector)：瞬时向量2的对数
• log10(v instant-vector)：瞬时向量10的对数
• minute(v=vector(time()) instant-vector)：给定的UTC时间是当前小时的多少分钟，取值0-59
• month(v=vector(time()) instant-vector)：给定的UTC时间是当前年份第几个月，取值1-12
• predict_linear(v range-vector, t scalar)：基于范围向量使用简单线性回归，预测从当前开始t秒后的值
• rate(v range-vector)：计算范围向量的平均增长率，打破单调性时（如由于目标重启导致的计数器重置）会自动调整，适用趋势分析和告警，用于counter类型。与聚合操作符或聚合函数一起使用时，需先执行rate再执行聚合，否则rate无法检测到重置。
• resets(v range-vector)：返回范围向量中计时器的重置次数，以瞬时向量返回，两个连续样本数值发生减少则认为重置，用于counter
• round(v instant-vector, to_nearest=1 scalar)：使用瞬时向量样本进行计算，返回值是to_nearest的整数倍，该值与样本值偏差最小。如样本值为sample_value，存在**(n-1)*to_nearest < sample_value < n*to_nearest**，则与sample_value差值小的一侧值为计算结果，如果差值相等，选较大值。
• scalar(v instant-vector)：给定瞬时向量的样本值转为标量，样本数量=0或>1时，返回NaN
• sort(v instant-vector)：瞬时向量样本值升序排列
• sort_desc(v instant-vector)：瞬时向量样本值降序排列
• sqrt(v instant-vector)：瞬时向量的样本值开方
• time()：返回表达式计算的时间。
• timestamp(v instant-vector)：返回瞬时向量中每个样本的时间戳。
• vector(s scalar)：scalar转为vector，不含标签
• year(v=vector(time()) instant-vector)：返回给定时间的年
• <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): scalar在vector中的分位数
  • stddev_over_time(range-vector): 标准差
  • stdvar_over_time(range-vector): 标准方差

详细描述，见FUNCATIONS。

HTTP API

API接口请求返回2xx状态码，响应数据是json格式。

异常请求返回：

• 400 Bad Request 参数错误
• 422 Unprocessable Entity 表达式无法执行
• 503 Service Unavailable 请求超时或被丢弃

响应数据如下：

{
  "status": "success" | "error",   // 请求状态
  "data": <data>,                  // 响应数据

  // 请求异常时返回，status为error
  "errorType": "<string>",
  "error": "<string>",

  // 请求存在警告时返回
  "warnings": ["<string>"]
}

表达式查询

当查询返回结果超过server端字符限制时，可将参数使用URL编码，并指定请求方式为POST，请求头Content-Type: application/x-www-form-urlencoded。

查询返回格式：

{
  "resultType": "matrix" | "vector" | "scalar" | "string",   // 响应格式
  "result": <value>                                          // 响应值
}

上述返回为HTTP API中<data>标签内容，返回具体格式见响应格式。

查询主要包含以下两种：

（1）瞬时查询

API：

GET /api/v1/query
POST /api/v1/query

Params：

• query=: PromQL表达式
• time=: 时间，默认当前服务器时间，可选
• timeout=: 超时时间，默认使用-query.timeout，可选

（2）范围查询

API：

GET /api/v1/query_range
POST /api/v1/query_range

Params：

• query=: PromQL表达式
• start=: 开始时间
• end=: 结束时间
• step=: 查询周期间隔
• timeout=: 超时时间，默认使用-query.timeout，可选

响应格式

API表达式查询的返回格式，包括matrix, vector, scalar, string四种，对应PromQL定义的四种返回类型，以下描述的返回格式，均为表达式查询中result标签内容。

（1）Range vectors

范围向量返回格式定义为matrix：

[
  {
    "metric": { "标签名": "标签值", ... },
    "values": [ [ 时间戳, "样本值" ], ... ]
  },
  ...
]

（2）Instant vectors

瞬时向量格式定义为vector：

[
  {
    "metric": { "标签名": "标签值", ... },
    "value": [ 时间戳, "样本值" ]
  },
  ...
]

（3）scalar

标量格式定义为scalar：

[ 时间戳, "数值" ]

（4）string

字符串定义为string：

[ 时间戳, "字符串值" ]

元数据查询

（1）根据标签查找指标

当查询返回结果超过server端字符限制时，可将参数使用URL编码，并指定请求方式为POST，请求头Content-Type: application/x-www-form-urlencoded。

API：

GET /api/v1/series
POST /api/v1/series

Params：

• match[]=: 一个或多个匹配选择器，至少一个
• start=: 开始时间
• end=: 结束时间

（2）查询标签名

API：

GET /api/v1/labels
POST /api/v1/labels

（3）查询标签值

API：

GET /api/v1/label/<label_name>/values

目标查询

查询prometheus监控的目标对象的状态信息。

API：

GET /api/v1/targets

规则查询

返回当前已加载的预警规则信息，和由实例触发的告警规则，该新增API稳定性暂时不能保证。

API：

GET /api/v1/rules

告警查询

返回当前激活的告警列表，该新增API稳定性暂时不能保证。

GET /api/v1/rules

目标元数据查询

试验性接口，可能变动，建议不应用。

API:

GET /api/v1/targets/metadata

Params:

• match_target=: 标签选择器，为空匹配所有目标
• metric=: 指标名称，为空匹配所有指标
• limit=: 最大匹配数

AlertManager状态查询

告警组件AlertManager状态查询。

API：

GET /api/v1/alertmanagers

状态查询

查询当前prometheus相关配置信息。

API：

GET /api/v1/status/config           // 返回当前已加载的配置yaml文件内容，不含注释
GET /api/v1/status/flags            // 返回prometheus启动配置项信息
GET /api/v1/status/runtimeinfo      // 返回运行信息，如启动时间、chunk数、安装目录等
GET /api/v1/status/buildinfo        // 返回prometheus版本构建信息

数据库管理API

所有数据库管理API需要开启--web.enable-admin-api。

（1）快照

接口用于保存实时数据的快照，数据存放在<data-dir>/snapshots/<datetime>-<rand>，接口返回生成的数据目录名称<datetime>-<rand>。

API：

POST /api/v1/admin/tsdb/snapshot
PUT /api/v1/admin/tsdb/snapshot

Params：

• skip_head=: 跳过头块中未压缩的数据，可选。

（2）删除

用于删除时间段内指定的指标数据，数据不会被立即删除，会在后续清理或调用清理的接口。操作成功会返回204.

API：

POST /api/v1/admin/tsdb/delete_series
PUT /api/v1/admin/tsdb/delete_series

Params：

• match[]=: 一个或多个匹配选择器，至少一个
• start=: 开始时间，可选，默认最小时间。
• end=: 结束时间，可选，默认最大时间

（3）清理

用于清理 已删除的数据，会立即释放磁盘空间，操作成功返回204

API：

POST /api/v1/admin/tsdb/clean_tombstones
PUT /api/v1/admin/tsdb/clean_tombstones