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

# ElasticSearch

> 配置 ElasticSearch 数据源的告警规则，支持 SQL 聚合查询

Monitors 通过 ElasticSearch SQL 功能实现对日志和指标数据的监控，支持灵活的聚合查询与告警判定。

## 核心概念

<Warning>
  由于依赖 SQL 特性，仅支持 **ElasticSearch 6.3** 及以上版本。
</Warning>

| 配置项      | 说明                      |
| -------- | ----------------------- |
| **查询语言** | 目前仅支持 SQL 语法            |
| **字段处理** | 所有字段名自动转换为小写，配置时请使用小写字母 |

## 1. 阈值判定模式 (Threshold)

此模式适用于需要对聚合后的数值进行阈值比对的场景，例如监控"最近 5 分钟错误日志数量"。

### 配置方式

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

* 示例：统计最近 5 分钟内，各服务的错误日志数量。
  ```sql theme={null}
  SELECT service_name, count(*) AS error_cnt 
  FROM "app-logs-*" 
  WHERE "@timestamp" > now() - INTERVAL 5 MINUTES AND log_level = 'ERROR'
  GROUP BY service_name
  ```

2. **字段映射**：

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

3. **阈值条件**：

* 使用 `$A.字段名` 引用数值。
* 示例：`Critical: $A.error_cnt > 50`，`Warning: $A.error_cnt > 10`。
* 简写：如果只配置了一个值字段，可以直接使用 `$A`，如 `$A > 50`。

### 工作原理

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

<Warning>
  标签字段组合唯一标识一个告警对象，查询结果中不能有多行数据具有相同的标签字段值组合。
</Warning>

### 恢复逻辑

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

<Accordion title="恢复查询示例">
  告警 SQL 查出了 `network_host="a", interface="b"` 的网卡挂了，恢复 SQL 可以写：

  ```sql theme={null}
  SELECT network_host, interface, status FROM "network-status-*" 
  WHERE "@timestamp" > now() - INTERVAL 5 MINUTES 
    AND network_host = '${network_host}' 
    AND interface = '${interface}' 
    AND status = 'UP'
  ```

  引擎会将变量替换为实际值后执行查询，如果查到数据，则判定恢复。
</Accordion>

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

此模式适用于将过滤逻辑直接写在 SQL 中的场景，或者只需要关注"是否有数据返回"的情况。

### 配置方式

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

* 示例：直接查询错误数超过 50 的服务。
  ```sql theme={null}
  SELECT service_name, count(*) AS error_cnt 
  FROM "app-logs-*" 
  WHERE "@timestamp" > now() - INTERVAL 5 MINUTES AND log_level = 'ERROR'
  GROUP BY service_name
  HAVING count(*) > 50
  ```

2. **字段映射**：

* 在此模式下，标签字段和值字段为 **非必填项**。如果都留空，引擎会将查询结果中的所有字段都作为标签字段，可以在规则备注中引用。

### 恢复逻辑

* **数据消失即恢复**：当 SQL 查询结果为空（即不再满足 HAVING 条件）时，引擎判定故障恢复。这是最常用的恢复方式。
* **恢复查询**：
  * **场景**：有时"查不到数据"并不代表恢复（可能是日志采集挂了），或者需要更严格的恢复条件（如连续 N 分钟无错误）。
  * **配置**：编写一条独立的 SQL 语句用于恢复判定。只要该查询能查到数据，就认为故障已恢复。
  * **变量支持**：支持在恢复 SQL 中使用 `${label_name}` 引用告警事件的标签值，实现精准恢复检测。

### 优缺点分析

| 类型     | 说明                                         |
| ------ | ------------------------------------------ |
| **优点** | 利用 ES 集群的计算能力进行过滤，减少网络传输，性能更好              |
| **缺点** | 无法区分多级告警（如 Info/Warning），SQL 只能返回满足特定条件的数据 |

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

此模式用于监控"预期应该有数据，但实际没有数据"的场景，常用于监控日志采集链路中断或周期性任务未执行。

### 配置方式

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

* 示例：查询所有主机的日志上报心跳。
  ```sql theme={null}
  SELECT host_name 
  FROM "heartbeat-logs-*" 
  WHERE "@timestamp" > now() - INTERVAL 5 MINUTES 
  GROUP BY host_name
  ```

2. **判定规则**：

* 引擎会周期性执行该 SQL。
* 如果某个 `host_name` 在之前的周期中出现过，但在当前周期（以及连续的 N 个周期）中不再出现在查询结果中，则触发"数据缺失"告警。
* 注意：这与 Data Exists 模式相反。Data Exists 是"查到数据就告警"，No Data 是"查不到数据就告警"。

### 恢复逻辑

| 策略          | 说明                                |
| ----------- | --------------------------------- |
| **数据出现即恢复** | 一旦该 `host_name` 重新出现在查询结果中，告警自动恢复 |
| **自动恢复时间**  | 可配置超时时间（如 24 小时），超时后自动关闭告警        |

## 4. 案例说明

日志告警经常遇到如下需求：统计最近 5 分钟的 ERROR 日志数量，如果超过阈值则告警，同时在告警消息中展示最近一条 ERROR 日志作为样例。配置方案如下：

* **主告警条件**：使用 Threshold 模式，SQL 语句统计最近 5 分钟的 ERROR 日志数量，配置阈值条件。
* **关联查询**：配置一个关联查询，SQL 语句查询最近一条 ERROR 日志，使用 `${service_name}` 等变量限定具体服务。
* **规则备注描述**：在告警规则的备注描述中引用关联查询结果，使用 `$relates` 变量，把日志原文渲染出来。