API 监控告警系统

LogMonitor - API监控告警系统基于Python的智能API监控系统集成Splunk日志分析和钉钉告警支持多种API类型的实时监控和趋势分析。代码地址https://github.com/junbingliu007/log_monitor功能特性多API类型监控支持多种API类型智能告警分析基于趋势分析的智能告警区分新生异常、紧急恶化、严重恶化等不同级别钉钉集成双向通信支持告警推送和命令接收灵活的时间窗口每种监控类型可配置独立的时间窗口和检查频率排除规则管理支持临时排除当天和永久排除Web管理面板提供Web界面查看监控状态和告警历史数据库持久化MySQL存储配置、排除规则和统计数据系统架构核心组件monitor.py # 主监控引擎APIMonitor ├── alert_manager.py # 告警趋势判定SmartAlertManager ├── splunk_client.py # Splunk查询封装SplunkClient ├── command_handler.py # 命令解析与执行CommandHandler ├── report_builder.py # 监控报告生成ReportBuilder ├── db.py # 数据访问与排除规则维护 ├── web_server.py # FastAPI 管理面板与接口 ├── utils.py # 共享工具函数 └── config.py # 环境变量与运行配置组件职责详解1) monitor.py主控制平面核心类APIMonitor职责初始化所有依赖Splunk、DB、告警管理器、报告生成器、命令处理器、钉钉机器人。维护按监控类型的频率调度monitor_frequencies与上次检查时间last_check_times。按类型分派监控逻辑monitor_2b_api、monitor_system_errors、monitor_api_type。更新内存态最新告警快照latest_alerts供 Web 接口读取。发送钉钉告警消息Markdown。关键点main()中将监控循环放在守护线程运行同时启动 FastAPI 服务。通过_web_server_mod._monitor_mod sys.modules[__main__]共享latest_alerts避免web_serverimport 产生副本。2) alert_manager.py告警决策核心类SmartAlertManager职责输入最近 5 个窗口错误计数输出趋势文本和标识。区分“新生异常P0”与“趋势异常P0”两条分支。使用变化率公式R (C - P) / P × 100%做等级判定。3) splunk_client.py查询适配层核心类SplunkClient职责建立 Splunk 连接并统一执行导出查询CSV。支持在查询语句未显式带earliest_time/latest_time时自动补齐时间范围。提供 URL 过滤条件与查询语句构建辅助函数。4) db.py数据持久化层职责读取监控配置监控类型、接口关键字、频率、状态。管理排除规则TODAY_ONLY、PERMANENT、CANCEL(NULL)。URL 模式化与排除规则 ID 获取/创建get_exclusion_id。每日清理今日排除规则clean_expired_exclusions。5) report_builder.py输出构建层核心类ReportBuilder职责生成按监控类型区分表头的文本报告。结合告警管理器输出趋势标签。追加排除/取消命令提示形成可操作的告警通知文本。6) command_handler.py命令处理层核心类CommandHandler职责解析并执行状态/停止/开始/列表/帮助/排除/永久排除/取消。将命令动作映射为排除规则更新复用APIMonitor.update_exclusion_type。说明当前仓库代码中已实现命令处理逻辑命令输入接入方式由运行环境集成决定例如聊天机器人入口或上层调用。7) web_server.py可视化与运维接口核心框架FastAPI职责提供首页与监控类型页面复用templates/index.html。提供告警快照和排除规则管理 API。接口列表GET /api/alerts读取内存快照告警GET /api/debug线程与缓存调试信息GET /api/exclusions排除规则列表POST /api/exclusion设置排除规则DELETE /api/exclusion/{exclusion_id}取消排除规则运行时线程模型主线程启动APIMonitor再启动 Uvicorn Web 服务。监控线程daemon执行APIMonitor.run()循环按频率分类型检查。Web服务线程/事件循环处理页面与 API 请求。停机行为监控线程是守护线程主进程退出时自动结束。端到端工作流程详细启动阶段读取.env并加载Config。建立 Splunk 和 MySQL 连接加载监控类型频率。调度阶段进入while True循环按monitor_type判断是否到达检查时间。采集阶段从monitor_log_config读取启用接口关键字。查询 Splunk 近窗口错误先定位出错 URL再按排除规则过滤。聚合阶段计算多时间窗口错误统计补齐缺失项并合并 24h 统计。判定阶段调用SmartAlertManager.analyze_trend计算趋势等级。分发阶段写入latest_alertsWeb 展示数据源。若有错误则生成报告并发送钉钉告警。维护阶段每日清理TODAY_ONLY排除规则。每天固定时段重置 24h 统计。快速开始环境要求Python 3.8MySQL 5.7Splunk Enterprise/Cloud访问权限钉钉企业账号和机器人安装步骤克隆项目gitclonerepository-urlcdlog_monitor创建虚拟环境python-mvenv .venv# Windows.venv\Scripts\activate# Linux/Macsource.venv/bin/activate安装依赖pipinstall-rrequirements.txt配置环境变量创建.env文件并配置以下参数# Splunk配置 SPLUNK_HOSTyour-splunk-host SPLUNK_PORT8089 SPLUNK_USERNAMEyour-username SPLUNK_PASSWORDyour-password # 数据库配置 DB_HOSTlocalhost DB_PORT3306 DB_USERyour-db-user DB_PASSWORDyour-db-password DB_NAMElog_monitor # 钉钉Webhook配置 DINGTALK_WEBHOOKhttps://oapi.dingtalk.com/robot/send?access_tokenxxx DINGTALK_SECRETyour-secret DINGTALK_LOG_MAX_LENGTH500 # 钉钉应用机器人配置 DINGTALK_APP_IDyour-app-id DINGTALK_CLIENT_IDyour-client-id DINGTALK_CLIENT_SECRETyour-client-secret DINGTALK_ROBOT_CODEyour-robot-code # Web面板配置 WEB_URLhttp://localhost:8000 # 监控环境 MONITOR_ENVprd初始化数据库确保MySQL数据库已创建并包含以下表结构监控配置表monitor_type, interface, frequency等排除规则表exclusion_type: TODAY_ONLY, PERMANENT错误统计表运行# 启动监控系统主入口包含监控与钉钉命令处理python monitor.py# 仅启动Web面板可选python web_server.py配置说明时间窗口配置在config.py中的TIME_WINDOWS配置不同API类型的时间窗口TIME_WINDOWS{2b-api:[1min,1min,1min,1min,1min],open-api:[2min,2min,2min,2min,2min],callback-api:[10min,10min,10min,10min,10min],app-api:[2min,2min,2min,2min,2min],rpc-api:[2min,2min,2min,2min,2min],system-error:[1min,1min,1min,1min,1min]}支持的时间单位min分钟、h小时、d天告警级别系统根据错误趋势自动判断告警级别 新生异常前一窗口无错误当前窗口出现错误 紧急恶化增长率 ≥ 100%⚠️ 严重恶化增长率 ≥ 50% 持续增长增长率 ≥ 20%➡️ 持续异常错误数量稳定但持续存在趋势变化率公式R (C - P) / P × 100%C当前窗口错误数P前一窗口错误数钉钉命令在钉钉群中机器人使用以下命令状态/status查看监控状态停止/stop停止监控开始/start启动监控列表/list查看当前告警列表帮助/help显示帮助信息排除 [ID]临时排除指定告警当天有效永久排除 [ID]永久排除指定告警取消 [ID]取消排除规则说明命令中的显示码如025会映射为数据库内部 ID去掉首字符后匹配。项目结构log_monitor/ ├── monitor.py # 主程序入口包含 APIMonitor 与 main() 启动逻辑 ├── alert_manager.py # SmartAlertManager趋势分析与告警等级判定 ├── command_handler.py # CommandHandler状态/启停/列表/排除命令解析 ├── report_builder.py # ReportBuilder告警文本与统计周期描述生成 ├── splunk_client.py # SplunkClientSplunk连接、查询执行、结果解析 ├── db.py # DB函数集合配置读取、排除规则维护、URL模式化 ├── web_server.py # FastAPI 服务页面路由 /api/* 管理接口 ├── config.py # Config环境变量加载与全局配置定义 ├── utils.py # 通用工具时间解析、排除ID转换、命令标准化等 ├── requirements.txt # 运行依赖清单 ├── .env.example # 环境变量模板本地复制为 .env 使用 ├── migrations/ │ ├── add_priority_field.sql # 数据库字段演进脚本 │ └── rename_url_field.sql # 数据库字段重命名脚本 ├── templates/ │ └── index.html # Web 面板前端模板 ├── DINGTALK_CONFIG.md # 钉钉接入与配置专项文档 ├── CLAUDE.md # 项目协作说明面向 Claude Code └── README.md # 当前项目总览文档目录补充说明monitor.py是唯一主入口执行python monitor.py后会同时启动监控线程和 Web 服务。web_server.py默认读取monitor.py维护的latest_alerts内存快照不直接查询 Splunk。db.py采用函数式设计而非 ORMSQL 更直观便于快速定位线上问题。migrations/仅保留增量 SQL执行策略应按实际库版本审慎执行。templates/index.html为单模板页面前端数据通过/api/*动态拉取。开发说明线程架构主线程初始化APIMonitor启动监控线程并启动 Uvicorn Web 服务。监控线程守护线程执行APIMonitor.run()周期任务调度与告警发送。Web服务执行流由 Uvicorn 驱动 FastAPI 路由处理页面与 API 请求。线程生命周期监控线程为 daemon主进程退出后自动结束。扩展新的监控类型在数据库中添加新的monitor_type配置在Config.TIME_WINDOWS中添加对应的时间窗口配置确保Splunk查询语句支持新的监控类型自定义告警规则修改alert_manager.py中的analyze_trend方法来调整告警判断逻辑。注意事项凭证安全.env文件包含敏感信息切勿提交到版本控制生产凭据风险config.py可能包含 Splunk/MySQL/钉钉生产凭据严禁将真实凭据提交到仓库Token缓存钉钉access token有效期2小时系统自动刷新提前约200秒刷新数据库连接确保MySQL连接池配置合理避免连接泄漏Splunk查询大时间窗口查询可能较慢建议合理配置时间窗口故障排查监控未启动检查.env配置是否正确确认Splunk和MySQL连接正常查看日志输出的错误信息钉钉消息未收到验证webhook地址和secret是否正确检查钉钉机器人是否已添加到群组确认access token是否有效数据库连接失败检查MySQL服务是否运行验证数据库凭证和权限确认数据库表结构是否完整