# 日志系统配置指南

## 概述 ✅ **系统已完成部署**

本项目采用统一的日志管理系统，支持模块化配置和多种运行模式。所有日志通过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日  
**系统状态**: 生产就绪，所有功能正常运行