日志系统配置指南

概述 ✅ 系统已完成部署

本项目采用统一的日志管理系统，支持模块化配置和多种运行模式。所有日志通过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

全局配置

version: 1

# 全局配置
global:
  base_level: INFO    # 全局基础日志级别

默认配置

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模块

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模块

  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模块

  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模块

  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模块支持双重日志机制（已全面实现）：

全局日志: 写入 logs/data_pipeline.log ✅
任务特定日志: 写入 data_pipeline/training_data/{task_id}/data_pipeline.log ✅
滚动功能: 全局日志20MB/5备份，任务日志10MB/3备份 ✅

使用方法

基础用法

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")

任务特定日志

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模式

# 在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模式：数据处理完成")

命令行模式

# 在命令行脚本中使用
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

初始化

from core.logging import initialize_logging

# 初始化日志系统（使用默认配置文件）
initialize_logging()

# 使用自定义配置文件
initialize_logging("custom_config.yaml")

获取Logger

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")

上下文管理

from core.logging import set_log_context, clear_log_context

# 设置上下文信息
set_log_context(user_id="user123", session_id="sess456")

# 清除上下文
clear_log_context()

使用示例

基本用法

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("严重错误")

上下文使用

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("用户请求处理开始")

配置自定义

创建自定义配置文件

复制 config/logging_config.yaml 为新文件
修改配置参数
使用自定义配置初始化：

from core.logging import initialize_logging
initialize_logging("config/custom_logging.yaml")

动态配置调整

from core.logging import get_logger

# 获取logger后动态调整级别
logger = get_logger("MyComponent", "app")
logger.setLevel(logging.DEBUG)

最佳实践

1. 日志级别选择

DEBUG: 详细的调试信息，仅在开发环境使用
INFO: 程序正常运行的关键信息
WARNING: 潜在问题，但不影响程序运行
ERROR: 错误情况，但程序可以继续运行
CRITICAL: 严重错误，程序可能无法继续运行

2. 消息格式规范

# 推荐格式
logger.info("用户登录成功", extra={"user_id": "123"})
logger.error("数据库连接失败", extra={"error": str(e)})

# 避免格式
logger.info("用户123登录成功")  # 不易于查询和分析

3. 异常处理

try:
    # 业务逻辑
    result = process_data()
    logger.info("数据处理成功")
except Exception as e:
    logger.error(f"数据处理失败: {e}", exc_info=True)
    raise

4. 性能考虑

# 对于频繁调用的DEBUG日志，使用条件判断
if logger.isEnabledFor(logging.DEBUG):
    logger.debug(f"复杂计算结果: {expensive_operation()}")

故障排除

常见问题

1. 日志文件不生成

检查 logs/ 目录权限
确认配置文件路径正确
验证 initialize_logging() 已调用

2. 控制台无输出

检查配置文件中 console.enabled 设置
确认日志级别设置正确

3. 日志格式异常

检查格式化字符串语法
确认上下文变量已正确设置

调试方法

启用调试模式

import logging
logging.basicConfig(level=logging.DEBUG)

from core.logging import initialize_logging
initialize_logging()

查看配置加载情况

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日
系统状态: 生产就绪，所有功能正常运行

日志系统配置指南.md 12 KB 文件歷史 原始文件