> ## Documentation Index
> Fetch the complete documentation index at: https://test-8ad8522e-feat-ai-sre.mintlify.site/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. **字段映射**：

* **值字段**：选择 `error_cnt`，用于阈值判定。
* **标签字段**：选择 `service_name`，用于标识告警对象。明确选择标签字段后，其他非值字段会作为附加信息随告警携带。
* 详细规则请参见[查询结果字段映射](/zh/monitors/alert-rules/query-result-fields)。

3. **阈值条件**：

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

### 工作原理

Monitors 按标签字段区分告警对象，并使用值字段进行阈值判定。标签字段留空时，除值字段外的所有返回字段都会作为标签。

### 恢复逻辑

| 策略         | 说明                                  |
| ---------- | ----------------------------------- |
| **自动恢复**   | 当数值不再满足任何告警阈值时，自动生成恢复事件             |
| **特定恢复条件** | 配置恢复表达式（如 `$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 个周期中查不到数据，则触发"数据缺失"告警。

### 恢复逻辑

无数据告警支持配置**告警结束方式**，决定告警如何结束：

| 结束方式             | 说明                                                                |
| ---------------- | ----------------------------------------------------------------- |
| **数据重新出现后自动结束**  | 默认方式。数据重新出现后，告警自动结束                                               |
| **数据恢复或超时后自动结束** | 数据重新出现或达到自动关闭时间后，告警自动结束。自动关闭时间单位为秒，最小为 1；仅开启「之前查到过数据，现在查不到了」模式时可选 |
| **仅允许手工关闭**      | 告警保持活动，直到用户手工关闭                                                   |

## 4. 最佳实践

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

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

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