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

# Tencent CLS

> 配置腾讯云日志服务 (CLS) 数据源的告警规则

Monitors 通过腾讯云日志服务 CLS 的检索与分析接口获取数据，并根据查询结果触发告警。每条查询通过「地域 + 日志主题」定位日志，查询模式支持原始日志检索（raw）与 SQL 分析（analysis）。

## 核心概念

| 配置项      | 说明                                                                                  |
| -------- | ----------------------------------------------------------------------------------- |
| **查询资源** | 每条查询必须指定 `tencent_cls.region`（地域）和 `tencent_cls.topic_id`（日志主题）；日志集只用于界面筛选，不参与保存与执行 |
| **查询模式** | `raw` 原始日志检索返回日志行；`analysis` SQL 分析返回聚合结果。后端按存储的参数值执行，不从表达式推断                       |
| **检索语法** | 原始日志检索使用 `tencent_cls.syntax` 指定的语法：`CQL` 或 `Lucene`                                |
| **时间范围** | 由参数控制，无需在查询语句中书写时间过滤条件                                                              |
| **执行标识** | 执行时只认日志主题 ID，主题名称仅用于展示                                                              |

## 查询参数

| 参数                           | 说明                                         | 默认值            |
| ---------------------------- | ------------------------------------------ | -------------- |
| `tencent_cls.region`         | （必填）地域 code，如 `ap-guangzhou`。切换地域会清空已选日志主题 | `ap-guangzhou` |
| `tencent_cls.topic_id`       | （必填）日志主题 ID，可按名称搜索或直接粘贴 ID                 | -              |
| `tencent_cls.query_mode`     | 查询模式：`raw` 原始日志检索 / `analysis` SQL 分析      | `raw`          |
| `tencent_cls.syntax`         | 检索语法：`CQL` / `Lucene`，用于原始日志检索             | `cql`          |
| `tencent_cls.timespan.value` | 时间跨度数值                                     | `15`           |
| `tencent_cls.timespan.unit`  | 时间跨度单位：`s`（秒）、`m`（分）、`h`（时）、`d`（天）         | `m`            |
| `tencent_cls.limit`          | 最大返回条数，仅 raw 模式有效，取值范围 1\~100              | `1`            |

地域下拉提供常用地域建议列表（如 ap-guangzhou、ap-shanghai、ap-beijing 等），仅为建议而非白名单；也可以输入任意符合 `[a-z0-9-]` 形状的地域 code，能否使用由腾讯云判定。

## 查询模式

### 原始日志检索（raw）

使用 CQL 或 Lucene 语法检索日志，返回匹配的日志行。每返回一条日志，就可能生成一条告警。

* 时间窗口最长 **6 小时**。
* 用 `tencent_cls.limit` 控制单次最多返回的日志条数，可填 1\~100。新建规则默认写入 `1`；参数缺失时，Edge 也按 `1` 条执行。
* 查询编辑器不提供关键字补全：raw 模式写的是 CQL/Lucene，SQL 关键字补全只会误导。

### SQL 分析（analysis）

对日志进行 SQL 聚合，返回聚合结果，适合阈值判定与数据存在判定。

* 时间窗口最长 **24 小时**。
* 不允许携带 `tencent_cls.limit`，携带会被后端拒绝。

## 时间范围

默认查询最近 15 分钟（`tencent_cls.timespan.value=15`、`tencent_cls.timespan.unit=m`）的数据。时间窗口上限随查询模式变化：原始日志检索最长 6 小时，SQL 分析最长 24 小时；超出上限时表单直接报错（「时间窗口最长 N 小时」），无需等到保存。

## 数据源与主题要求

### 单数据源绑定

Tencent CLS 规则只能**精确绑定一个数据源**，且不支持名称通配。创建规则时数据源选择为单选，名称通配输入被隐藏；配置非法时保存会提示「该数据源类型只能绑定一个数据源」或「该数据源类型不支持名称通配，请清空后重新选择」。

### 主题索引要求

日志主题必须开启索引，检索和 SQL 分析才能返回结果。主题列表中未开启索引的主题带有「未开启索引」标记；选中未开启索引的主题后，编辑器会提示「该日志主题未开启索引，检索和 SQL 分析都不会有结果。请先在腾讯云控制台配置索引。」——这类查询会持续返回空结果。

### 主题 ID 执行

主题选择器支持按名称搜索或直接粘贴主题 ID。保存进规则的只有主题 ID，执行时也只认主题 ID；日志集筛选仅用于界面过滤，不会被保存。编辑已有规则时，若主题已被删除，界面会提示「主题不存在或已被删除」，需要重新选择主题。

## 无数据检测

Tencent CLS 不支持按曲线（per-series）的无数据检测：

* 仅支持「**所有查询均无返回数据时告警**」。
* 不提供「之前查到过数据，现在查不到了，再告警；重新查到数据就恢复」选项——该配置会被后端拒绝，因此这张检测卡在界面上不出现。
* 告警结束方式只有「数据重新出现后自动结束」与「仅允许手工关闭」，不提供「数据恢复或超时后自动结束」。

## 恢复查询与关联查询

* **恢复查询**：阈值判定模式选择「表达式查到数据就算恢复」、数据存在模式选择「恢复检测查到数据才恢复」时，恢复查询同样需要配置地域、日志主题、查询模式等参数，判定逻辑与主查询一致。
* **关联查询**：关联查询支持同样的 Tencent CLS 参数，可在告警中附带相关信息。