Files
douyin_guaji-main/docs/LOGGING_IMPROVEMENTS.md
T
Your Name c67f22f76f feat: Refactor and reorganize project structure with new modules and files
- Deleted obsolete files including test scripts and configuration files to streamline the project.
- Introduced new modules for handling Douyin functionalities, including core operations, logging, and GUI components.
- Updated import paths to reflect the new module structure, enhancing code organization and maintainability.
- Added configuration files and documentation to support the new structure and improve user guidance.
2025-12-28 14:16:40 +08:00

163 lines
5.5 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 日志系统优化说明
## 概述
本次优化系统性地增强了现有行为日志系统,使其记录更详细、结构更清晰,并包含完整的调试上下文信息,以便快速定位和诊断程序运行中的问题。
## 主要改进
### 1. 创建增强的日志配置模块 (`douyin_logger.py`)
- **标准 Python logging 集成**:使用 Python 标准 `logging` 模块,提供更强大的日志管理能力
- **日志级别管理**:支持 DEBUG, INFO, WARNING, ERROR, CRITICAL 五个级别
- **日志轮转**:支持按大小(RotatingFileHandler)和时间(TimedRotatingFileHandler)自动轮转
- **灵活的配置**:从 `config.json` 读取配置,支持环境变量覆盖
- **日志上下文管理器**:提供 `LogContext` 类用于记录函数调用、参数、返回值、耗时等
### 2. 增强 `_log_kv` 方法 (`douyin_fudai.py`)
- **集成标准 logging**:在保持原有格式和功能的基础上,同时输出到标准 logging 系统
- **自动异常堆栈记录**:检测异常上下文并自动记录完整堆栈信息
- **调用者信息**:自动记录模块名、函数名、行号
- **日志级别支持**:通过 `level` 参数控制日志级别
- **向后兼容**:完全兼容现有的 `_log_kv` 调用方式
### 3. 配置文件更新 (`config.json`)
添加了日志配置选项:
```json
"logging": {
"level": "INFO", // 日志级别:DEBUG, INFO, WARNING, ERROR, CRITICAL
"file_path": "logs/unified.log", // 日志文件路径
"rotation": {
"enabled": true, // 是否启用日志轮转
"max_bytes": 10485760, // 按大小轮转:最大文件大小(字节)
"backup_count": 5, // 保留的备份文件数量
"when": "midnight", // 按时间轮转:轮转时间点
"interval": 1 // 按时间轮转:间隔天数
}
}
```
### 4. 日志格式优化
标准 logging 输出格式:
```
%(asctime)s - [%(levelname)s] - %(name)s:%(funcName)s:%(lineno)d - %(message)s
```
示例输出:
```
2025-01-20 10:30:45 - [INFO] - douyin:run_once_basic:910 - [截图] 截图+阶段诊断 stage=IN_LIVE_ROOM seen=直播间
```
### 5. 异常处理增强
- **完整堆栈跟踪**:所有异常都记录完整的堆栈信息
- **异常上下文**:自动检测并记录异常发生时的上下文信息
- **错误级别**:异常自动标记为 ERROR 级别
## 使用方法
### 基本使用
现有的 `_log_kv` 调用方式保持不变:
```python
# 基本用法
self._log_kv("标签", "消息", field1=value1, field2=value2)
# 指定日志级别
self._log_kv("标签", "消息", level="DEBUG", field1=value1)
# 记录异常(自动包含堆栈)
try:
# 某些操作
pass
except Exception as e:
self._log_kv("错误", "操作失败", error=str(e), level="ERROR", exc_info=sys.exc_info())
```
### 使用标准 logging
也可以直接使用标准 logging:
```python
import douyin_logger
logger = douyin_logger.get_logger("douyin")
logger.debug("调试信息")
logger.info("一般信息")
logger.warning("警告信息")
logger.error("错误信息", exc_info=True) # 包含异常堆栈
```
### 使用日志上下文管理器
记录函数调用的详细信息:
```python
import douyin_logger
logger = douyin_logger.get_logger("douyin")
def my_function(arg1, arg2):
with douyin_logger.LogContext(logger, "my_function", log_args=True, log_result=True):
# 函数体
result = arg1 + arg2
return result
```
## 环境变量
可以通过环境变量动态调整日志级别(开发调试时使用):
```bash
# Windows
set DOUYIN_LOG_LEVEL=DEBUG
# Linux/Mac
export DOUYIN_LOG_LEVEL=DEBUG
```
## 日志文件位置
- 默认路径:`logs/unified.log`
- 可在 `config.json` 中通过 `logging.file_path` 配置
- 日志轮转后的备份文件:`logs/unified.log.2025-01-20` 等
## 日志级别说明
- **DEBUG**:详细的调试信息,包括函数调用、参数、返回值等
- **INFO**:一般信息,程序正常运行的关键步骤
- **WARNING**:警告信息,程序可以继续运行但可能存在潜在问题
- **ERROR**:错误信息,程序遇到错误但可以继续运行
- **CRITICAL**:严重错误,程序可能无法继续运行
## 最佳实践
1. **关键操作**:在关键业务逻辑处(如福袋识别、界面操作)记录详细日志
2. **异常处理**:所有异常都应该被捕获并记录,使用 `level="ERROR"` 和 `exc_info=sys.exc_info()`
3. **性能监控**:使用 `_log_step_time` 记录关键步骤的耗时
4. **调试模式**:开发调试时设置 `DOUYIN_LOG_LEVEL=DEBUG` 环境变量获取最详细信息
5. **生产环境**:生产环境建议使用 `INFO` 或 `WARNING` 级别,平衡性能与可观察性
## 注意事项
1. **不要修改 fudai1.py**:按照要求,未修改 `原始代码/fudai1.py`,所有增强都在 `douyin_fudai.py` 中实现
2. **向后兼容**:所有现有的 `_log_kv` 调用都保持兼容,无需修改
3. **日志轮转**:日志文件会自动轮转,避免单个文件过大
4. **性能影响**:标准 logging 的性能开销很小,但在高频调用时建议使用适当的日志级别
## 后续优化建议
1. **结构化日志**:考虑使用 JSON 格式的结构化日志,便于日志分析工具处理
2. **日志聚合**:对于分布式部署,可以考虑集成日志聚合服务(如 ELK、Loki 等)
3. **性能指标**:添加更多性能指标记录(如函数调用次数、平均耗时等)
4. **日志过滤**:添加日志过滤功能,可以根据标签、级别等条件过滤日志