Read file: docs/日志服务使用清单.md Read file: docs/全局log服务改造方案_优化版.md 现在我来为您创建一份完整的日志规范化改造文档：

Read file: docs/日志服务改造检查报告.md 现在我来创建一份完整的日志规范化改造文档：

日志规范化改造实施方案

1. 项目概述

1.1 改造目标

将项目从分散的日志管理方式统一为中央化的日志管理系统，实现：

统一的日志服务架构
模块独立的日志配置
支持API和命令行两种运行模式
自动日志轮转和清理
灵活的上下文管理

1.2 当前问题分析

经过代码分析，发现以下主要问题：

日志体系分散：存在3套独立的日志管理器
- core/logging/log_manager.py - 中央日志管理器
- data_pipeline/dp_logging/manager.py - 数据管道独立日志
- react_agent/logger.py - React Agent独立日志
print语句残留：多个模块仍使用print输出
配置不统一：各模块使用不同的日志配置方式
文件管理混乱：日志文件分散在不同目录

2. 改造方案设计

2.1 统一日志架构

项目根目录/ ├── core/logging/ # 中央日志服务 │ ├── init.py # 统一入口 │ └── log_manager.py # 核心管理器 ├── config/ │ └── logging_config.yaml # 统一配置文件 ├── logs/ # 统一日志目录 │ ├── app.log # 主应用日志 │ ├── agent.log # Agent模块日志 │ ├── vanna.log # Vanna相关日志 │ ├── data_pipeline.log # 数据管道日志 │ └── react_agent.log # React Agent日志 └── 各业务模块/ # 使用统一日志API

2.2 模块日志分配

模块	日志文件	主要组件	说明
App	`app.log`	unified_api.py, citu_app.py, common/*	主应用和通用功能
Agent	`agent.log`	agent/, agent/tools/	智能代理相关
Vanna	`vanna.log`	core/, customllm/, customembedding/, custompgvector/	Vanna框架相关
Data Pipeline	`data_pipeline.log`	data_pipeline/*	数据处理管道
React Agent	`react_agent.log`	react_agent/*	React Agent模块

3. 具体实施步骤

3.1 第一步：完善配置文件

3.1.1 更新config/logging_config.yaml

version: 1

# 全局配置
global:
  base_level: INFO
  
# 默认配置（用于app.log）
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

# 模块特定配置
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:
    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
  
  vanna:
    level: DEBUG
    console:
      enabled: true
      level: INFO
      format: "%(asctime)s [%(levelname)s] Vanna: %(message)s"
    file:
      enabled: true
      level: DEBUG
      filename: "vanna.log"
      format: "%(asctime)s [%(levelname)s] [%(name)s] %(filename)s:%(lineno)d - %(message)s"
      rotation:
        enabled: true
        max_size: "20MB"
        backup_count: 5
  
  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:
    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

3.2 第二步：改造React Agent模块

3.2.1 删除独立日志管理器

# 删除独立日志文件
rm react_agent/logger.py

3.2.2 修改React Agent模块代码

react_agent/api.py

# 替换现有的日志导入
from core.logging import get_app_logger

# 初始化日志
logger = get_app_logger("ReactAgentAPI")

react_agent/agent.py

# 替换现有的日志导入
from core.logging import get_app_logger

# 初始化日志
logger = get_app_logger("CustomReactAgent")

react_agent/sql_tools.py

# 替换现有的日志导入
from core.logging import get_app_logger

# 初始化日志
logger = get_app_logger("SQLTools")

3.3 第三步：改造Data Pipeline模块

3.3.1 创建统一日志接口

data_pipeline/dp_logging/init.py

"""
Data Pipeline 统一日志管理
支持API和命令行两种模式
"""

from core.logging import get_data_pipeline_logger, initialize_logging
import os

def init_data_pipeline_logging():
    """初始化data_pipeline日志系统"""
    # 确保日志系统已初始化
    initialize_logging()

def get_logger(name: str, task_id: str = None):
    """
    获取data_pipeline专用logger
    
    Args:
        name: logger名称
        task_id: 任务ID（可选，用于任务特定日志）
    
    Returns:
        配置好的logger实例
    """
    logger = get_data_pipeline_logger(name)
    
    # 如果提供了task_id，添加任务特定的文件处理器
    if task_id:
        import logging
        from pathlib import Path
        
        # 创建任务特定的日志文件
        task_log_file = Path(f"data_pipeline/training_data/{task_id}/data_pipeline.log")
        task_log_file.parent.mkdir(parents=True, exist_ok=True)
        
        # 创建任务特定的文件处理器
        task_handler = logging.FileHandler(task_log_file, encoding='utf-8')
        task_handler.setLevel(logging.DEBUG)
        
        formatter = logging.Formatter(
            '%(asctime)s [%(levelname)s] [%(name)s] %(filename)s:%(lineno)d - %(message)s',
            datefmt='%Y-%m-%d %H:%M:%S'
        )
        task_handler.setFormatter(formatter)
        
        # 添加到logger
        logger.addHandler(task_handler)
    
    return logger

3.3.2 修改Data Pipeline主要文件

data_pipeline/schema_workflow.py

# 替换现有的日志导入
from data_pipeline.dp_logging import init_data_pipeline_logging, get_logger

# 在类初始化时调用
init_data_pipeline_logging()
logger = get_logger("SchemaWorkflow", task_id)

data_pipeline/trainer/run_training.py

# 在文件开头添加
from data_pipeline.dp_logging import init_data_pipeline_logging, get_logger

# 初始化日志
init_data_pipeline_logging()
logger = get_logger("RunTraining")

# 替换所有print语句
# 原代码：print("正在检查嵌入模型连接...")
# 新代码：logger.info("正在检查嵌入模型连接...")

3.4 第四步：清理print语句

3.4.1 需要改造的文件清单

文件路径	当前状态	改造方式	优先级
`data_pipeline/task_executor.py`	print语句	替换为logger	高
`data_pipeline/config.py`	print语句	替换为logger	高
`data_pipeline/trainer/run_training.py`	print语句	替换为logger	高
`data_pipeline/validators/sql_validate_cli.py`	print语句	保留（CLI工具）	中
`data_pipeline/validators/sql_validation_example.py`	print语句	保留（示例程序）	低

3.4.2 print语句替换规则

# 错误信息 -> logger.error()
print(f"错误: {error_message}") 
# 改为：
logger.error(f"错误: {error_message}")

# 警告信息 -> logger.warning()
print(f"警告: {warning_message}")
# 改为：
logger.warning(f"警告: {warning_message}")

# 调试信息 -> logger.debug()
print(f"调试: {debug_info}")
# 改为：
logger.debug(f"调试: {debug_info}")

# 一般信息 -> logger.info()
print(f"信息: {info_message}")
# 改为：
logger.info(f"信息: {info_message}")

【补充】

3.4.3 批量扫描print语句建议

建议使用正则表达式（如print\(）或脚本工具，批量扫描全项目（排除./test、./doc和test_*.py文件）中的print语句，形成详细的待改造文件清单，确保无遗漏。

3.5 第五步：验证和测试

3.5.1 API模式测试

# 启动API服务
python unified_api.py

# 检查日志文件生成
ls -la logs/
# 应该看到：app.log, agent.log, vanna.log, data_pipeline.log, react_agent.log

# 调用API测试日志
curl -X POST http://localhost:5000/api/v0/ask_agent \
  -H "Content-Type: application/json" \
  -d '{"question": "test question", "user_id": "test_user"}'

# 检查agent.log
tail -f logs/agent.log

3.5.2 命令行模式测试

# 测试data_pipeline命令行
python data_pipeline/trainer/run_training.py

# 检查data_pipeline.log
tail -f logs/data_pipeline.log

【补充】

3.6 API入口日志初始化与写入

3.6.1 unified_api.py日志初始化

在unified_api.py文件开头，务必添加日志系统初始化代码：
```
from core.logging import initialize_logging, get_app_logger
initialize_logging()
logger = get_app_logger("App")
```
- 替换所有print和异常输出为logger调用。
- 确保API处理函数（如ask_agent）有logger.info/debug/error等调用。
- 启动unified_api.py后，logs/app.log应由该文件负责写入。
3.6.2 agent.log日志写入排查建议
- 检查agent相关模块是否用统一日志服务（如get_app_logger("Agent")）。
- 检查unified_api.py是否初始化了日志系统。
- 检查日志配置文件中agent部分是否正确。
- 若调用ask_agent API未见agent.log写入，需重点排查上述环节。
4. 改造完成标准

4.1 功能验证清单
- 启动unified_api.py时自动初始化日志系统
- 各模块日志正确写入对应的日志文件
- 日志文件自动轮转功能正常
- 控制台和文件输出格式正确
- 上下文信息（user_id, session_id）正确显示
- 错误降级到控制台功能正常
4.2 文件验证清单
- 删除react_agent/logger.py
- 删除data_pipeline/dp_logging/manager.py
- 更新所有模块的日志导入
- 替换所有print语句
- 配置文件正确更新
4.3 日志文件验证

启动服务后，logs/目录下应该包含：
- app.log - 主应用日志
- agent.log - Agent模块日志
- vanna.log - Vanna相关日志
- data_pipeline.log - 数据管道日志
- react_agent.log - React Agent日志
【补充】

4.4 logger命名规范建议
- 建议所有logger实例命名时，使用模块名或功能名作为参数，如： python logger = get_app_logger("Agent") logger = get_app_logger("Vanna") logger = get_app_logger("DataPipeline") logger = get_app_logger("ReactAgent") logger = get_app_logger("App")
便于日志聚合和后续分析。

5. 注意事项和风险控制

5.1 兼容性考虑

保留CLI工具的print输出，确保用户体验
示例程序可以保留print，便于演示
确保API和命令行两种模式都能正常工作

5.2 性能考虑

日志文件轮转避免单个文件过大
合理设置日志级别，避免过多DEBUG输出
考虑异步日志写入（如需要）

5.3 错误处理

日志目录创建失败时降级到控制台
配置文件加载失败时使用默认配置
文件写入失败时不影响主程序运行

【补充】

5.4 日志异常处理与降级机制

日志系统初始化失败时，自动降级为控制台输出，保证主程序不因日志异常而中断。
日志目录创建失败时，自动切换为当前目录或控制台输出。
配置文件加载失败时，自动使用默认配置。
文件写入失败时，日志输出降级为console，主程序继续运行。

6. 后续优化建议

6.1 短期优化（1-2周）

根据实际使用情况调整日志级别
优化日志格式，提高可读性
添加日志文件大小监控

6.2 中期优化（1-3个月）

实现结构化日志（JSON格式）
添加日志分析和统计功能
集成日志管理系统（如ELK）

6.3 长期优化（3-6个月）

实现异步日志写入
添加日志压缩和归档
实现分布式日志收集

7. 总结

通过本次改造，项目将实现：

统一管理：所有模块使用同一套日志系统
模块独立：不同模块的日志分离存储
配置灵活：通过YAML文件统一配置
易于维护：标准化的日志格式和API
高可用性：完善的错误处理和降级机制

改造完成后，项目的日志管理将更加规范、高效和易于维护。

3.日志规范化改造建议.md 14 KB パーマリンク 履歴 Raw

日志规范化改造实施方案

1. 项目概述

1.1 改造目标

1.2 当前问题分析

2. 改造方案设计

2.1 统一日志架构

2.2 模块日志分配

3. 具体实施步骤

3.1 第一步：完善配置文件

3.1.1 更新config/logging_config.yaml

3.2 第二步：改造React Agent模块

3.2.1 删除独立日志管理器

3.2.2 修改React Agent模块代码

3.3 第三步：改造Data Pipeline模块

3.3.1 创建统一日志接口

3.3.2 修改Data Pipeline主要文件

3.4 第四步：清理print语句

3.4.1 需要改造的文件清单

3.4.2 print语句替换规则

3.4.3 批量扫描print语句建议

3.5 第五步：验证和测试

3.5.1 API模式测试

3.5.2 命令行模式测试

3.6 API入口日志初始化与写入

3.6.1 unified_api.py日志初始化

3.6.2 agent.log日志写入排查建议

4. 改造完成标准

4.1 功能验证清单

4.2 文件验证清单

4.3 日志文件验证

4.4 logger命名规范建议

5. 注意事项和风险控制

5.1 兼容性考虑

5.2 性能考虑

5.3 错误处理

5.4 日志异常处理与降级机制

6. 后续优化建议

6.1 短期优化（1-2周）

6.2 中期优化（1-3个月）

6.3 长期优化（3-6个月）

7. 总结

3.日志规范化改造建议.md 14 KB

パーマリンク履歴 Raw