# 告警同步功能使用说明

## 功能概述

告警同步功能会自动将您的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. **测试网络连通**: 部署前测试到主系统的网络连通性