Skip to content

ALERT_GUIDELINE.md

Latest commit

 

History

History
247 lines (187 loc) · 8.26 KB

ALERT_GUIDELINE.md

File metadata and controls

247 lines (187 loc) · 8.26 KB

警报功能使用指南

功能概述

警报功能是SpringBoot-API-Scheduler的一个重要特性，它能够监控API任务的执行情况，并在断言失败率达到设定阈值时自动触发警报通知。该功能可以帮助您及时发现API服务的问题并采取相应措施。

警报工作原理

  1. 周期性检查：系统每小时自动检查一次所有启用警报的任务
  2. 失败率统计：对于每个任务，系统会统计指定时间窗口内API执行的断言失败率
  3. 阈值比较：将计算出的失败率与配置的阈值进行比较
  4. 触发警报：如果失败率超过阈值，则触发警报并向指定API发送通知
  5. 记录保存：所有警报事件都会被记录下来供后续查看和分析

警报配置说明

警报配置项详解

1. 失败率阈值 (%)

  • 作用：设置触发警报的断言失败率阈值
  • 取值范围：1-100
  • 示例：设置为50表示当任务在指定时间窗口内的断言失败率超过50%时触发警报

2. 检查间隔 (分钟)

  • 作用：定义检查时间窗口大小，同时也是检查频率的重要参数
  • 取值范围：5-1440分钟（1天）
  • 说明：系统会检查任务在过去N分钟内的执行记录（N为该值），同时每10分钟检查一次

3. 警报API地址

  • 作用：指定接收警报通知的API地址
  • 格式：完整的URL地址，如 https://api.example.com/alert
  • 说明：当警报触发时，系统会向该地址发送HTTP请求
  • 支持的变量：
    • ${taskId}：任务ID
    • ${taskName}：任务名称
    • ${failureRate}：失败率
    • ${failureCount}：失败次数
    • ${totalCount}：总执行次数

4. 请求方法

  • 选项：GET 或 POST
  • 默认值：POST
  • 说明：发送警报通知时使用的HTTP方法

5. 请求头 (JSON格式)

  • 作用：定义发送警报请求时的HTTP头部信息
  • 格式：JSON字符串
  • 示例：{"Content-Type": "application/json", "Authorization": "Bearer token123"}

6. 请求体 (JSON格式)

  • 作用：定义发送警报请求时的请求体内容
  • 格式：JSON字符串
  • 支持的变量：
    • ${taskId}：任务ID
    • ${taskName}：任务名称
    • ${failureRate}：失败率
    • ${failureCount}：失败次数
    • ${totalCount}：总执行次数
  • 示例：{"message": "任务[${taskName}]断言失败率过高", "failureRate": "${failureRate}%"}

7. 启用警报功能

  • 作用：控制是否启用警报功能
  • 选项：勾选启用，不勾选禁用
  • 说明：只有启用后警报功能才会生效

警报触发条件

警报会在以下条件同时满足时触发：

  1. 任务的警报功能已被启用
  2. 在过去的N分钟内（N为检查间隔配置值）有API执行记录
  3. 这些执行记录中的断言失败率超过了设定的阈值

失败率计算公式

失败率 = (断言失败次数 / 总执行次数) × 100%

其中：

  • 断言失败次数：在检查时间窗口内，断言结果为失败的执行次数
  • 总执行次数：在检查时间窗口内的总执行次数

配置步骤

步骤1：进入警报配置界面

  1. 登录系统管理界面
  2. 在任务管理页面点击"警报配置"按钮

步骤2：填写警报配置参数

  1. 设置失败率阈值：

    • 根据业务需求设置合适的阈值
    • 一般建议设置为10-50之间

  2. 设置检查间隔：

    • 根据任务执行频率设置合适的时间窗口
    • 如任务每5分钟执行一次，可设置检查间隔为30分钟

  3. 配置警报API地址：

    • 填写接收警报通知的API地址
    • 确保该地址可以正常访问

  4. 选择请求方法：

    • 通常选择POST方法
    • 根据接收端API的要求选择

  5. 配置请求头：

    • 如需身份验证，添加相应的认证头
    • 设置正确的Content-Type

  6. 编写请求体：

    • 使用支持的变量构建有意义的警报消息
    • 确保JSON格式正确

  7. 启用警报功能：

    • 勾选启用选项激活警报功能

步骤3：保存配置

点击"保存配置"按钮完成警报配置。

警报记录查看

系统提供了警报记录查看功能，您可以：

  1. 在导航栏点击"警报记录"进入记录页面
  2. 查看所有警报事件的详细信息
  3. 按任务名称筛选记录
  4. 记录按触发时间倒序排列

警报变量说明

在配置警报API的请求体时，可以使用以下变量：

变量名 说明 示例值
${taskId} 任务ID "task-12345"
${taskName} 任务名称 "获取用户信息"
${failureRate} 断言失败率 "30%"
${failureCount} 断言失败次数 "3"
${totalCount} 总执行次数 "10"

最佳实践

1. 阈值设置建议

  • 高重要性任务：阈值设为10-20%，确保及时发现问题
  • 普通任务：阈值设为30-50%，避免频繁误报
  • 低重要性任务：阈值设为50%以上，只关注严重问题

2. 检查间隔配置

  • 高频任务（每分钟执行）：检查间隔设为30-60分钟
  • 中频任务（每小时执行）：检查间隔设为120-240分钟
  • 低频任务（每天执行）：检查间隔设为720-1440分钟

3. 警报API设计

建议警报接收API具备以下能力：

  • 能够处理重复警报（同一问题可能多次触发警报）
  • 能够记录警报来源和详细信息
  • 能够区分不同类型的警报
  • 支持多种通知方式（邮件、短信、微信等）

4. 警报处理流程

  1. 接收警报：警报API接收到警报通知
  2. 记录日志：将警报信息记录到日志系统
  3. 发送通知：通过邮件、短信等方式通知相关人员
  4. 问题排查：根据警报信息排查问题原因
  5. 问题解决：修复导致警报的问题
  6. 验证恢复：确认问题已解决，警报恢复正常

故障排除

常见问题

  1. 警报未触发

    • 检查任务是否启用了警报功能
    • 确认任务在检查时间窗口内有执行记录
    • 验证失败率是否确实超过了阈值
    • 检查系统时间是否准确

  2. 警报API未收到通知

    • 检查警报API地址是否正确
    • 验证网络连接是否正常
    • 确认请求方法、请求头和请求体配置是否正确
    • 查看系统日志是否有错误信息

  3. 警报过于频繁

    • 适当提高失败率阈值
    • 增加检查时间窗口（增大检查间隔）
    • 优化API任务减少断言失败

调试技巧

  1. 查看任务执行日志：检查任务的断言执行结果
  2. 手动计算失败率：根据日志记录手动计算失败率验证系统计算是否正确
  3. 临时调整配置：为了测试可以临时降低阈值或减小检查间隔
  4. 查看系统日志：在系统日志中查找警报相关的日志信息

数据库表结构

alert_config 表

  • id: 配置ID
  • task_id: 关联的任务ID
  • failure_rate_threshold: 失败率阈值
  • check_interval: 检查间隔(分钟)
  • api_url: 警报API地址
  • http_method: 请求方法
  • headers: 请求头(JSON格式)
  • body: 请求体(JSON格式)
  • enabled: 是否启用
  • create_time: 创建时间
  • update_time: 更新时间
  • last_check_time: 上次检查时间

alert_record 表

  • id: 记录ID
  • task_id: 关联的任务ID
  • task_name: 任务名称
  • failure_rate: 失败率
  • failure_count: 失败次数
  • total_count: 总执行次数
  • alert_message: 警报消息
  • api_url: 调用的API地址
  • response: API响应结果
  • alert_time: 警报触发时间
  • create_time: 创建时间

注意事项

  1. 系统限制：目前系统中只能有一个警报配置记录，这是全局唯一的配置
  2. 检查频率：警报检查每小时执行一次，不能自定义检查频率
  3. 时间窗口：检查间隔既决定了检查频率也决定了统计时间窗口
  4. 数据保留：警报记录会保留30天，之后会被自动清理
  5. 网络依赖：警报功能依赖网络通信，确保系统可以访问配置的警报API地址

更新日志

v1.0.0

  • 新增警报功能
  • 支持基于断言失败率的警报触发机制
  • 提供警报配置界面
  • 实现警报记录查看功能
  • 支持通过HTTP API发送警报通知