PromQL 快速上手

1.简介

PromQL 是 Prometheus 监控系统的查询语言，语法简洁且功能强大。

PromQL 的语法跟一般的 SQL 语言很不一样，初学者往往需要花费几个小时阅读 官方 PromQL 文档 才能理解它的工作原理。

这里请跟随我们的思路，一起快速理解 PromQL 的设计精髓并掌握 PromQL 的用法。

2.主要特点

功能性查询语言:

PromQL 提供了一种功能性查询语言，允许用户以一种声明式的方式来描述他们想要的数据，而不是以过程式的方式来一步一步地操作。

丰富的功能:

PromQL 支持各种运算符、函数和聚合函数，可以实现复杂的查询和计算逻辑。

广泛应用：

PromQL 被广泛应用于 Prometheus 监控系统中，用于数据查询、可视化、警报等场景。

3.基本用法

PromQL 查询的基本语法是：

[selector] [modifier]

selector 用于选择时间序列，例如：http_requests_total 或 http_requests_total{job=“my-web-app”}。

modifier 用于对选择的时间序列进行操作，例如聚合、过滤、计算等。

PromQL 的一些常见用法：

• 查询特定指标：查询某个指标，例如 http_requests_total。
• 过滤指标：过滤掉特定标签的指标，例如 http_requests_total{status_code="200"}。
• 聚合指标：对指标进行聚合，例如 sum(http_requests_total) 或 avg(node_cpu_seconds_total{mode="idle"})。
• 计算指标：对指标进行计算，例如 sum(rate(http_requests_total[5m]))。
• 警报规则：在 PromQL 表达式中定义警报规则，当表达式的结果满足一定条件时触发警报

4.数据类型

PromQL 支持四种数据类型：

• 瞬时向量(Instant vector)：一组时间序列，每个时间序列包含一个样本，都共享相同的时间戳。
• 区间向量(Range vector)：一组时间序列，其中包含每个时间序列随时间变化的一系列数据点。
• 标量(Scalar)：一个单独的值，例如数字。
• 布尔值(Boolean)：True 或 False。

其中 Prometheus 时序数据是其监控系统的核心存储对象，本质是带有时间戳的多维度量值。

数据结构模型：

type Sample struct {
    Metric    map[string]string // 标签键值对
    Value     float64           // 数值
    Timestamp int64             // Unix 毫秒时间戳
}

示例数据点：

{
  metric: {
    __name__="http_requests_total",
    method="POST",
    status="200",
    endpoint="/api/login"
  },
  value: 1845.0,
  timestamp: 1717254000000
}

5.Prometheus 的四种指标类型

Prometheus 主要定义了四种核心指标类型（Metric Types），它们在客户端库（如 Go、Java、Python 等）中实现，并在抓取时通过 HELP 和 TYPE 行提供给 Prometheus 服务器。理解这些类型对于正确查询和聚合数据至关重要。

计数器（Counter）跟踪只能增加的累计值。它们通常用于跟踪处理的请求、错误和传输的字节数等。

仪表盘 (Gauge) 。代表一个瞬时的、可升可降的测量值。它们通常用于跟踪内存用量、CPU 用
量和磁盘可用空间等。

直方图（Histogram）跟踪值的分布情况。它们通常用于跟踪请求延迟时间和响应大小等。

摘要（Summary）与直方图类似，但它们还跟踪分位数。因此，它们对于识别离群值和了解值的整体分布更有用。

6.常用函数

PromQL 提供了丰富的函数来处理和分析时间序列数据。

聚合运算符 (Aggregation Operators)

Prometheus 还提供了聚合操作符，这些操作符作用于瞬时向量。可以将瞬时表达式返回的样本数据进行聚合，形成一个新的时间序列。目前支持的聚合函数有：

• sum (求和)
• min (最小值)
• max (最大值)
• avg (平均值)
• stddev (标准差)
• stdvar (标准方差)
• count (计数)
• count_values (对value进行计数)
• bottomk (后n条时序)
• topk (前n条时序)
• quantile (分位数)

速率与增量 (Rate and Derivatives)

计算时间序列的变化率：

• rate(range_vector)

计算区间内每秒平均增长率（自动处理计数器重置）。适用于单调递增的计数器（如请求数）。

• irate(range_vector)

计算区间内最后两个点的瞬时增长率（更敏感，适合快速变化）。

• increase(range_vector)

计算区间内的绝对增长量（自动处理重置）。

• delta(range_vector)

计算区间内样本值的差值（可正可负，适用于非计数器如温度）。

计数器处理 (Counter Resets)

处理计数器的重置（归零）问题：

• resets(range_vector)

返回区间内计数器重置的次数。

示例：

// 1小时内CPU时间重置次数
resets(process_cpu_seconds_total[1h])

时间操作 (Time and Date)

• time()

返回当前Unix时间戳（秒）。

• year(timestamp_vector)

返回年份。

• month/day/hour/minute/second(timestamp_vector)

返回时间成分值。

标签操作 (Label Manipulation)

修改时间序列的标签：

// 基于正则替换标签值。
label_replace(vector, "dst_label", "replacement", "src_label", "regex")

// 将多个标签值连接为新标签。
label_join(vector, "dst_label", "separator", "src_label1", "src_label2", ...)

示例：从 instance=“1.2.3.4:9100” 提取主机名到新标签 host=“1.2.3.4”。

label_replace(up{job="node"}, "host", "$1", "instance", "(.*):\d+")

数学运算 (Mathematical Functions)

// 绝对值
abs(vector)

// 四舍五入
round(vector, scalar)

// 向上/向下取整。
- ceil/floor(vector)

// 对数计算。
- ln/log2/log10(vector)

// 指数/幂运算。
- exp/pow(vector, scalar)

示例：

// 内存使用量保留两位小数
round(avg_over_time(memory_usage[5m]), 0.01)

逻辑与过滤 (Logical and Filtering)

• absent(vector)
  检测序列是否不存在（常用于告警）。

• absent_over_time(range_vector)
  检测时间段内是否无数据。

• clamp_max/clamp_min(vector, scalar)
  限制值的上下限。

示例：

// 若MySQL实例消失则触发
absent(up{job="mysql"} == 1)

特殊函数

• histogram_quantile(φ, vector)
  直方图分位数计算：根据 _bucket 和 _sum 计算分位数（如P99）。

• predict_linear(range_vector, scalar)
  基于线性回归预测未来值（如磁盘占满时间）。

示例：

// 计算P99请求延迟
histogram_quantile(0.99, sum by(le) (rate(http_request_duration_seconds_bucket[5m])))

排序 (Sorting)

• sort(vector)
  升序排列。

• sort_desc(vector)
  降序排列。

示例：

// 内存使用量最高的3个序列升序显示
sort(topk(3, memory_usage))

---

参考文献

官方 PromQL 文档
Prometheus 和 PromQL 是什么？