# 日志系统使用指南

## 概述

本项目集成了完整的日志系统，支持多级别日志记录、文件轮转、彩色输出等功能。

## 日志配置

### 环境变量配置

在 `.env` 文件中配置以下日志相关参数：

```bash
# 日志级别: DEBUG, INFO, WARNING, ERROR, CRITICAL
LOG_LEVEL=INFO

# 日志文件路径
LOG_FILE=logs/app.log

# 单个日志文件最大大小（字节）
LOG_MAX_BYTES=10485760  # 10MB

# 备份文件数量
LOG_BACKUP_COUNT=5

# 日志格式
LOG_FORMAT=%(asctime)s - %(name)s - %(levelname)s - %(message)s

# 时间格式
LOG_DATE_FORMAT=%Y-%m-%d %H:%M:%S
```

### 日志级别说明

- **DEBUG**: 详细的调试信息，通常只在开发时使用
- **INFO**: 一般信息，记录应用正常运行状态
- **WARNING**: 警告信息，表示可能出现问题
- **ERROR**: 错误信息，表示发生了错误但不影响应用运行
- **CRITICAL**: 严重错误，可能导致应用崩溃

## 使用方法

### 1. 获取日志器

```python
from app.logger import get_logger

# 方式1: 指定名称
logger = get_logger("my_module")

# 方式2: 自动获取模块名
logger = get_logger()  # 自动获取调用者的模块名
```

### 2. 记录日志

```python
logger.debug("这是调试信息")
logger.info("这是一般信息")
logger.warning("这是警告信息")
logger.error("这是错误信息")
logger.critical("这是严重错误信息")

# 记录异常信息（包含堆栈跟踪）
try:
    # 可能出错的代码
    result = 1 / 0
except Exception as e:
    logger.error(f"计算失败: {e}", exc_info=True)
```

### 3. 使用预定义日志器

```python
from app.logger import (
    app_logger,      # 应用级日志
    api_logger,      # API接口日志
    db_logger,       # 数据库操作日志
    redis_logger,    # Redis操作日志
    external_api_logger  # 外部API调用日志
)

# 使用示例
api_logger.info("API接口被访问")
db_logger.info("数据库操作完成")
```

## 日志输出

### 控制台输出

控制台输出支持彩色显示，不同级别的日志使用不同颜色：

- 🔵 DEBUG: 青色
- 🟢 INFO: 绿色
- 🟡 WARNING: 黄色
- 🔴 ERROR: 红色
- 🟣 CRITICAL: 紫色

### 文件输出

日志文件保存在配置的路径中，支持自动轮转：

- 当文件大小超过 `LOG_MAX_BYTES` 时，会自动创建备份文件
- 备份文件命名格式：`app.log.1`, `app.log.2`, ...
- 最多保留 `LOG_BACKUP_COUNT` 个备份文件

## 项目中的日志记录

### 1. 应用启动/关闭日志

```python
# 应用启动
logger.info("🚀 应用启动中...")
logger.info("✅ 数据库连接成功")
logger.info("🎉 应用启动完成!")

# 应用关闭
logger.info("🛑 应用关闭中...")
logger.info("👋 应用已关闭")
```

### 2. API接口日志

```python
# 请求接收
logger.info(f"🔥 收到AI Talk回调请求: siteId={siteId}, count={count}")

# 业务逻辑
logger.info(f"✅ count={count} >= {threshold}，直接返回")
logger.info(f"📞 调用外部API，重试次数: {retry_count}")

# 错误处理
logger.error(f"❌ 服务器内部错误: {e}", exc_info=True)
```

### 3. 数据库操作日志

```python
# 数据库初始化
logger.info("📊 初始化数据库表结构...")
logger.info("✅ 数据库表结构初始化完成")

# 数据记录
logger.info(f"📝 记录回调请求: siteId={siteId}, count={count}")
```

### 4. Redis操作日志

```python
# 锁操作
logger.debug(f"🔒 尝试获取Redis锁: {key}")
logger.debug(f"✅ Redis锁获取成功: {key}")
```

### 5. 外部API调用日志

```python
# API调用
logger.info(f"🌐 开始调用外部API: {url}")
logger.debug(f"📤 第{attempt + 1}次尝试调用外部API")
logger.info(f"✅ 外部API调用成功，状态码: {status}")
logger.warning(f"⚠️ 外部API返回错误状态码: {status}")
```

## 日志查看和分析

### 1. 实时查看日志

```bash
# 查看最新日志
tail -f logs/app.log

# 查看带颜色的日志（如果支持）
tail -f logs/app.log | ccze  # 需要安装ccze
```

### 2. 搜索日志

```bash
# 搜索错误日志
grep "ERROR" logs/app.log

# 搜索特定接口的日志
grep "siteId=123" logs/app.log

# 搜索特定时间范围的日志
grep "2024-12-02 10:" logs/app.log
```

### 3. 日志统计

```bash
# 统计不同级别的日志数量
grep -c "INFO" logs/app.log
grep -c "ERROR" logs/app.log
grep -c "WARNING" logs/app.log

# 查看最频繁的错误
grep "ERROR" logs/app.log | sort | uniq -c | sort -nr
```

## 最佳实践

### 1. 日志级别使用建议

- **生产环境**: 使用 INFO 或 WARNING 级别
- **开发环境**: 使用 DEBUG 级别查看详细信息
- **测试环境**: 使用 INFO 级别

### 2. 日志内容建议

- 包含关键业务参数（如 siteId, count）
- 使用表情符号增强可读性
- 错误日志包含完整的异常信息
- 重要操作记录开始和结束状态

### 3. 性能考虑

- 避免在高频循环中记录 DEBUG 日志
- 使用日志级别控制避免不必要的字符串格式化
- 合理设置日志轮转大小和数量

### 4. 安全考虑

- 避免在日志中记录敏感信息（密码、密钥等）
- 生产环境注意日志文件的访问权限
- 定期清理旧的日志文件

## 故障排查

### 1. 常见问题

**问题**: 日志文件没有创建
- 检查日志目录是否存在且有写权限
- 检查 LOG_FILE 配置是否正确

**问题**: 日志没有输出到控制台
- 检查 LOG_LEVEL 配置是否过高
- 检查是否有其他处理器冲突

**问题**: 日志轮转不工作
- 检查 LOG_MAX_BYTES 设置是否合理
- 检查文件系统权限

### 2. 调试日志系统

```python
# 检查日志器配置
import logging
logger = logging.getLogger()
print(f"日志级别: {logger.level}")
print(f"处理器数量: {len(logger.handlers)}")
for handler in logger.handlers:
    print(f"处理器: {handler.__class__.__name__}")
```

## 测试

运行日志系统测试：

```bash
# 运行日志测试
python -m pytest test_logger.py -v

# 运行特定测试
python -m pytest test_logger.py::TestLogger::test_logger_setup -v
```