268 lines
6.0 KiB
Markdown
268 lines
6.0 KiB
Markdown
# 日志系统使用指南
|
||
|
||
## 概述
|
||
|
||
本项目集成了完整的日志系统，支持多级别日志记录、文件轮转、彩色输出等功能。
|
||
|
||
## 日志配置
|
||
|
||
### 环境变量配置
|
||
|
||
在 `.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
|
||
``` |