> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flashduty.com/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. **查询语句**：编写 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. **字段映射**：
   * **值字段**：选择 `error_cnt`，用于阈值判定。
   * **标签字段**：选择 `host`，用于标识告警对象。明确选择标签字段后，其他非值字段会作为附加信息随告警携带。
   * 详细规则请参见[查询结果字段映射](/zh/monitors/alert-rules/query-result-fields)。
4. **阈值条件**：
   * 使用 `$A.field_name` 引用数值。
   * 示例：`Critical: $A.error_cnt > 50`，`Warning: $A.error_cnt > 10`。

### 工作原理

Monitors 按配置的时间范围执行 SLS 查询，按标签字段区分告警对象，并使用值字段进行阈值判定。标签字段留空时，除值字段外的返回字段会作为标签。

### 恢复逻辑

| 策略 | 说明 |
| - | - |
| **自动恢复** | 当数值不再满足任何告警阈值时，自动恢复 |
| **特定恢复条件** | 配置恢复表达式（如 `$A.error_cnt < 5`） |
| **恢复查询** | 独立 SQL 用于恢复判定，支持 `${label_name}` 变量；亦支持 Go 模板 `{{ $labels.<标签名> }}`（需 monit-edge `v0.75.4` 及以上） |
| **手工关闭** | 告警保持活动，直到用户手工关闭 |

## 数据存在模式

此模式适用于将过滤逻辑直接写在 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 服务端的计算能力，减少数据传输 |
| **缺点** | 无法区分多级告警 |

### 恢复逻辑

* **数据消失即恢复**：当查询结果为空时，判定恢复
* **恢复查询**：支持配置额外的查询语句
* **手工关闭**：告警保持活动，直到用户手工关闭

## 数据缺失模式

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

SLS 不支持按曲线（per-series）的无数据检测，只能使用“**所有查询均无返回数据时告警**”判定，不支持“之前查到过数据，现在查不到了，就告警”。

### 配置方式

1. **查询语句**：编写一个预期应该持续返回数据的查询。
   * 示例：查询所有主机的日志上报心跳。
     ```sql theme={null}
     * | SELECT host, max(__time__) as last_seen GROUP BY host
     ```
2. **判定规则**：所有查询在连续 N 次检测中都返回空结果时，触发"数据缺失"告警。N 由该页签共享的“触发条件”决定。

### 存量已启用按曲线检测的规则

如果已有的 SLS 规则开启了按曲线的无数据检测，打开编辑页时该判定会被自动关闭，保存后生效；不打开编辑页，规则不会变化。

* 规则还有其他已启用的判定（阈值判定、数据存在）时，可以直接保存。
* 这是规则唯一的判定时，需要先启用至少一项判定才能保存。

建议改用“所有查询均无返回数据时告警”，确认至少启用了一项判定后再保存。

### 恢复逻辑

“所有查询均无返回数据时告警”的**恢复方式**不可配置，引擎固定为**任一查询重新查到数据后自动恢复**，界面上以只读文本展示：

| 恢复方式 | 说明 |
| - | - |
| `任一查询重新查到数据后自动恢复` | 固定值，不是可选项，界面上没有下拉框 |

原先的恢复方式下拉（`数据重新出现后自动结束` / `数据恢复或超时后自动结束` / `仅允许手工关闭`）只存在于按曲线的检测卡内部，SLS 下不可用。无数据页签里可配置的共享项只有触发与恢复条件（`触发方式`、`触发条件`、`恢复条件`）。

## 高级配置

<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.lines` 控制单次查询最多返回的日志条数。每返回一条日志，就可能生成一条告警。

    | 情形 | 行为 |
    | - | - |
    | **新建规则** | 默认写入 `1`，只取时间窗口内最新 1 条日志 |
    | **可填范围** | 1\~100 的整数 |
    | **留空** | 表示这条规则从未配置过该项，Edge 沿用旧的默认值 100 条 |
    | **越界或非整数** | 保存时显式报错（提示输入 1\~100 之间的整数），不会被静默修正 |

    该参数仅对原始日志检索有效；查询中包含 SQL 时，阿里云会忽略该配置。
  </Accordion>

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

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.