ai-chat-ui/docs/LOGGING_SYSTEM.md

统一日志管理系统说明

功能特性

1. 多级别日志支持：DEBUG, INFO, WARNING, ERROR, CRITICAL
2. 结构化日志：支持JSON格式的结构化日志输出
3. 文件轮转：自动按日期和大小分割日志文件
4. 系统监控：记录系统状态和性能指标
5. 请求追踪：记录API请求和响应信息
6. 错误追踪：详细记录异常和错误信息

使用方法

1. 基本日志记录

from utils.logger import log_debug, log_info, log_warning, log_error, log_critical

log_info("服务启动成功")
log_warning("内存使用率较高")
log_error("API请求失败")

2. 结构化日志

from utils.logger import log_structured

log_structured(
    "info",
    "用户登录成功",
    user_id="12345",
    ip_address="192.168.1.100",
    timestamp=datetime.now().isoformat()
)

3. 请求日志

from utils.logger import log_request_info, log_response_info

log_request_info("POST", "/api/chat", "192.168.1.100", "Mozilla/5.0...")
log_response_info(200, 150.5, "/api/chat", "POST", "192.168.1.100")

4. 错误详情记录

from utils.logger import log_error_detail

try:
    # 可能出错的代码
    pass
except Exception as e:
    log_error_detail(
        type(e).__name__,
        str(e),
        str(e.__traceback__),
        context={"user_id": "123", "action": "chat_request"}
    )

5. 对话交互记录

from utils.logger import log_chat_interaction

log_chat_interaction(
    user_input="你好，请帮我分析这张图片",
    ai_response="这张图片显示了一座山和一片湖泊",
    model="qwen-vl-plus",
    conversation_id="conv_abc123"
)

6. 系统状态记录

from utils.logger import log_system_status

log_system_status(
    status="healthy",
    uptime=3600.5,
    cpu_usage=45.2,
    memory_usage=60.8,
    disk_usage=75.1
)

配置

环境变量配置

环境变量	默认值	说明
LOG_LEVEL	INFO	日志级别
LOG_DIR	logs	日志文件目录
LOG_MAX_BYTES	10485760	单个日志文件最大大小
LOG_BACKUP_COUNT	5	保留的备份日志数量

配置文件

创建 logging.conf 文件来配置日志系统：

LOG_LEVEL=INFO
LOG_DIR=logs
LOG_MAX_BYTES=10485760
LOG_BACKUP_COUNT=5

日志文件组织

• 日志文件按日期分割：ai-chat-api_2026-03-03.log
• 自动轮转，当日志文件达到指定大小时创建新文件
• 保留最近5个日志文件，旧文件会被自动删除
• 日志文件存放在 logs/ 目录下

集成到现有代码

在你的 FastAPI 应用中：

from utils.logger import setup_global_logger

# 初始化日志系统
logger = setup_global_logger()

@app.middleware("http")
async def logging_middleware(request, call_next):
    start_time = time.time()

    # 记录请求
    logger.info(f"Request: {request.method} {request.url.path}")

    response = await call_next(request)

    # 记录响应
    process_time = time.time() - start_time
    logger.info(f"Response: {response.status_code} in {process_time:.2f}s")

    return response

注意事项

1. 使用结构化日志便于日志分析和查询
2. 避免在日志中记录敏感信息（如密码、token等）
3. 适当使用日志级别，避免过度记录DEBUG信息
4. 定期清理旧的日志文件，防止磁盘空间不足