> ## 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.

# PostgreSQL

> 配置 PostgreSQL 数据源的告警规则，支持标准 SQL 语法

Monitors 支持使用标准 SQL 语法对 PostgreSQL 进行查询，并根据查询结果触发告警。

## 核心概念

| 配置项      | 说明                                         |
| -------- | ------------------------------------------ |
| **查询语言** | 使用 PostgreSQL SQL 语法                       |
| **字段处理** | 所有字段名自动转换为小写，配置时请使用小写字母                    |
| **时间处理** | 建议使用 `NOW()`、`CURRENT_TIMESTAMP` 等函数进行时间过滤 |

## 1. 阈值判定模式

此模式适用于需要对聚合后的数值进行阈值比对的场景。

### 配置方式

1. **查询语句**：编写 SQL 聚合查询，返回数值列和（可选的）标签列。

* 示例：统计最近 5 分钟内，各服务的错误日志数量。
  ```sql theme={null}
  SELECT 
      service_name, 
      count(*) AS error_cnt 
  FROM app_log 
  WHERE log_time > NOW() - INTERVAL '5 minutes' AND level = 'error'
  GROUP BY service_name
  ```

2. **字段映射**：

* **标签字段**：用于区分不同告警对象的字段。上例中为 `service_name`。该字段可以留空，Monitors 会自动把除了值字段外的所有字段都作为标签字段。
* **值字段**：用于阈值判定的数值字段。上例中为 `error_cnt`。

3. **阈值条件**：

* 使用 `$A.field_name` 引用数值。
* 示例：`Critical: $A.error_cnt > 50`，`Warning: $A.error_cnt > 10`。

### 工作原理

引擎执行 SQL 查询，获取结果集。根据"标签字段"将数据分组，然后提取"值字段"的数值与阈值表达式进行比对。

### 恢复逻辑

| 策略         | 说明                                  |
| ---------- | ----------------------------------- |
| **自动恢复**   | 当数值不再满足任何告警阈值时，自动生成恢复事件             |
| **特定恢复条件** | 配置恢复表达式（如 `$A.error_cnt < 5`）       |
| **恢复查询**   | 独立 SQL 用于恢复判定，支持 `${label_name}` 变量 |

## 2. 数据存在模式

此模式适用于将过滤逻辑直接写在 SQL 中的场景。

### 配置方式

1. **查询语句**：在 SQL 中使用 `HAVING` 子句直接过滤出异常数据。

* 示例：直接查询错误数超过 50 的服务。
  ```sql theme={null}
  SELECT 
      service_name, 
      count(*) AS error_cnt 
  FROM app_log 
  WHERE log_time > NOW() - INTERVAL '5 minutes' AND level = 'error'
  GROUP BY service_name
  HAVING count(*) > 50
  ```

2. **判定规则**：只要 SQL 查询返回了数据，即触发告警。

### 优缺点分析

| 类型     | 说明                                |
| ------ | --------------------------------- |
| **优点** | 利用 PostgreSQL 数据库的计算能力进行过滤，减少网络传输 |
| **缺点** | 无法区分多级告警                          |

### 恢复逻辑

* **数据消失即恢复**：当 SQL 查询结果为空时，判定恢复
* **恢复查询**：支持配置额外的查询语句用于辅助判断恢复状态

## 3. 数据缺失模式

此模式用于监控"预期应该有数据，但实际没有数据"的场景。

### 配置方式

1. **查询语句**：编写一个预期应该持续返回数据的 SQL 查询。

* 示例：查询所有探针的心跳上报。
  ```sql theme={null}
  SELECT probe_id, max(check_time) as last_seen
  FROM probe_heartbeat
  WHERE check_time > NOW() - INTERVAL '5 minutes'
  GROUP BY probe_id
  ```

2. **判定规则**：如果某个 `probe_id` 在之前的周期中出现过，但在当前及连续 N 个周期中查不到数据，则触发"数据缺失"告警。

## 4. 最佳实践

<AccordionGroup>
  <Accordion title="索引优化">
    务必在 `WHERE` 子句中包含时间范围过滤，并确保时间字段上有索引，否则可能导致全表扫描。

    推荐写法：`log_time > NOW() - INTERVAL '5 minutes'`
  </Accordion>

  <Accordion title="字段大小写">
    Monitors 引擎会将 PostgreSQL 返回的列名统一转为小写。在填写"标签字段"和"值字段"时，请始终使用小写字母。
  </Accordion>
</AccordionGroup>