jzw/VWED_server

Fork 0

靳中伟 2899453300 add api

2025-07-14 10:29:37 +08:00

6.1 KiB

Raw Blame History

告警同步功能使用说明

功能概述

告警同步功能会自动将您的VWED任务微服务中产生的WARNING及以上级别的日志同步到主系统，实现统一的告警管理。

核心特性

自动同步: 无需修改现有业务代码，所有WARNING及以上级别的日志会自动同步
异步处理: 采用异步队列，不影响业务性能
智能分类: 根据logger名称自动分类告警类型（系统/机器人/任务）
错误重试: 支持配置重试次数和延迟
灵活配置: 支持开关控制和详细参数配置

告警级别映射

Python日志级别	主系统告警级别	说明
logging.WARNING	2 (警告)	需要关注但不影响系统运行
logging.ERROR	3 (错误)	影响功能但系统可继续运行
logging.CRITICAL	4 (严重)	严重错误，需要立即处理
logging.INFO	-	不同步（信息级别）

告警类型自动识别

系统会根据logger名称自动识别告警类型：

Logger名称包含关键词	告警类型	主系统type值
task, execution, scheduler, template	任务告警	3
robot, vehicle, amr	机器人告警	2
其他	系统告警	1

配置说明

在config/settings.py中的相关配置项：

# 告警同步配置
ALERT_SYNC_ENABLED: bool = True                    # 是否启用告警同步
ALERT_SYNC_HOST: str = "192.168.189.97"           # 主系统IP
ALERT_SYNC_PORT: int = 8080                       # 主系统端口
ALERT_SYNC_API_PATH: str = "/warning"             # 告警API路径
ALERT_SYNC_TIMEOUT: int = 10                      # 请求超时时间（秒）
ALERT_SYNC_RETRY_COUNT: int = 3                   # 重试次数
ALERT_SYNC_RETRY_DELAY: int = 1                   # 重试延迟（秒）
ALERT_SYNC_BATCH_SIZE: int = 10                   # 批量发送大小
ALERT_SYNC_QUEUE_SIZE: int = 1000                 # 队列大小
ALERT_SYNC_MIN_LEVEL: str = "WARNING"             # 最小告警级别

环境变量配置

也可以通过环境变量配置：

export ALERT_SYNC_ENABLED=true
export ALERT_SYNC_HOST=192.168.189.97
export ALERT_SYNC_PORT=8080
export ALERT_SYNC_TIMEOUT=10

使用方法

1. 基本使用

直接使用现有的日志记录方式，系统会自动同步：

from utils.logger import get_logger

logger = get_logger("services.task_service")

# 这些日志会自动同步到主系统
logger.warning("任务执行超时")
logger.error("任务执行失败")
logger.critical("任务调度器严重错误")

# 这些日志不会同步
logger.info("任务开始执行")
logger.debug("调试信息")

2. 异常处理

使用exception方法记录异常，会包含更详细的信息：

try:
    # 业务逻辑
    result = some_risky_operation()
except Exception as e:
    logger.exception("操作失败")  # 会自动同步并包含异常堆栈

3. 不同模块的告警

# 任务相关告警
task_logger = get_logger("services.task_execution")
task_logger.error("任务执行失败")  # 会被标记为任务告警(type=3)

# 机器人相关告警
robot_logger = get_logger("services.robot_scheduler")
robot_logger.warning("机器人电池电量低")  # 会被标记为机器人告警(type=2)

# 系统相关告警
system_logger = get_logger("database.connection")
system_logger.error("数据库连接失败")  # 会被标记为系统告警(type=1)

自动处理的场景

以下场景的错误会自动记录日志并同步：

HTTP错误: 4xx和5xx HTTP状态码
参数验证错误: FastAPI参数验证失败
未捕获异常: 全局异常处理器捕获的异常
业务逻辑错误: 您在代码中主动记录的WARNING及以上级别日志

同步到主系统的数据格式

发送到主系统的数据格式如下：

{
    "type": 3,                           // 告警类型: 1-系统, 2-机器人, 3-任务
    "level": 2,                          // 告警级别: 2-警告, 3-错误, 4-严重
    "code": 5678,                        // 4位告警码（5400-9999范围，自动生成）
    "name": "TASK_SERVICE_WARNING",      // 告警名称（自动生成）
    "description": "任务执行超时 [文件: task_service.py:123] [函数: execute_task()]",
    "solution": "请检查相关日志文件获取详细的异常堆栈信息，并根据异常类型进行排查"  // 可选
}

测试功能

运行测试脚本验证功能：

cd scripts
python test_alert_sync.py

测试脚本会：

发送不同类型和级别的告警
验证INFO级别不会同步
显示服务状态信息

故障排查

1. 检查配置

from utils.alert_sync import get_alert_sync_service
service = get_alert_sync_service()

print(f"启用状态: {service.enabled}")
print(f"同步URL: {service.sync_url}")
print(f"队列大小: {service.alert_queue.qsize()}")

2. 查看日志

告警同步的错误信息会输出到控制台，查看是否有网络或配置问题。

3. 临时禁用

如果需要临时禁用告警同步：

export ALERT_SYNC_ENABLED=false

或在配置文件中设置：

ALERT_SYNC_ENABLED: bool = False

性能影响

内存占用: 队列最大1000个待发送告警，每个告警约1KB
网络开销: 异步发送，不阻塞业务逻辑
CPU占用: 后台线程处理，对主业务影响极小

注意事项

网络依赖: 需要确保微服务能够访问主系统的告警接口
队列满载: 如果队列满载，新的告警会被丢弃
重试机制: 发送失败会自动重试，但最终失败的告警会丢失
日志循环: 告警同步本身的错误不会触发新的告警，避免无限循环

最佳实践

合理使用日志级别: 只有真正需要关注的问题才使用WARNING及以上级别
提供有用信息: 在日志消息中包含足够的上下文信息
监控队列状态: 定期检查队列大小，避免积压
测试网络连通: 部署前测试到主系统的网络连通性

6.1 KiB Raw Blame History Unescape Escape