> ## 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 等），仅为建议而非白名单；也可以直接输入建议列表之外的地域 code。地域 code 需满足：小写字母开头，由小写字母、数字和连字符组成，且至少含一个连字符（如 `ap-nanjing`、`na-siliconvalley`），总长不超过 64 个字符。

<Warning>
  **不支持腾讯云金融专区**：以 `-fsi` 结尾的地域（如 `ap-shanghai-fsi`）会被直接拒绝，保存与预览都会失败。这不是腾讯云的限制，而是 Flashduty 侧的校验。
</Warning>

地域 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 分析都不会返回结果。主题列表会标出未开启索引的主题，请先在腾讯云控制台配置索引。

### 主题 ID 执行

可以按名称搜索主题，或直接粘贴主题 ID。规则只保存并使用主题 ID（日志集筛选只用于查找，不会保存）。如果主题已被删除，编辑规则时需要重新选择。

## 无数据检测

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

* 只能使用“**所有查询均无返回数据时告警**”判定，不支持“之前查到过数据，现在查不到了，就告警”（通过 API 也无法开启）。
* 恢复方式固定为**任一查询重新查到数据后自动恢复**，不可配置，也不支持仅手工关闭。

## 恢复查询与关联查询

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


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