Merge branch 'main' of github.com:flashcatcloud/knowledge-base

Author: pijiang3

flashduty/zh/3. Monitors/2. 告警规则配置/9.victorialogs.md

@@ -0,0 +1,116 @@
+# VictoriaLogs 告警规则配置说明
+
+本文档介绍如何在 Monitors 告警引擎中配置 VictoriaLogs 数据源的告警规则。Monitors 通过 HTTP 查询 VictoriaLogs，支持查询日志原文、做统计分析，并基于结果进行阈值判定和数据存在/缺失判断。
+
+## 1. 前置说明
+
+### 1.1 原理说明
+
+Monitors 针对 VictoriaLogs 数据源的告警规则配置，分两个模式：
+
+- 查原文。调用的是其 `/select/logsql/query` 接口。该接口返回的数据可以看作是一个二维表格，在阈值**判定模式**下需要用“标签字段”和“值字段”进行映射。
+- 做统计。调用的是其 `/select/logsql/stats_query` 接口。该接口返回的数据遵从 Prometheus 协议格式，Monitors 自动识别哪些字段是标签，哪些字段是值，无需额外配置。
+- VictoriaLogs 数据源仍然支持三种告警模式，最推荐使用“数据存在模式”，最适合日志场景。
+
+### 1.2 查原文
+
+在“查原文”模式下，相关配置项说明：
+
+- 查询语句。举例：`error | fields _time, _stream, _msg | sort by (_time) desc`
+- 返回条目限制。该配置项用于限制查询结果的最大返回行数，避免单次查询返回过多数据影响性能。在 Monitors 中，最大可以设置为 100。
+- 时间范围。指定查询的时间窗口，例如“最近 5 分钟”。
+- 标签字段。指定查询结果中哪些字段作为告警对象的标签，用于区分不同的告警实体。可以配置多个标签字段。如果留空，Monitors 会将除了值字段之外的所有字段都视为标签字段。
+- 值字段。指定查询结果中哪个字段作为数值进行阈值判定。通常是一个数值类型的字段。在**阈值判定模式**下必填，在其他模式下选填。
+
+
+### 1.3 做统计
+
+在“做统计”模式下，需要使用 `stats` 关键字。相关配置项说明：
+
+- 查询语句。举例：`_time:1d | stats by (level) count(*) total`
+- 没有其他参数。注意查询语句中要包含 `_time` 过滤条件，例如 `_time:5m`，以限定查询的时间范围。否则就是查全部数据，可能导致性能问题。
+
+---
+
+## 2. 阈值判定模式 (Threshold)
+
+**查原文**和**做统计**两种查询模式都可以使用。下面分别举例说明。
+
+### 2.1 查原文示例
+
+查询语句示例：
+
+```
+level:ERROR | stats by (level) count(*) total
+```
+
+得到的结果类似：
+
+| level | total |
+|-------|-------|
+| ERROR | 150   |
+
+值字段配置为 `total`，标签字段配置为 `level`（或不配置，Monitors 会自动识别）。不同阈值不同级别的配置示例：
+
+- Warning：`$A.total >= 50` 或者简写为 `$A >= 50`（因为只有 total 这一个值字段）
+- Critical：`$A.total >= 100` 或者简写为 `$A >= 100`（因为只有 total 这一个值字段）
+
+### 2.2 做统计示例
+
+查询语句示例：
+
+`_time:1d and level:ERROR | stats by (level) count(*) total`
+
+得到的结果遵从 Prometheus 协议格式：
+
+```
+total{level="ERROR"} 150
+```
+
+不同阈值不同级别的配置示例：
+
+- Warning：`$A.total >= 50` 或者简写为 `$A >= 50`（因为只有 total 这一个指标字段）
+- Critical：`$A.total >= 100` 或者简写为 `$A >= 100`（因为只有 total 这一个指标字段）
+
+
+### 2.3 恢复逻辑
+
+与 Prometheus / ElasticSearch 阈值模式类似，VictoriaLogs 阈值模式支持：
+
+- **自动恢复**：当最新查询结果中，某个对象的数值不再满足任何告警阈值时，自动生成恢复事件。
+- **特定恢复条件**：可配置恢复表达式，例如 `$A.total < 10`，只有在错误数跌落到 10 以下时才认为恢复，减少抖动。
+- **恢复查询 (Recovery Query)**：可配置一条独立的 VictoriaLogs 查询语句用于恢复判定。
+  - 原理：告警触发后，Monitors 会周期性执行这条恢复查询语句。只要该查询能查到数据（即返回结果不为空），就认为故障已恢复。
+  - 变量支持：恢复查询语句中支持嵌入变量（格式为 `${label_name}`），这些变量会被自动替换为告警事件中对应的标签值，使得恢复查询能够针对具体的告警对象进行检测。
+
+---
+
+## 3. 数据存在模式 (Data Exists)
+
+此模式将过滤逻辑全部写在 VictoriaLogs 查询中，Monitors 只负责判断“是否有数据返回”。适用于“只要有满足条件的数据就告警”的场景。**这是最推荐的 VictoriaLogs 告警配置方式**（因为阈值判定模式需要数据一直都能查到，只是数值发生变化，这在日志场景不太适用，日志场景更适合采用数据存在模式）。
+
+查询语句示例（采用**做统计**查询模式）：
+
+`_time:15m and level:ERROR | stats by (level) count(*) total | filter total:>10`
+
+其中 `| filter total:>10` 用于筛选出 `total` 大于 10 的数据，只要有满足该条件的数据行返回，Monitors 就会触发告警。如果某个阶段没有任何数据行满足该条件，则认为该告警恢复。
+
+
+---
+
+## 4. 数据缺失模式 (No Data)
+
+数据缺失模式用于监控“原本应该持续产生的日志不再出现”的情况，常见于：
+
+- 应用实例不再产生日志（可能是进程退出）。
+- 日志采集链路异常（如 agent 宕机或输出阻塞）。
+
+### 4.1 配置示例
+
+查询语句（**做统计**模式）：
+
+```
+_time:15m and level:INFO | stats by (level) count(*) total
+```
+
+场景：某个服务应该一直都有 INFO 日志输出，如果在最近 15 分钟内没有任何 INFO 日志产生，就触发告警。