|
@@ -0,0 +1,455 @@
|
|
|
+# 日志系统配置指南
|
|
|
+
|
|
|
+## 概述 ✅ **系统已完成部署**
|
|
|
+
|
|
|
+本项目采用统一的日志管理系统,支持模块化配置和多种运行模式。所有日志通过YAML配置文件进行集中管理,支持灵活的格式化、级别控制和文件轮转。
|
|
|
+
|
|
|
+**📅 完成时间**: 2025年7月17日
|
|
|
+**🎯 实施状态**: 100%完成,所有5个模块已全面部署统一日志系统
|
|
|
+**🔄 功能特性**: 支持日志滚动、双重日志机制、任务特定日志
|
|
|
+
|
|
|
+## 日志架构
|
|
|
+
|
|
|
+### 目录结构
|
|
|
+```
|
|
|
+项目根目录/
|
|
|
+├── config/
|
|
|
+│ └── logging_config.yaml # 主配置文件
|
|
|
+├── logs/ # 统一日志目录
|
|
|
+│ ├── app.log # 主应用日志
|
|
|
+│ ├── agent.log # 智能代理日志
|
|
|
+│ ├── vanna.log # Vanna框架日志
|
|
|
+│ ├── data_pipeline.log # 数据管道日志
|
|
|
+│ └── react_agent.log # React Agent日志
|
|
|
+├── core/logging/ # 核心日志管理
|
|
|
+│ ├── __init__.py # 统一入口API
|
|
|
+│ └── log_manager.py # 日志管理器
|
|
|
+└── data_pipeline/training_data/ # 任务特定日志
|
|
|
+ └── {task_id}/
|
|
|
+ └── data_pipeline.log # 任务专用日志
|
|
|
+```
|
|
|
+
|
|
|
+### 模块分类 ✅ **全部已实现**
|
|
|
+
|
|
|
+| 模块 | 日志文件 | 状态 | 说明 |
|
|
|
+|------|----------|------|------|
|
|
|
+| **app** | `app.log` | ✅ 已部署 | 主应用程序、API入口(unified_api.py)、通用功能 |
|
|
|
+| **agent** | `agent.log` | ✅ 已部署 | 智能代理相关功能(agent/*) |
|
|
|
+| **vanna** | `vanna.log` | ✅ 已部署 | Vanna框架相关(core/*, customllm/*) |
|
|
|
+| **data_pipeline** | `data_pipeline.log` | ✅ 已部署 | 数据处理管道(data_pipeline/*) |
|
|
|
+| **react_agent** | `react_agent.log` | ✅ 已部署 | React Agent模块(react_agent/*) |
|
|
|
+
|
|
|
+**📊 统计**: 5个模块,100%完成统一日志部署
|
|
|
+
|
|
|
+## 配置文件详解
|
|
|
+
|
|
|
+### 主配置文件:config/logging_config.yaml
|
|
|
+
|
|
|
+#### 全局配置
|
|
|
+```yaml
|
|
|
+version: 1
|
|
|
+
|
|
|
+# 全局配置
|
|
|
+global:
|
|
|
+ base_level: INFO # 全局基础日志级别
|
|
|
+```
|
|
|
+
|
|
|
+#### 默认配置
|
|
|
+```yaml
|
|
|
+default:
|
|
|
+ level: INFO # 默认日志级别
|
|
|
+ console:
|
|
|
+ enabled: true # 是否启用控制台输出
|
|
|
+ level: INFO # 控制台日志级别
|
|
|
+ format: "%(asctime)s [%(levelname)s] %(name)s: %(message)s"
|
|
|
+ file:
|
|
|
+ enabled: true # 是否启用文件输出
|
|
|
+ level: DEBUG # 文件日志级别
|
|
|
+ filename: "app.log"
|
|
|
+ format: "%(asctime)s [%(levelname)s] [%(name)s] [user:%(user_id)s] [session:%(session_id)s] %(filename)s:%(lineno)d - %(message)s"
|
|
|
+ rotation:
|
|
|
+ enabled: true # 是否启用日志轮转
|
|
|
+ max_size: "50MB"
|
|
|
+ backup_count: 10
|
|
|
+```
|
|
|
+
|
|
|
+#### 模块特定配置
|
|
|
+
|
|
|
+##### App模块
|
|
|
+```yaml
|
|
|
+modules:
|
|
|
+ app:
|
|
|
+ level: INFO
|
|
|
+ console:
|
|
|
+ enabled: true
|
|
|
+ level: INFO
|
|
|
+ format: "%(asctime)s [%(levelname)s] %(name)s: %(message)s"
|
|
|
+ file:
|
|
|
+ enabled: true
|
|
|
+ level: DEBUG
|
|
|
+ filename: "app.log"
|
|
|
+ format: "%(asctime)s [%(levelname)s] [%(name)s] [user:%(user_id)s] [session:%(session_id)s] %(filename)s:%(lineno)d - %(message)s"
|
|
|
+ rotation:
|
|
|
+ enabled: true
|
|
|
+ max_size: "50MB"
|
|
|
+ backup_count: 10
|
|
|
+```
|
|
|
+
|
|
|
+##### Agent模块
|
|
|
+```yaml
|
|
|
+ agent:
|
|
|
+ level: DEBUG
|
|
|
+ console:
|
|
|
+ enabled: true
|
|
|
+ level: INFO
|
|
|
+ format: "%(asctime)s [%(levelname)s] Agent: %(message)s"
|
|
|
+ file:
|
|
|
+ enabled: true
|
|
|
+ level: DEBUG
|
|
|
+ filename: "agent.log"
|
|
|
+ format: "%(asctime)s [%(levelname)s] [%(name)s] [user:%(user_id)s] [session:%(session_id)s] %(filename)s:%(lineno)d - %(message)s"
|
|
|
+ rotation:
|
|
|
+ enabled: true
|
|
|
+ max_size: "30MB"
|
|
|
+ backup_count: 8
|
|
|
+```
|
|
|
+
|
|
|
+##### Data Pipeline模块
|
|
|
+```yaml
|
|
|
+ data_pipeline:
|
|
|
+ level: DEBUG
|
|
|
+ console:
|
|
|
+ enabled: true
|
|
|
+ level: INFO
|
|
|
+ format: "%(asctime)s [%(levelname)s] Pipeline: %(message)s"
|
|
|
+ file:
|
|
|
+ enabled: true
|
|
|
+ level: DEBUG
|
|
|
+ filename: "data_pipeline.log"
|
|
|
+ format: "%(asctime)s [%(levelname)s] [%(name)s] %(filename)s:%(lineno)d - %(message)s"
|
|
|
+ rotation:
|
|
|
+ enabled: true
|
|
|
+ max_size: "20MB"
|
|
|
+ backup_count: 5
|
|
|
+```
|
|
|
+
|
|
|
+##### React Agent模块
|
|
|
+```yaml
|
|
|
+ react_agent:
|
|
|
+ level: DEBUG
|
|
|
+ console:
|
|
|
+ enabled: true
|
|
|
+ level: INFO
|
|
|
+ format: "%(asctime)s [%(levelname)s] ReactAgent: %(message)s"
|
|
|
+ file:
|
|
|
+ enabled: true
|
|
|
+ level: DEBUG
|
|
|
+ filename: "react_agent.log"
|
|
|
+ format: "%(asctime)s [%(levelname)s] [%(name)s] [user:%(user_id)s] [session:%(session_id)s] %(filename)s:%(lineno)d - %(message)s"
|
|
|
+ rotation:
|
|
|
+ enabled: true
|
|
|
+ max_size: "30MB"
|
|
|
+ backup_count: 8
|
|
|
+```
|
|
|
+
|
|
|
+### 配置参数说明
|
|
|
+
|
|
|
+#### 日志级别
|
|
|
+- `DEBUG`: 详细的调试信息
|
|
|
+- `INFO`: 一般信息
|
|
|
+- `WARNING`: 警告信息
|
|
|
+- `ERROR`: 错误信息
|
|
|
+- `CRITICAL`: 严重错误
|
|
|
+
|
|
|
+#### 格式化字符串
|
|
|
+- `%(asctime)s`: 时间戳
|
|
|
+- `%(levelname)s`: 日志级别
|
|
|
+- `%(name)s`: Logger名称
|
|
|
+- `%(message)s`: 日志消息
|
|
|
+- `%(filename)s`: 文件名
|
|
|
+- `%(lineno)d`: 行号
|
|
|
+- `%(user_id)s`: 用户ID(上下文)
|
|
|
+- `%(session_id)s`: 会话ID(上下文)
|
|
|
+
|
|
|
+#### 文件轮转
|
|
|
+- `enabled`: 是否启用轮转
|
|
|
+- `max_size`: 单个文件最大大小
|
|
|
+- `backup_count`: 保留的备份文件数量
|
|
|
+
|
|
|
+## Data Pipeline 特殊配置 ✅ **已完成实现**
|
|
|
+
|
|
|
+### 双重日志机制
|
|
|
+
|
|
|
+Data Pipeline模块支持双重日志机制(已全面实现):
|
|
|
+
|
|
|
+1. **全局日志**: 写入 `logs/data_pipeline.log` ✅
|
|
|
+2. **任务特定日志**: 写入 `data_pipeline/training_data/{task_id}/data_pipeline.log` ✅
|
|
|
+3. **滚动功能**: 全局日志20MB/5备份,任务日志10MB/3备份 ✅
|
|
|
+
|
|
|
+### 使用方法
|
|
|
+
|
|
|
+#### 基础用法
|
|
|
+```python
|
|
|
+from data_pipeline.dp_logging import init_data_pipeline_logging, get_logger
|
|
|
+
|
|
|
+# 初始化日志系统
|
|
|
+init_data_pipeline_logging()
|
|
|
+
|
|
|
+# 获取基础logger(仅写入全局日志)
|
|
|
+logger = get_logger("ComponentName")
|
|
|
+logger.info("这条日志会写入 logs/data_pipeline.log")
|
|
|
+```
|
|
|
+
|
|
|
+#### 任务特定日志
|
|
|
+```python
|
|
|
+from data_pipeline.dp_logging import init_data_pipeline_logging, get_logger
|
|
|
+
|
|
|
+# 初始化日志系统
|
|
|
+init_data_pipeline_logging()
|
|
|
+
|
|
|
+# 获取任务特定logger(同时写入全局和任务日志)
|
|
|
+task_id = "task_20250717_160000"
|
|
|
+logger = get_logger("ComponentName", task_id)
|
|
|
+
|
|
|
+# 这条日志会同时写入两个地方:
|
|
|
+# 1. logs/data_pipeline.log
|
|
|
+# 2. data_pipeline/training_data/task_20250717_160000/data_pipeline.log
|
|
|
+logger.info("处理任务开始")
|
|
|
+```
|
|
|
+
|
|
|
+### 任务目录结构
|
|
|
+```
|
|
|
+data_pipeline/training_data/
|
|
|
+├── task_20250717_160000/
|
|
|
+│ ├── data_pipeline.log # 任务专用日志
|
|
|
+│ ├── task_config.json
|
|
|
+│ ├── task_result.json
|
|
|
+│ └── 其他任务文件...
|
|
|
+├── task_20250717_170000/
|
|
|
+│ ├── data_pipeline.log # 另一个任务的日志
|
|
|
+│ └── 其他任务文件...
|
|
|
+└── ...
|
|
|
+```
|
|
|
+
|
|
|
+### API和命令行模式
|
|
|
+
|
|
|
+#### API模式
|
|
|
+```python
|
|
|
+# 在API调用中使用
|
|
|
+from data_pipeline.dp_logging import init_data_pipeline_logging, get_logger
|
|
|
+
|
|
|
+def process_data_api(task_id: str):
|
|
|
+ init_data_pipeline_logging()
|
|
|
+ logger = get_logger("DataProcessor", task_id)
|
|
|
+
|
|
|
+ logger.info("API模式:开始处理数据")
|
|
|
+ # 处理逻辑...
|
|
|
+ logger.info("API模式:数据处理完成")
|
|
|
+```
|
|
|
+
|
|
|
+#### 命令行模式
|
|
|
+```python
|
|
|
+# 在命令行脚本中使用
|
|
|
+from data_pipeline.dp_logging import init_data_pipeline_logging, get_logger
|
|
|
+
|
|
|
+def main():
|
|
|
+ task_id = "manual_20250717_160000"
|
|
|
+ init_data_pipeline_logging()
|
|
|
+ logger = get_logger("TrainingScript", task_id)
|
|
|
+
|
|
|
+ logger.info("命令行模式:开始训练")
|
|
|
+ # 训练逻辑...
|
|
|
+ logger.info("命令行模式:训练完成")
|
|
|
+
|
|
|
+if __name__ == "__main__":
|
|
|
+ main()
|
|
|
+```
|
|
|
+
|
|
|
+## 编程接口 ✅ **全部可用**
|
|
|
+
|
|
|
+### 核心API
|
|
|
+
|
|
|
+#### 初始化
|
|
|
+```python
|
|
|
+from core.logging import initialize_logging
|
|
|
+
|
|
|
+# 初始化日志系统(使用默认配置文件)
|
|
|
+initialize_logging()
|
|
|
+
|
|
|
+# 使用自定义配置文件
|
|
|
+initialize_logging("custom_config.yaml")
|
|
|
+```
|
|
|
+
|
|
|
+#### 获取Logger
|
|
|
+```python
|
|
|
+from core.logging import (
|
|
|
+ get_app_logger,
|
|
|
+ get_agent_logger,
|
|
|
+ get_vanna_logger,
|
|
|
+ get_data_pipeline_logger,
|
|
|
+ get_react_agent_logger
|
|
|
+)
|
|
|
+
|
|
|
+# 获取不同模块的logger
|
|
|
+app_logger = get_app_logger("ComponentName")
|
|
|
+agent_logger = get_agent_logger("ComponentName")
|
|
|
+vanna_logger = get_vanna_logger("ComponentName")
|
|
|
+data_logger = get_data_pipeline_logger("ComponentName")
|
|
|
+react_logger = get_react_agent_logger("ComponentName")
|
|
|
+```
|
|
|
+
|
|
|
+#### 上下文管理
|
|
|
+```python
|
|
|
+from core.logging import set_log_context, clear_log_context
|
|
|
+
|
|
|
+# 设置上下文信息
|
|
|
+set_log_context(user_id="user123", session_id="sess456")
|
|
|
+
|
|
|
+# 清除上下文
|
|
|
+clear_log_context()
|
|
|
+```
|
|
|
+
|
|
|
+### 使用示例
|
|
|
+
|
|
|
+#### 基本用法
|
|
|
+```python
|
|
|
+from core.logging import initialize_logging, get_app_logger
|
|
|
+
|
|
|
+# 初始化
|
|
|
+initialize_logging()
|
|
|
+
|
|
|
+# 获取logger
|
|
|
+logger = get_app_logger("MyComponent")
|
|
|
+
|
|
|
+# 记录日志
|
|
|
+logger.debug("调试信息")
|
|
|
+logger.info("一般信息")
|
|
|
+logger.warning("警告信息")
|
|
|
+logger.error("错误信息")
|
|
|
+logger.critical("严重错误")
|
|
|
+```
|
|
|
+
|
|
|
+#### 上下文使用
|
|
|
+```python
|
|
|
+from core.logging import initialize_logging, get_app_logger, set_log_context
|
|
|
+
|
|
|
+initialize_logging()
|
|
|
+logger = get_app_logger("APIHandler")
|
|
|
+
|
|
|
+# 设置用户上下文
|
|
|
+set_log_context(user_id="user123", session_id="sess456")
|
|
|
+
|
|
|
+# 这条日志会包含上下文信息
|
|
|
+logger.info("用户请求处理开始")
|
|
|
+```
|
|
|
+
|
|
|
+## 配置自定义
|
|
|
+
|
|
|
+### 创建自定义配置文件
|
|
|
+
|
|
|
+1. 复制 `config/logging_config.yaml` 为新文件
|
|
|
+2. 修改配置参数
|
|
|
+3. 使用自定义配置初始化:
|
|
|
+
|
|
|
+```python
|
|
|
+from core.logging import initialize_logging
|
|
|
+initialize_logging("config/custom_logging.yaml")
|
|
|
+```
|
|
|
+
|
|
|
+### 动态配置调整
|
|
|
+
|
|
|
+```python
|
|
|
+from core.logging import get_logger
|
|
|
+
|
|
|
+# 获取logger后动态调整级别
|
|
|
+logger = get_logger("MyComponent", "app")
|
|
|
+logger.setLevel(logging.DEBUG)
|
|
|
+```
|
|
|
+
|
|
|
+## 最佳实践
|
|
|
+
|
|
|
+### 1. 日志级别选择
|
|
|
+- **DEBUG**: 详细的调试信息,仅在开发环境使用
|
|
|
+- **INFO**: 程序正常运行的关键信息
|
|
|
+- **WARNING**: 潜在问题,但不影响程序运行
|
|
|
+- **ERROR**: 错误情况,但程序可以继续运行
|
|
|
+- **CRITICAL**: 严重错误,程序可能无法继续运行
|
|
|
+
|
|
|
+### 2. 消息格式规范
|
|
|
+```python
|
|
|
+# 推荐格式
|
|
|
+logger.info("用户登录成功", extra={"user_id": "123"})
|
|
|
+logger.error("数据库连接失败", extra={"error": str(e)})
|
|
|
+
|
|
|
+# 避免格式
|
|
|
+logger.info("用户123登录成功") # 不易于查询和分析
|
|
|
+```
|
|
|
+
|
|
|
+### 3. 异常处理
|
|
|
+```python
|
|
|
+try:
|
|
|
+ # 业务逻辑
|
|
|
+ result = process_data()
|
|
|
+ logger.info("数据处理成功")
|
|
|
+except Exception as e:
|
|
|
+ logger.error(f"数据处理失败: {e}", exc_info=True)
|
|
|
+ raise
|
|
|
+```
|
|
|
+
|
|
|
+### 4. 性能考虑
|
|
|
+```python
|
|
|
+# 对于频繁调用的DEBUG日志,使用条件判断
|
|
|
+if logger.isEnabledFor(logging.DEBUG):
|
|
|
+ logger.debug(f"复杂计算结果: {expensive_operation()}")
|
|
|
+```
|
|
|
+
|
|
|
+## 故障排除
|
|
|
+
|
|
|
+### 常见问题
|
|
|
+
|
|
|
+#### 1. 日志文件不生成
|
|
|
+- 检查 `logs/` 目录权限
|
|
|
+- 确认配置文件路径正确
|
|
|
+- 验证 `initialize_logging()` 已调用
|
|
|
+
|
|
|
+#### 2. 控制台无输出
|
|
|
+- 检查配置文件中 `console.enabled` 设置
|
|
|
+- 确认日志级别设置正确
|
|
|
+
|
|
|
+#### 3. 日志格式异常
|
|
|
+- 检查格式化字符串语法
|
|
|
+- 确认上下文变量已正确设置
|
|
|
+
|
|
|
+### 调试方法
|
|
|
+
|
|
|
+#### 启用调试模式
|
|
|
+```python
|
|
|
+import logging
|
|
|
+logging.basicConfig(level=logging.DEBUG)
|
|
|
+
|
|
|
+from core.logging import initialize_logging
|
|
|
+initialize_logging()
|
|
|
+```
|
|
|
+
|
|
|
+#### 查看配置加载情况
|
|
|
+```python
|
|
|
+from core.logging import _log_manager
|
|
|
+print(_log_manager.config)
|
|
|
+```
|
|
|
+
|
|
|
+## 总结 ✅ **系统全面运行**
|
|
|
+
|
|
|
+本项目的日志系统已成功提供了灵活、可扩展的日志管理解决方案。通过统一的配置文件和模块化的设计,实现了不同模块的独立日志管理需求。Data Pipeline模块的双重日志机制特别适合需要任务追踪的场景。
|
|
|
+
|
|
|
+### 🎯 实施完成情况
|
|
|
+- ✅ **5个模块**: app、agent、vanna、data_pipeline、react_agent
|
|
|
+- ✅ **100%滚动支持**: 所有日志文件均支持自动滚动
|
|
|
+- ✅ **双重日志机制**: Data Pipeline支持全局+任务特定日志
|
|
|
+- ✅ **统一API**: 提供完整的编程接口
|
|
|
+- ✅ **配置文件**: 单一YAML配置管理所有模块
|
|
|
+
|
|
|
+### 🚀 系统优势
|
|
|
+正确使用日志系统可以大大提高问题诊断效率和系统可维护性。当前系统已在生产环境中充分利用不同级别的日志记录,为监控和故障排除提供有力支持。
|
|
|
+
|
|
|
+**部署完成时间**: 2025年7月17日
|
|
|
+**系统状态**: 生产就绪,所有功能正常运行
|