> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flashcat.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Prometheus

> 配置 Prometheus 数据源的告警规则，支持 PromQL 查询语法

Monitors 兼容 Prometheus 的 PromQL 查询语法，并提供了灵活的告警判定与恢复机制。

## 核心概念

告警引擎支持三种核心判定模式：

<CardGroup cols={3}>
  <Card title="阈值判定" icon="gauge">
    查询返回原始指标数值，由告警引擎在内存中进行阈值比对
  </Card>

  <Card title="数据存在" icon="database">
    查询语句包含过滤条件，仅返回异常数据，查到数据即告警
  </Card>

  <Card title="数据缺失" icon="circle-exclamation">
    用于监控数据上报中断的场景
  </Card>
</CardGroup>

## 1. 阈值判定模式

此模式适用于需要对同一指标进行多级告警（如 Info/Warning/Critical）或需要获取精确恢复值的场景。

### 配置方式

* **查询语句 (PromQL)**：编写 **不包含** 比较运算符的 PromQL，只返回指标数值。
  * 示例：查询内存使用率
    ```promql theme={null}
    (node_memory_MemTotal_bytes - node_memory_MemAvailable_bytes) / node_memory_MemTotal_bytes * 100
    ```
* **阈值条件**：在规则配置中定义不同严重级别的阈值表达式。变量 `$A` 代表查询结果的值。
  * **Critical**：`$A > 90`（内存使用率超过 90% 触发严重告警）
  * **Warning**：`$A > 80`（内存使用率超过 80% 触发警告告警）

### 多查询支持与数据关联

Monitors 支持在一个告警规则中配置多条查询语句（分别命名为 A、B、C...），并支持在阈值表达式中同时引用这些查询结果（如 `$A > 90 and $B < 50`）。

* **自动关联**：告警引擎会自动根据 **标签** 对不同查询语句返回的结果进行关联。
* **对齐要求**：只有当两条查询语句返回的数据包含 **完全相同** 的标签集时，它们才能被关联到同一组上下文中进行计算。
  * 示例：查询 A 返回 `cpu_usage_percent{instance="host-1", job="node"}`，查询 B 返回 `mem_usage_percent{instance="host-1", job="node"}`，则 `$A` 和 `$B` 可以成功关联。
  * 注意：如果查询 A 多了一个标签（如 `disk="/"`），而查询 B 没有，则无法关联。建议在 PromQL 中使用 `sum by (...)` 或 `avg by (...)` 等聚合操作，显式控制返回的标签，确保多条查询结果的标签一致。

### 工作原理

告警引擎周期性执行 PromQL，获取所有 Series 的当前值。随后，引擎遍历每个 Series，依次匹配 Critical、Warning、Info 条件。一旦满足某个级别的条件，即产生对应级别的告警事件。

### 恢复逻辑

支持多种恢复策略：

| 策略         | 说明                                   |
| ---------- | ------------------------------------ |
| **自动恢复**   | 当最新查询结果不再满足任何告警阈值时，自动生成恢复事件          |
| **特定恢复条件** | 可配置额外的恢复表达式（如 `$A < 75`），避免在阈值附近频繁震荡 |
| **恢复查询**   | 自定义一条 PromQL 用于恢复判定，查到数据即恢复          |

<Note>
  恢复查询语句支持嵌入变量（格式为 `${label_name}`），会被自动替换为告警事件中对应的标签值，实现针对具体告警对象的精确检测。
</Note>

## 2. 数据存在模式 (Data Exists)

此模式与 Prometheus 原生告警规则（Alerting Rules）的行为一致。适用于习惯直接在 PromQL 中定义阈值的用户，或需要高性能处理大量 Series 的场景。

### 配置方式

* **查询语句**：编写 **包含** 比较运算符的 PromQL，仅筛选出异常数据。
  * 示例：查询内存使用率超过 90% 的节点
    ```promql theme={null}
    (node_memory_MemTotal_bytes - node_memory_MemAvailable_bytes) / node_memory_MemTotal_bytes * 100 > 90
    ```
* **判定规则**：无需额外配置阈值表达式。引擎只要查询到结果，即认为触发告警，查到几条数据就生成几个告警事件。

### 恢复逻辑

* **数据消失即恢复**：引擎周期性查询，如果某些数据查不到了，引擎判定对应的告警恢复。注意：数据的标识是基于标签集的。
* **恢复查询（可选）**：可配置一个独立的查询语句用于判定恢复（例如查询 `up{instance="${instance}"} == 1` 来确认服务恢复），查到数据才算恢复。这个 QL 中引入了变量 `${instance}`，会被替换为告警事件中的具体标签值。

### 优缺点分析

<Tabs>
  <Tab title="优点">
    * **性能更优**：过滤逻辑下推至 Prometheus 服务端，减少了传输到告警引擎的数据量
    * **迁移成本低**：可直接复用现有的 Prometheus Rule 语句
  </Tab>

  <Tab title="缺点">
    * **单一级别**：一条规则通常对应一个严重级别（如需区分 >90 和 >80，需配置两条规则）
    * **现场值获取**：恢复时无法直接获取恢复时的具体数值（可使用关联查询获取）
  </Tab>
</Tabs>

## 3. 数据缺失模式 (No Data)

此模式专门用于监控监控对象是否存活或数据上报链路是否正常。

### 配置方式

* **查询语句**：编写预期应该一直存在的指标查询。
  * 示例：`up{job="my-service"}`
* **判定规则**：如果连续 N 个周期无法查询到该 Series 的数据（注意：是完全查不到数据，而不是值为 0），则触发"数据缺失"告警。
* **引擎重启**：如果告警引擎（monitedge）重启，内存中的状态丢失，如果重启之前可以查到的数据重启之后恰好查不到了，则无法告警。重启之后会重新开始统计缺失周期。

### 典型应用

* 监控 Exporter 宕机。
* 监控埋点上报服务中断。
* 监控批处理任务未按时执行。

### 对比 Prometheus 原生的 `absent()` 函数

| 方式                    | 说明                           |
| --------------------- | ---------------------------- |
| Prometheus `absent()` | 需要把每个标识类的标签组合都列举出来，多个实例需多条语句 |
| Monitors 数据缺失模式       | 只需一条查询语句，自动对所有 Series 进行监控   |

## 高级配置

### 标签与变量

Monitors 会自动解析 Prometheus 返回的 Labels。在 **恢复查询** 或 **关联查询** 中，可以使用 `${label_name}` 引用标签值。

比如某个告警规则查询语句返回的结果包含标签 `instance="host-1"` 和 `job="node"`，则在恢复查询中可以这样写：

```
up{instance="${instance}", job="${job}"} == 1
```

告警引擎执行时，会将 `${instance}` 替换为 `host-1`，`${job}` 替换为 `node`，也就是告警事件标签中的具体值。

### 关联查询 (Enrichment)

为了丰富告警通知的内容，可以配置"关联查询"。关联查询不参与告警判定，仅用于获取额外信息。

* **场景**：CPU 告警时，同时查询该机器的 `mem_usage_percent` 负载情况，展示在告警详情中，辅助排查。
* **变量**：关联查询中支持 `${label_name}` 变量，用于针对具体告警对象查询。
* **结果展示**：关联查询的结果可以在告警规则的备注描述中引用，其变量是 `$relates`，您可以查看 **备注描述** 的详细使用说明。