199 lines
6.1 KiB
Markdown
199 lines
6.1 KiB
Markdown
# 告警同步功能使用说明
|
||
|
||
## 功能概述
|
||
|
||
告警同步功能会自动将您的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`中的相关配置项：
|
||
|
||
```python
|
||
# 告警同步配置
|
||
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" # 最小告警级别
|
||
```
|
||
|
||
### 环境变量配置
|
||
|
||
也可以通过环境变量配置：
|
||
|
||
```bash
|
||
export ALERT_SYNC_ENABLED=true
|
||
export ALERT_SYNC_HOST=192.168.189.97
|
||
export ALERT_SYNC_PORT=8080
|
||
export ALERT_SYNC_TIMEOUT=10
|
||
```
|
||
|
||
## 使用方法
|
||
|
||
### 1. 基本使用
|
||
|
||
直接使用现有的日志记录方式，系统会自动同步：
|
||
|
||
```python
|
||
from utils.logger import get_logger
|
||
|
||
logger = get_logger("services.task_service")
|
||
|
||
# 这些日志会自动同步到主系统
|
||
logger.warning("任务执行超时")
|
||
logger.error("任务执行失败")
|
||
logger.critical("任务调度器严重错误")
|
||
|
||
# 这些日志不会同步
|
||
logger.info("任务开始执行")
|
||
logger.debug("调试信息")
|
||
```
|
||
|
||
### 2. 异常处理
|
||
|
||
使用exception方法记录异常，会包含更详细的信息：
|
||
|
||
```python
|
||
try:
|
||
# 业务逻辑
|
||
result = some_risky_operation()
|
||
except Exception as e:
|
||
logger.exception("操作失败") # 会自动同步并包含异常堆栈
|
||
```
|
||
|
||
### 3. 不同模块的告警
|
||
|
||
```python
|
||
# 任务相关告警
|
||
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)
|
||
```
|
||
|
||
## 自动处理的场景
|
||
|
||
以下场景的错误会自动记录日志并同步：
|
||
|
||
1. **HTTP错误**: 4xx和5xx HTTP状态码
|
||
2. **参数验证错误**: FastAPI参数验证失败
|
||
3. **未捕获异常**: 全局异常处理器捕获的异常
|
||
4. **业务逻辑错误**: 您在代码中主动记录的WARNING及以上级别日志
|
||
|
||
## 同步到主系统的数据格式
|
||
|
||
发送到主系统的数据格式如下：
|
||
|
||
```json
|
||
{
|
||
"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": "请检查相关日志文件获取详细的异常堆栈信息，并根据异常类型进行排查" // 可选
|
||
}
|
||
```
|
||
|
||
## 测试功能
|
||
|
||
运行测试脚本验证功能：
|
||
|
||
```bash
|
||
cd scripts
|
||
python test_alert_sync.py
|
||
```
|
||
|
||
测试脚本会：
|
||
- 发送不同类型和级别的告警
|
||
- 验证INFO级别不会同步
|
||
- 显示服务状态信息
|
||
|
||
## 故障排查
|
||
|
||
### 1. 检查配置
|
||
|
||
```python
|
||
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. 临时禁用
|
||
|
||
如果需要临时禁用告警同步：
|
||
|
||
```bash
|
||
export ALERT_SYNC_ENABLED=false
|
||
```
|
||
|
||
或在配置文件中设置：
|
||
|
||
```python
|
||
ALERT_SYNC_ENABLED: bool = False
|
||
```
|
||
|
||
## 性能影响
|
||
|
||
- **内存占用**: 队列最大1000个待发送告警，每个告警约1KB
|
||
- **网络开销**: 异步发送，不阻塞业务逻辑
|
||
- **CPU占用**: 后台线程处理，对主业务影响极小
|
||
|
||
## 注意事项
|
||
|
||
1. **网络依赖**: 需要确保微服务能够访问主系统的告警接口
|
||
2. **队列满载**: 如果队列满载，新的告警会被丢弃
|
||
3. **重试机制**: 发送失败会自动重试，但最终失败的告警会丢失
|
||
4. **日志循环**: 告警同步本身的错误不会触发新的告警，避免无限循环
|
||
|
||
## 最佳实践
|
||
|
||
1. **合理使用日志级别**: 只有真正需要关注的问题才使用WARNING及以上级别
|
||
2. **提供有用信息**: 在日志消息中包含足够的上下文信息
|
||
3. **监控队列状态**: 定期检查队列大小，避免积压
|
||
4. **测试网络连通**: 部署前测试到主系统的网络连通性 |