告警规则与告警记录
告警模块周期性扫描接口调用日志，按规则识别异常，并通过邮件等通道发送通知。规则按环境创建并关联接口，触发记录可追溯至具体接口、发布版本和 traceId。
入口
| 功能 | 入口 |
|---|---|
| 告警规则 | 告警通知 → 告警规则 |
| 告警记录 | 告警通知 → 告警记录 |
两个列表都支持按关键字和环境筛选，并按项目隔离。
告警规则
列表字段
| 列 | 说明 |
|---|---|
| 规则ID | 规则编号 |
| 规则名称 | 便于识别的名称 |
| 告警类型 | 超时、HTTP 状态码、业务状态码、错误率、连续失败 |
| 条件 | 规则条件，如 > 500ms、≠ 500 |
| 通知方式 | 邮件、短信、Webhook 标签 |
| 频率 | 每小时最大发送次数 |
| 状态 | 启用 / 禁用 |
| 修改时间 | 最近更新时间 |
操作包括编辑、关联 API、删除。规则已关联接口时不能删除，需先解除关联。
新建告警规则
规则表单分为基础信息、条件配置、统计配置、通知配置四部分。
基础信息
| 字段 | 说明 |
|---|---|
| 规则名称 | 必填 |
| 所属环境 | 创建后不可修改 |
| 告警类型 | 决定后续条件与统计字段 |
| 规则描述 | 可选，说明告警用途 |
告警类型与条件
| 类型 | 含义 | 条件字段 | 默认条件 |
|---|---|---|---|
timeout | 单次请求耗时超过阈值 | 阈值（毫秒）、比较符 | > |
http_status | HTTP 状态码匹配 | 状态码（支持逗号分隔多个）、比较符 | ≠ |
biz_code | 响应体指定字段与期望值比较 | 字段路径、期望值、比较符 | ≠ |
error_rate | 时间窗口内错误率超过阈值 | 阈值（百分比）、比较符 | > |
consecutive_fail | 从最新请求向前统计连续失败次数 | 阈值（次数）、比较符 | ≥ |
比较符支持 >、<、=、≠、≥、≤。业务状态码字段使用点分路径，例如 data.code，从 JSON 响应体中逐层提取。
统计配置
| 字段 | 适用类型 | 说明 |
|---|---|---|
| 时间窗口（秒） | 超时、错误率、连续失败 | 扫描日志的时间范围，默认 600 秒 |
| 最少请求数 | 错误率、连续失败 | 窗口内请求数不足时不触发，避免小样本误报 |
通知配置
| 字段 | 说明 |
|---|---|
| 通知方式 | 当前页面开放邮件；后端同时支持短信与 Webhook，但页面暂未开放配置入口 |
| 告警邮箱 | 多个邮箱用英文逗号分隔，逐个校验格式 |
| 告警频率 | 每小时最大发送次数，达到上限后本小时不再发送 |
| 状态 | 启用或禁用 |
短信与 Webhook
后端支持阿里云短信，以及企业微信、钉钉、飞书和自定义 Webhook，并在列表与记录中展示对应通知方式。当前编辑页面只开放邮件勾选项，如需短信或 Webhook，需要通过接口或后续版本页面配置。
关联接口
规则保存后，点击「关联 API」选择当前环境下的接口。未关联接口的规则不会产生任何告警。
关联关系按环境隔离：规则只扫描关联时所在环境的接口日志。
执行逻辑
告警扫描由 定时任务驱动，默认每 10 分钟执行一次，可通过 apigo.warn.scan-cron 调整；apigo.warn.enabled=false 可关闭告警扫描。多实例部署时通过 Redis 分布式锁保证同一时刻只有一个实例执行。
日志来源
默认从数据库的调用日志表读取；当 spring.elasticsearch.enabled=true 时改为从 Elasticsearch 读取。两条链路使用相同的接口、环境和时间窗口条件。
各类型评估方式
| 类型 | 评估方式 |
|---|---|
| 超时 | 遍历窗口内日志，找到响应耗时满足条件的记录；同一 API 只触发一次 |
| HTTP 状态码 | 匹配单个状态码或逗号分隔的多个状态码；同一 API 只触发一次 |
| 业务状态码 | 从响应体提取点分路径字段，与期望值比较；同一 API 只触发一次 |
| 错误率 | 按 API 分组统计失败数 ÷ 总数，达到阈值且满足最少请求数时触发 |
| 连续失败 | 按时间倒序从最新请求开始计数，遇到成功请求即停止 |
失败状态的判定标准是调用日志的请求状态为空或不等于 success。
去重与频率控制
| 机制 | 作用范围 | 规则 |
|---|---|---|
| 每小时频率 | 规则 | 达到配置次数后本小时不再发送 |
| 日志去重 | 单条日志 + 规则 | 同一日志 24 小时内不重复告警 |
| 活跃状态 | 窗口型规则 + API | 已告警的 API 在窗口期内不重复告警；指标恢复后清除状态 |
窗口型规则（错误率、连续失败）的活跃状态有效期取时间窗口与 300 秒中的较大值，避免窗口过短导致频繁重复通知。
通知发送
- 每个通知通道独立发送，只要有一个通道发送成功，本次告警即记为成功；
- 邮件按收件人逐个发送，单个收件人失败不影响其他收件人；
- 短信通过阿里云短信服务发送，需要配置 AccessKey、签名和模板；
- Webhook 支持企业微信、钉钉、飞书的 Markdown/文本格式，以及自定义 JSON；
- 每次发送都会写入告警记录，记录每个通道的发送结果。
告警记录
列表字段
| 列 | 说明 |
|---|---|
| 记录ID | 告警记录编号 |
| 告警类型 | 触发的规则类型 |
| 接口名称 | 触发告警的接口 |
| 环境 | 所属环境 |
| 条件 | 规则条件与阈值 |
| 触发值 | 实际触发值，如 820ms、12.50%、5次 |
| 通知方式 | 本次配置的通知渠道 |
| 发送状态 | 成功 / 失败 |
| 告警时间 | 记录创建时间 |
详情
点击「详情」可查看：
- 规则名称、类型、条件、触发值与阈值；
- 接口名称、路径、环境、发布版本；
traceId与请求时间；- 发送状态、发送明细；
- 告警摘要，说明触发原因。
告警记录只读，不提供删除或重发操作。
常见问题
| 现象 | 排查方向 |
|---|---|
| 规则不触发 | 是否启用、是否关联接口、关联环境是否正确 |
| 告警延迟 | 扫描默认 10 分钟一次，属于正常延迟；可调整 cron |
| 错误率一直不触发 | 窗口内请求数是否达到最少请求数 |
| 连续失败次数偏小 | 统计从最新请求向前直到遇到成功请求，成功请求会截断计数 |
| 收到重复告警 | 检查不同规则的关联范围是否重叠，以及每小时频率设置 |
| 发送状态失败 | 检查邮件服务配置、收件人地址、短信或 Webhook 配置 |
| 业务状态码提取不到 | 确认响应体为 JSON，字段路径与响应结构一致 |
限制
- 告警基于历史日志扫描，不是实时流式检测，触发存在扫描周期延迟；
- 单条规则只能关联同一环境下的接口；
- 页面当前只开放邮件通知配置；
- 告警记录不自动清理，需结合数据库容量制定归档策略；
- 告警规则不替代限流与熔断，前者用于发现异常，后者用于实时保护。