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

# Flashduty Monitors 入门指南

> Monitors 快速开始指南，帮助您快速上手告警功能

要体验 Monitors 功能，核心包含三个步骤：

<Steps>
  <Step title="安装 monitedge">
    部署告警引擎到私有网络
  </Step>

  <Step title="创建数据源">
    配置要监控的数据来源
  </Step>

  <Step title="创建告警规则">
    定义告警条件和通知方式
  </Step>
</Steps>

## 安装 monitedge

`monitedge` 需要部署在用户私有网络内，负责从 SaaS 同步告警规则，周期性查询数据源并进行阈值判定，产生告警事件并推送给 SaaS 端。

**菜单入口**：告警引擎 → 引擎安装/升级

支持 Linux、Docker、Kubernetes 三种安装方式。

<Warning>
  **引擎集群名字**非常重要：相同名字的 `monitedge` 会组成一个集群，共同分片处理告警规则，避免单点故障。

  * 单套集群：保持默认的 `default` 即可
  * 多套集群（如美东机房、华南机房各一套）：请为每套集群指定不同的名字
</Warning>

![告警引擎安装](https://docs-cdn.flashcat.cloud/imges/mon/64af7649b50f8ba705da9067afffc36a.png)

### 告警引擎状态

`monitedge` 安装完成后，会自动连接 SaaS 端并周期性同步告警规则。您可以在告警引擎状态页面查看当前状态信息。

长期没有心跳的引擎实例会展示删除按钮，可点击移除以避免引擎失联告警。

### 引擎失联告警

`monitedge` 挂掉影响很大，因此提供引擎失联告警。

<Note>
  多个实例组成的引擎集群，只要集群中有一个实例存活，就不会触发引擎失联告警。
</Note>

## 创建数据源

**菜单入口**：数据源 → 新建

![创建数据源](https://docs-cdn.flashcat.cloud/imges/mon/3eee06165afe05405db6187205f7025c.png)

| 配置项 | 说明 |
| - | - |
| **关联告警引擎** | 指定该数据源由哪个告警引擎集群进行数据查询和告警判定，通常选择同机房的集群 |
| **数据源连接地址** | 给 `monitedge` 连接的地址，必须是 `monitedge` 能访问到的内网地址 |

## 创建告警规则

**菜单入口**：告警规则

告警规则可能会很多，Monitors 提供树形分组结构进行分类管理。每个告警规则都要属于某个分组，您可以先创建分组，再在分组下创建告警规则。

创建 / 编辑告警规则的页面是一个单页表单，自上而下分为五个区块：**基础配置**、**数据源与查询**、**告警判定**、**检测频率 & 生效时间**、**事件配置**。

### 基础配置

![基础配置](https://docs-cdn.flashcat.cloud/imges/mon/3a2978a22d7a23dd862fdbd409adf663.png)

| 配置项 | 说明 |
| - | - |
| **所属分组** | 规则所在的分组路径（如“默认分组 / 数据库告警”）。如果分组已被删除或您无权访问，需要返回规则列表重新选择分组 |
| **规则名称** | 告警规则的名称，不支持引用变量（固定名称便于过滤、聚合操作）。同一分组内必须唯一；导入、编辑或移动规则时如与目标分组中已有规则重名，操作会失败 |
| **附加标签** | 类似 Prometheus 中的 `labels`，会附加到所有告警事件上，便于过滤、路由、抑制 |

### 数据源与查询

区块 2 由两段组成：**数据源** 决定规则生效到哪些数据源，**查询语句** 决定从数据源里查什么、怎么查。

#### 数据源

![数据源选择](https://docs-cdn.flashcat.cloud/imges/mon/9971af45b4bc19bfe807898bf1bf10a0.png)

先选择 **数据源类型**。这里只列出已配置过数据源的类型；如果还没有任何数据源，点击 **前往数据源管理页面**（在新标签页打开，不会丢失当前表单）先创建。

然后选择规则生效到哪些数据源，一个规则可以生效到多个数据源：

* **名称通配**：按名称匹配，新建规则时默认为 `*`（该类型下的所有数据源）。`*` 匹配任意字符串（如 `db-*`），`?` 匹配单个字符，`[0-9]`、`[a-z]` 匹配字符范围，`[!0-9]` 匹配不在范围内的字符。数据源改名会影响匹配。
* **精确匹配**：从下拉列表选择具体数据源，不受改名影响。

两种方式至少填一种，可以同时使用，规则生效到两者匹配结果的并集。腾讯云 CLS 例外：只能精确绑定一个数据源。

<Tip>
  需要不受数据源改名影响的稳定绑定时，建议使用精确匹配。详情参见[数据源管理](/zh/monitors/data-sources/data-sources)。
</Tip>

<Note>
  保存规则时，您需要对规则引用的每个数据源都有查询权限，包括名称通配在保存时匹配到的数据源（主体账号与 Admin 除外）。因此一条通配规则可能因为匹配到您无权查询的数据源而无法保存。只停用规则不受此限制。数据源授权见[数据源管理](/zh/monitors/data-sources/data-sources#数据源权限团队授权)。
</Note>

#### 查询语句

![查询语句](https://docs-cdn.flashcat.cloud/imges/mon/4e38b46952d6cbbfb97c2d28843dcdbe.png)

配置查询类型与查询语句。点击 **使用说明** 可以查看写法说明。表格型查询的值字段、标签字段与附加信息如何映射，详见[查询结果字段映射](/zh/monitors/alert-rules/query-result-fields)。

#### AI 查询助手

选择数据源类型后，点击查询输入框右上角的 **AI 帮我写**，查询助手会结合当前规则的数据源、查询类型、阈值和其他查询，帮您生成或改写查询语句。

* 生成的语句和相关参数（如 SLS 的项目 / 日志库、腾讯云 CLS 的地域 / 日志主题）会自动填入表单，也可以点击结果卡片上的 **回填** 重新填入。
* 主查询、恢复查询、关联查询、查询预览，以及实体树中的 PromQL 都可以使用查询助手。
* 回填不会自动保存规则，保存前请确认语句与阈值匹配。

### 告警判定

告警判定提供三种检测方式，每种是一个页签，在页签内的卡片标题右侧启用。已启用的页签标题后会显示对勾。

\|------|----------|
\| **阈值判定** | 按级别填写阈值表达式，满足条件并达到触发次数后，产生对应级别的告警。高级别触发后不再判断低级别；Critical、Warning、Info 至少填写一项 |
\| **数据缺失** | “之前查到过数据，现在查不到了”或“所有查询均无返回数据”时告警，两个条件可以分别启用 |
\| **数据存在** | 查询到数据即视为满足条件，达到触发次数后按设定级别产生告警 |

每个页签分为“**告警触发**”和“**告警恢复**”两张卡片（**数据缺失**页签合并为一张“**触发与恢复条件**”）。主要字段：

| 字段 | 说明 |
| - | - |
| **触发方式** | `连续命中` 或 `累计命中`，两者的区别见下一节 |
| **告警级别** | `Critical`、`Warning`、`Info` 三选一，默认 `Critical`。阈值判定的级别由命中的表达式决定 |
| **恢复方式** | 见下文[告警恢复](#告警恢复) |
| **恢复条件** | 连续 N 次正常才恢复，默认 1 |

#### 触发方式：连续命中与累计命中

| 触发方式 | 语义 | 触发条件句子 |
| - | - | - |
| **连续命中**（默认） | 连续满足条件达到设定次数才告警 | 连续 N 次检测都满足条件才告警，N 即**命中次数**，默认 3 |
| **累计命中** | 最近几次检测中，满足条件的次数达标即可，无需连续 | 最近 M 次检测中，有 N 次满足条件就告警，M 即**检测次数**，切到累计命中时默认取 `max(命中次数, 5)` |

* 累计命中下，命中次数不能大于检测次数，两者都不能超过 10000

<Note>
  **累计命中需要告警引擎 `v0.69.0` 及以上。** 更早版本的引擎会按连续命中执行，告警可能延迟或漏报。
</Note>

#### 告警恢复

恢复方式的可选项由检测方式决定：

| 页签 | 恢复方式 |
| - | - |
| **阈值判定** | `未触发任一阈值就算恢复`（默认）、`结果满足条件才算恢复`（需要额外填写恢复表达式）、`表达式查到数据就算恢复`（需要填写恢复查询语句）、`告警保持活动，直到用户手工关闭` |
| **数据存在** | `查询检测查不到数据即恢复`（默认）、`恢复检测查到数据才恢复`（需要填写恢复查询语句）、`告警保持活动，直到用户手工关闭` |
| **数据缺失** | `所有查询均无返回数据时告警` 的恢复方式固定为“任一查询重新查到数据后自动恢复”；`之前查到过数据，现在查不到了，就告警` 可选择 `数据重新出现后自动结束`（默认）、`数据恢复或超时后自动结束`（需要填写**自动关闭时间**，单位为秒、最小 1）、`仅允许手工关闭` |

### 检测频率与生效时间

![检测频率 & 生效时间](https://docs-cdn.flashcat.cloud/imges/mon/0980d71a653985a1706243fc6795685e.png)

| 配置项 | 说明 |
| - | - |
| **检测频率** | 通常是周期性检测，也支持 `cron` 表达式（精确到秒）和 `@every` 快捷写法。默认 `@every 15s`，可以从下拉选项中选择，也可以直接输入 |
| **查询时间偏移** | 设置查询时间偏移量（秒），用于处理数据源存在采集延迟的场景。例如设置为 60，则查询窗口整体向前偏移 60 秒，确保数据已完成写入后再查询。仅适用于 Prometheus、Loki、VictoriaLogs、SLS、Tencent CLS 数据源 |
| **规则时区** | 告警规则的执行时区，决定 `cron` 调度时间和**生效时间**窗口的解释方式。默认 `Asia/Shanghai`，必须填写有效的 IANA 时区名（如 `Asia/Shanghai`、`UTC`、`Europe/London`、`America/New_York`） |
| **生效时间** | 告警规则的生效时间段，非生效时间段内不会触发告警；时间窗口按上面配置的**规则时区**计算。可以添加多个时间窗，每个时间窗由星期（多选）和开始 / 结束时间（`HH:mm`）组成。默认全天生效 |

<Warning>
  **时区填写规则**：

  * **规则时区**只接受 IANA 标准时区名。`Local`、`UTC+8`、`CST`、`GMT+8` 等简写或偏移量写法会被拒绝
  * **`cron` 表达式不能以 `CRON_TZ=` 或 `TZ=` 开头**。如果您从开源 cron 系统迁移过来并习惯把时区内嵌在 cron 字符串里（例如 `CRON_TZ=Asia/Shanghai 0 0 * * *`），请去掉前缀，把时区填到**规则时区**字段中

  **cron 表达式格式规则**：

  * `cron` 表达式必须是 **6 段秒级表达式**，顺序为秒、分、时、日、月、周。5 段写法（例如 `*/5 * * * *`）会被拒绝，需要补充秒字段（例如 `0 */5 * * * *`）
  * 支持 `@every` 快捷写法，例如 `@every 30s`，表示每 30 秒检测一次。时长必须是**不小于 1 秒的整数秒**，支持 `@every 1m30s` 这类组合时长；`@every 0s`、`@every 1500ms` 等亚秒或不满足整秒的写法会被拒绝
  * 编辑旧规则时，不符合上述格式的检测频率需要先修正才能保存
</Warning>

<Note>
  重复通知的最大次数和重复间隔，以及各检测方式的命中次数和恢复次数都必须不小于 1，否则规则不会执行。
</Note>

### 事件配置

事件配置包括自定义字段与关联查询（默认折叠）、备注描述和重复发送配置。

| 配置项 | 说明 |
| - | - |
| **自定义字段** | 类似 Prometheus 中的 `annotations`，可附加仪表盘 URL、SOP URL 等 |
| **关联查询** | 不作为阈值判定依据，但可放到备注中作为变量引用（如附加日志样例） |
| **备注描述** | 非结构化文本字段，支持引用变量，便于值班人员快速定位问题 |
| **协作空间** | 指定 Flashduty On-call 中的协作空间，不指定则根据集成路由规则投递 |
| **重复通知** | 告警未恢复时持续通知，可配置间隔和最大次数（默认 10000 次） |

<Note>
  最大通知次数并不代表终端用户收到的消息提醒次数。因为 Monitors 产生的告警事件会投递到 On-call，可能会被聚合降噪，最终发送次数取决于 On-call 配置。
</Note>

## 查看效果

完成配置后，如果告警条件触发，告警规则前的状态会变成 `Triggered`。

![告警规则列表页面](https://docs-cdn.flashcat.cloud/imges/mon/6f1fad7d65b5aee6b89bf0f0a564a1be.png)

<Tip>
  告警规则列表的搜索框支持按规则名称、规则 ID 或标签进行搜索过滤，方便快速定位规则。也可以通过 URL 参数 `?rule_id=<ID>` 直接跳转到指定规则。
</Tip>

规则状态由 Flashmonit 当前活跃告警决定：`Triggered` 表示该规则至少有一个活跃告警，`Healthy` 表示当前没有活跃告警。

点击状态徽章（`Triggered` 或 `Healthy`），页面会切换到“活跃告警”标签页，并按该规则自动过滤（URL 参数 `active_alert_rule_id`），方便直接查看该规则当前产生的活跃告警。历史告警事件可到 On-call 中查看。详见[活跃告警](/zh/monitors/alert-rules/active-alerts)。

## 规则运行详情

告警规则列表的每一行都提供运行时自省能力。点击行操作菜单（行尾 `⋮`）中的**运行详情**，打开规则运行详情抽屉，帮助您判断规则的执行健康度并快速排障。

抽屉顶部可以选择要查看的**数据源**（规则可能绑定多个数据源）；这个选择器按查看者对各数据源的查询（`readonly`）权限过滤，没有查询权限的数据源会被静默丢弃，受限查看者看到的数据源可能少于规则实际绑定的数量。下方分为两个标签页：

### 当前状态

* **状态徽章**：`运行正常`（normal）、`执行异常`（abnormal）、`等待首次执行`（waiting）、`状态已过期`（stale）。当中心配置已保存但 Edge 尚未上报新版本时，额外显示 `配置待生效` 标识；规则被禁用时显示 `规则已停用` 标识
* **最近执行**：执行时间、执行耗时、执行结果、查询结果数、最近成功、连续失败、运行阶段、状态更新时间
* **告警实例**：活跃实例总数，并按检测模式拆分为 Threshold（阈值判定）、AnyData（数据存在）、NoData（数据缺失），以及最近产生的事件类型（告警触发、重复通知、告警恢复、告警关闭）
* **Edge 与配置**：负责该规则的 Edge 集群、Edge 实例、版本、在线状态和最近心跳

当状态为 `等待首次执行` 或 `状态已过期` 时页面会给出原因提示；负责该规则的 Edge 不在线，或执行出现错误时，会以醒目横幅展示错误类型和错误摘要。

### 执行历史

按时间范围查询该规则的历史执行记录（支持最近 15 分钟、1 小时、4 小时、1 天，最长 24 小时）。每条记录带执行摘要徽章：`执行失败`、`产生事件`、`告警恢复`、`定期采样`；展开后可查看日志入库时间、Edge 实例与集群、运行阶段、连续失败次数、各检测模式活跃实例数、产生的事件以及错误摘要。

<Note>
  执行历史只记录关键执行摘要（异常、事件、恢复和定期采样），不保证每轮评估都生成记录；匹配记录超过 200 条时仅展示最近 200 条，请缩小时间范围。
</Note>

## 批量操作

告警规则列表支持多选后进行批量操作，提升规则管理效率。

### 批量启用/禁用/删除

在列表中勾选多条规则后，可以一键批量启用、批量禁用或批量删除。

### 批量编辑字段

勾选多条规则后点击**批量更新**，可以统一修改以下 10 个字段：

| 可批量编辑的字段 | 说明 |
| - | - |
| **附加标签** | 统一设置 labels，支持增量修改与全量替换两种方式 |
| **数据源** | 统一切换数据源 |
| **检测频率** | 统一调整检测周期 |
| **规则时区** | 统一切换告警规则的 IANA 时区 |
| **生效时间** | 统一配置生效时间段 |
| **查询时间偏移** | 统一设置查询时间偏移。仅当所有选中规则的数据源都支持（Prometheus、Loki、VictoriaLogs、SLS、Tencent CLS）时可用 |
| **自定义字段** | 统一配置 annotations，支持增量修改与全量替换两种方式 |
| **协作空间** | 统一指定告警投递的协作空间 |
| **重复发送配置** | 统一设置重复通知间隔和次数 |
| **调试日志** | 统一开启或关闭调试日志 |

操作方式：在批量更新面板中先选择要修改的字段，然后设置新值，点击确定即可批量应用到所有选中规则。

批量更新**附加标签**和**自定义字段**时，使用专用的元数据编辑器，支持两种更新方式：

| 更新方式 | 说明 |
| - | - |
| **增量修改**（默认） | 逐条添加“设置”或“删除”操作，指定键和值。编辑时会根据所选规则的现有内容自动补全，并预览每个操作会影响多少条规则。自定义字段的键不能以 `$` 开头，同一批操作中的键不能重复 |
| **全量替换** | 用下方填写的内容完全替换每条规则的该字段，会删除每条规则中未在下方填写的其他内容 |

<Warning>
  修改附加标签可能影响告警路由、聚合或降噪，请谨慎操作。
</Warning>

部分规则更新失败时，会提示失败条数和第一个失败原因，其余规则照常更新。

### 批量移动

勾选多条规则后，可以将它们批量移动到其他文件夹中。

## 导入告警规则

**菜单入口**：告警规则 → 导入

导入采用文件上传方式，一次上传一个规则文件（`.yaml`、`.yml` 或 `.json`，不超过 1 MB）。系统会自动识别文件格式，并在导入前展示预检结果，支持以下四种来源：

| 来源格式 | 说明 |
| - | - |
| **Flashduty Rules YAML** | Flashduty 原生规则 bundle，与导出功能产出的格式一致，适合跨租户或跨环境迁移规则 |
| **Flashduty 规则 JSON** | 历史版本的 Flashduty 规则 JSON 格式 |
| **Prometheus Rules YAML** | 标准的 Prometheus 告警规则 YAML，要求以 `groups` 为根节点，YAML 缩进必须正确 |
| **Nightingale 规则 JSON** | Nightingale v6-v9 的规则 JSON |

### 导入配置

文件上传后可以配置：

* **同名规则处理方式**：`跳过同名规则`（默认，目标分组中已有同名规则时不导入）或 `创建副本`（为同名规则创建副本）
* **导入后启用规则**：仅对 Flashduty Rules YAML 来源显示。关闭时，导入的 Flashduty 规则保持停用
* **协作空间**：指定告警事件投递的协作空间

### 预检结果

系统解析文件后展示预检结果表格，逐条列出规则的导入名称、状态（`可导入` / `跳过` / `无效`）和说明。勾选要导入的规则（默认选中所有可导入的规则）后提交。

<Note>
  Nightingale 规则导入后统一保持停用，需检查数据源匹配和转换警告后再手动启用。常见的转换说明包括：Doris 数据源映射为 MySQL、仅保留最高级别告警条件、级别抑制/查询关联/通知目标等配置未保留、恢复语义按 Flashduty 规则能力近似转换、`Local` 时区转换为 `Asia/Shanghai`、全天生效时间转换为 `00:00-23:59`、缺少评估间隔时持续时间按 15 秒间隔换算等。
</Note>

### 导入结果

提交后系统展示导入结果：成功、跳过和无效的条数。如果一条都没有导入成功，可以在弹窗中查看原因后重新选择。

## 导出告警规则

在列表中勾选需要导出的规则，点击**导出**按钮。系统以 YAML 格式（Flashduty Rules YAML bundle）展示所选规则的完整配置，您可以：

* **下载**：将 YAML 保存为 `alert-rules.yaml` 文件
* **复制**：将 YAML 内容复制到剪贴板

导出的 YAML 可用于备份，也可以通过文件上传方式导入到其他环境，详见[导入告警规则](#导入告警规则)。

## 规则变更记录

每条告警规则都有完整的变更审计记录。您可以在规则详情中查看**变更记录**，了解规则的历史修改情况。

### 查看变更记录

变更记录列表展示每次操作的以下信息：

| 列信息 | 说明 |
| - | - |
| **操作时间** | 变更发生的时间 |
| **操作类型** | 如创建、更新等 |
| **操作人** | 执行变更的用户 |

### 版本对比

在变更记录列表中勾选两条记录，点击**对比**按钮，系统会以 JSON diff 的方式展示两个版本之间的差异，帮助您快速了解具体修改了哪些配置项。


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