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

# SLS

> 配置阿里云日志服务 (SLS) 数据源的告警规则

Monitors 通过 SLS 的 SQL 查询接口（GetLogsV3）获取数据，并根据查询结果触发告警。

## 核心概念

| 配置项      | 说明                                           |
| -------- | -------------------------------------------- |
| **查询语言** | 使用 SLS SQL 语法                                |
| **必填参数** | 每条查询必须指定 `sls.project` 和 `sls.logstore`      |
| **时间范围** | 由 API 参数控制，无需在 SQL 中写 `WHERE __time__ > ...` |
| **字段处理** | `__source__` 和 `__time__` 字段默认被忽略            |

## 1. 阈值判定模式

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

### 配置方式

1. **查询语句**：编写 SLS SQL 聚合查询。

* 示例：统计最近 15 分钟内，各主机的错误日志数量。
  ```sql theme={null}
  * | SELECT host, count(*) as error_cnt WHERE level = 'ERROR' GROUP BY host
  ```

2. **查询参数**：

* `sls.project`：（必填）项目名称。
* `sls.logstore`：（必填）日志库名称。
* `sls.timespan.value`：（选填）时间跨度数值，默认为 15。
* `sls.timespan.unit`：（选填）时间跨度单位，支持 `s`（秒）、`m`（分）、`h`（时）、`d`（天）。默认为 `m`。

3. **字段映射**：

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

4. **阈值条件**：

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

### 工作原理

引擎调用 SLS API，指定时间范围（如最近 15 分钟），执行 SQL 查询。获取结果后，根据"标签字段"分组，提取"值字段"与阈值比对。

### 恢复逻辑

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

## 2. 数据存在模式

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

### 配置方式

1. **查询语句**：使用 `HAVING` 子句过滤异常数据。

* 示例：查询错误数超过 50 的主机。
  ```sql theme={null}
  * | SELECT host, count(*) as error_cnt WHERE level = 'ERROR' GROUP BY host HAVING error_cnt > 50
  ```

2. **查询参数**：同上，需配置 `sls.project` 和 `sls.logstore`。
3. **判定规则**：只要查询返回了数据，即触发告警。

### 优缺点分析

| 类型     | 说明                     |
| ------ | ---------------------- |
| **优点** | 利用 SLS 服务端的计算能力，减少数据传输 |
| **缺点** | 无法区分多级告警               |

### 恢复逻辑

* **数据消失即恢复**：当查询结果为空时，判定恢复
* **恢复查询**：支持配置额外的查询语句

## 3. 数据缺失模式

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

### 配置方式

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

* 示例：查询所有主机的日志上报心跳。
  ```sql theme={null}
  * | SELECT host, max(__time__) as last_seen GROUP BY host
  ```

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

## 4. 高级配置

<AccordionGroup>
  <Accordion title="Power SQL">
    如果需要使用 SLS 的增强 SQL 语法，在查询参数中添加：`sls.powersql: true`
  </Accordion>

  <Accordion title="时间范围控制">
    默认查询最近 15 分钟的数据。可通过参数调整：

    | 参数                   | 说明                               |
    | -------------------- | -------------------------------- |
    | `sls.timespan.value` | 时间跨度数值，如 `60`                    |
    | `sls.timespan.unit`  | 时间单位：`s`（秒）、`m`（分）、`h`（时）、`d`（天） |

    <Warning>
      不要在 SQL 中使用 `__time__` 进行过滤，引擎会自动根据参数设置时间范围。
    </Warning>
  </Accordion>

  <Accordion title="调试参数">
    仅用于调试，不要配置在生产规则中：

    | 参数         | 说明       |
    | ---------- | -------- |
    | `sls.from` | 开始时间戳（秒） |
    | `sls.to`   | 结束时间戳（秒） |
  </Accordion>
</AccordionGroup>