PromQL查询函数参考

## 一、概述

Prometheus 查询语言（PromQL）提供了一系列内置函数，用于对时序数据进行数学运算、统计分析、标签处理及预测分析等操作。
这些函数可接受不同类型的输入参数（如瞬时向量 *instant-vector*、区间向量 *range-vector*、标量 *scalar* 等），并返回相应类型的计算结果。

本文档对 PromQL 中常用的函数进行系统整理与说明，涵盖函数的语法定义、参数类型、功能描述、返回结果以及典型使用示例，旨在为技术人员在监控指标计算、告警表达式编写、趋势分析和系统调优中提供权威参考。

---

## 二、函数分类与说明

### 2.1 数学与统计函数

| 函数名       | 描述              | 输入类型           | 输出类型           |
| --------- | --------------- | -------------- | -------------- |
| `abs()`   | 计算绝对值           | instant-vector | instant-vector |
| `ceil()`  | 向上取整            | instant-vector | instant-vector |
| `floor()` | 向下取整            | instant-vector | instant-vector |
| `round()` | 四舍五入至最接近整数或指定倍数 | instant-vector | instant-vector |
| `sqrt()`  | 计算平方根           | instant-vector | instant-vector |
| `ln()`    | 计算自然对数          | instant-vector | instant-vector |
| `log2()`  | 计算以 2 为底的对数     | instant-vector | instant-vector |
| `log10()` | 计算以 10 为底的对数    | instant-vector | instant-vector |
| `exp()`   | 计算 e 的指数幂       | instant-vector | instant-vector |

#### 1. `abs(v instant-vector)`

返回输入向量中所有样本的绝对值。
**示例：**

```
abs(cpu_usage_total)
```

#### 2. `ceil(v instant-vector)`

将样本值向上舍入到最接近的整数。
**示例：**

```
ceil(node_load1)
```

#### 3. `floor(v instant-vector)`

将样本值向下舍入到最接近的整数。
**示例：**

```
floor(node_load1)
```

#### 4. `round(v instant-vector, to_nearest=1 scalar)`

将样本值四舍五入到最接近的整数倍，默认倍数为 1。
**示例：**

```
round(memory_usage_bytes / 1024 / 1024, 0.1)
```

#### 5. `sqrt(v instant-vector)`

计算每个样本值的平方根。
**示例：**

```
sqrt(disk_latency_seconds)
```

#### 6. `ln(v instant-vector)`

计算每个样本的自然对数。
**特殊规则：**

* `ln(+Inf)` = `+Inf`
* `ln(0)` = `-Inf`
* `ln(x < 0)` = `NaN`
* `ln(NaN)` = `NaN`

#### 7. `log2(v instant-vector)`

计算以 2 为底的对数。
**示例：**

```
log2(cpu_usage_total)
```

#### 8. `log10(v instant-vector)`

计算以 10 为底的对数。
**示例：**

```
log10(disk_write_bytes_total)
```

#### 9. `exp(v instant-vector)`

计算 e 的指数幂。
**特殊规则：**

* `exp(+Inf)` = `+Inf`
* `exp(NaN)` = `NaN`

---

### 2.2 统计变化与趋势分析函数

| 函数名                | 描述              | 输入类型         | 输出类型           |
| ------------------ | --------------- | ------------ | -------------- |
| `delta()`          | 区间差值            | range-vector | instant-vector |
| `increase()`       | 区间内累计增加值（针对计数器） | range-vector | instant-vector |
| `rate()`           | 区间平均增长率（计数器）    | range-vector | instant-vector |
| `irate()`          | 区间瞬时增长率（计数器）    | range-vector | instant-vector |
| `idelta()`         | 最后两个样本差值        | range-vector | instant-vector |
| `changes()`        | 值变化次数           | range-vector | instant-vector |
| `resets()`         | 计数器重置次数         | range-vector | instant-vector |
| `deriv()`          | 一阶导数（线性回归）      | range-vector | instant-vector |
| `predict_linear()` | 线性趋势预测          | range-vector | instant-vector |

#### 示例：

```
increase(http_requests_total[5m])
rate(http_requests_total[5m])
predict_linear(node_memory_Active_bytes[1h], 3600)
```

这些函数通常应用于：

* **计数器（counters）**：如请求总数、字节数；
* **Gauge 类型指标**：如温度、CPU 负载等；
* **趋势预测与异常检测**：使用 `deriv()` 或 `predict_linear()`。

---

### 2.3 标签处理函数

| 函数名               | 描述              |
| ----------------- | --------------- |
| `label_join()`    | 将多个标签的值连接为一个新标签 |
| `label_replace()` | 使用正则替换标签值       |

#### 1. `label_join(v, dst_label, separator, src_label1, src_label2, ...)`

将多个源标签的值通过分隔符 `separator` 连接，生成一个新的标签 `dst_label`。
**示例：**

```
label_join(up{job="etcd",service="etcd-k8s"}, "foo", ",", "job", "service")
```

结果：

```
up{foo="etcd,etcd-k8s", job="etcd", service="etcd-k8s"} 1
```

#### 2. `label_replace(v, dst_label, replacement, src_label, regex)`

对标签 `src_label` 的值进行正则匹配，若匹配成功，则将结果替换并写入新标签 `dst_label`。
**示例：**

```
label_replace(up{service="a:b"}, "foo", "$1", "service", "(.*):.*")
```

结果：

```
up{foo="a", service="a:b"} 1
```

---

### 2.4 时间函数

| 函数名              | 描述           | 返回范围      |
| ---------------- | ------------ | --------- |
| `year()`         | 当前 UTC 年份    | 1970–9999 |
| `month()`        | 月份（1–12）     | 1–12      |
| `day_of_month()` | 月内天数         | 1–31      |
| `day_of_week()`  | 星期（0=Sunday） | 0–6       |
| `hour()`         | 当前小时（UTC）    | 0–23      |
| `minute()`       | 当前分钟         | 0–59      |
| `time()`         | Unix 时间戳（秒）  | —         |
| `timestamp(v)`   | 返回样本时间戳      | 秒         |

**示例：**

```
hour(vector(time()))
day_of_week()
timestamp(up)
```

---

### 2.5 缺失值与条件函数

| 函数名              | 描述                        |
| ---------------- | ------------------------- |
| `absent()`       | 检测指标是否缺失，若缺失则返回样本值为 1 的结果 |
| `clamp_max()`    | 将样本值限制在最大值以下              |
| `clamp_min()`    | 将样本值限制在最小值以上              |
| `count_scalar()` | 统计样本总数，返回标量               |

**示例：**

```
absent(node_cpu_seconds_total)
clamp_max(http_requests_total, 100)
```

---

### 2.6 直方图与分位数函数

#### `histogram_quantile(φ, b instant-vector)`

从直方图类型的向量 `b` 中计算 φ 分位数（0 ≤ φ ≤ 1）。
常用于 `_bucket` 指标计算百分位响应时间、延迟等。

**典型用法：**

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

**注意事项：**

* 输入向量必须包含标签 `le`；
* 最高 bucket 必须为 `le="+Inf"`；
* 假定样本分布为线性。

---

### 2.7 区间聚合函数 `_over_time`

这些函数对区间向量执行时间范围内的统计聚合操作，返回瞬时向量。

| 函数名                    | 描述   |
| ---------------------- | ---- |
| `avg_over_time()`      | 平均值  |
| `min_over_time()`      | 最小值  |
| `max_over_time()`      | 最大值  |
| `sum_over_time()`      | 求和   |
| `count_over_time()`    | 样本数  |
| `quantile_over_time()` | 分位数  |
| `stddev_over_time()`   | 标准偏差 |
| `stdvar_over_time()`   | 标准方差 |

**示例：**

```
avg_over_time(node_cpu_seconds_total[5m])
max_over_time(http_request_duration_seconds_sum[1h])
```

---

## 三、使用规范与建议

1. **计数器（Counter）类型指标**
   推荐使用：`rate()`、`increase()`、`resets()`、`irate()`
   用于累计值的速率分析与重置检测。

2. **Gauge 类型指标**
   推荐使用：`delta()`、`deriv()`、`predict_linear()`
   用于趋势变化与预测分析。

3. **标签管理**
   使用 `label_join()`、`label_replace()` 进行标签规范化处理，确保聚合维度统一。

4. **缺失检测与异常监控**
   `absent()` 可用于判断指标采集是否中断，是监控告警中的常用辅助函数。

5. **聚合操作顺序**
   组合函数时，务必遵循：

```
   rate() → sum() → histogram_quantile()
   ```

即先计算速率，再聚合，再分位数分析。

---

## 四、附录

**参数类型说明：**

| 参数类型             | 说明           |
| ---------------- | ------------ |
| *instant-vector* | 单时刻样本集合      |
| *range-vector*   | 一段时间内的样本序列集合 |
| *scalar*         | 单一数值         |
| *string*         | 文本标签值        |