AcidMap/app/log

日志系统使用文档

概述

本日志系统为 FastAPI 项目提供统一的日志记录和查询功能，支持多级别日志记录、日志轮转、错误详情查询等功能。系统基于 Python 标准库 logging 模块构建，通过 YAML 配置文件实现灵活配置。

目录结构

project/
├── app/
│   ├── main.py             # 应用入口
│   ├── logger.py           # 日志核心模块
│   ├── log/
│   │   └── logging_config.yaml  # 日志配置文件
│   └── api/
│       └── errors.py       # 错误查询接口
├── logs/                   # 日志目录
│   ├── app.log             # 普通日志
│   └── errors.log          # 错误日志
└── requirements.txt

快速开始

1. 安装依赖

pip install PyYAML

2. 初始化日志系统

在应用入口文件 (main.py) 中初始化日志：

from app.logger import setup_logging

# 在创建 FastAPI 应用前初始化日志
setup_logging()

3. 在模块中使用日志

在任何模块中获取日志记录器：

from app.logger import get_logger

# 获取当前模块的日志记录器
logger = get_logger(__name__)

# 记录不同级别的日志
logger.debug("调试信息")
logger.info("常规信息")
logger.warning("警告信息")
logger.error("错误信息")
logger.critical("严重错误")

# 记录异常堆栈
try:
    # 可能出错的代码
except Exception as e:
    logger.exception("操作失败", exc_info=True)

核心功能

1. 日志记录级别

系统支持五种标准日志级别：

级别	描述	使用场景
DEBUG	调试信息	开发环境详细日志
INFO	常规信息	操作记录、状态变更
WARNING	警告信息	非预期但可恢复的问题
ERROR	错误信息	操作失败、异常情况
CRITICAL	严重错误	系统崩溃级别错误

2. 日志输出目标

• 控制台输出：开发环境默认输出到控制台

文件输出

：

• app.log：所有级别日志
• errors.log：仅错误级别日志（ERROR+）

3. 日志轮转

• 单个日志文件最大 10MB
• 保留最近 5 个普通日志文件
• 保留最近 10 个错误日志文件

4. 错误详情查询

提供 RESTful 接口查询错误详情：

GET /api/errors/{error_id}

响应示例：

{
  "id": "ERR-123456789",
  "timestamp": "2025-08-15 10:30:22",
  "level": "ERROR",
  "message": "数据库连接失败",
  "traceback": [
    "Traceback (most recent call last):",
    "  File \"app/main.py\", line 42, in get_data",
    "    db.connect()",
    "ConnectionError: 无法连接数据库"
  ],
  "related_entries": []
}

配置说明

配置文件：log/logging_config.yaml

基本配置

version: 1
disable_existing_loggers: False  # 不禁用现有日志记录器

日志格式

formatters:
  standard:
    format: "[%(asctime)s] [%(levelname)s] [%(name)s:%(lineno)d] - %(message)s"
    datefmt: "%Y-%m-%d %H:%M:%S"

日志处理器

handlers:
  console:  # 控制台输出
    class: logging.StreamHandler
    level: INFO
    formatter: standard
    stream: ext://sys.stdout

  file:  # 普通日志文件
    class: logging.handlers.RotatingFileHandler
    level: DEBUG
    formatter: standard
    filename: logs/app.log
    maxBytes: 10485760  # 10MB
    backupCount: 5
    encoding: utf8

  error_file:  # 错误日志文件
    class: logging.handlers.RotatingFileHandler
    level: ERROR
    formatter: standard
    filename: logs/errors.log
    maxBytes: 10485760
    backupCount: 10
    encoding: utf8

日志记录器配置

loggers:
  app:  # 应用特定日志记录器
    level: DEBUG
    handlers: [console, file, error_file]
    propagate: False  # 不传播到根记录器

root:  # 根日志记录器
  level: DEBUG
  handlers: [console, file, error_file]

环境配置

开发环境

默认配置适用于开发环境：

• 日志级别：DEBUG
• 输出到控制台和文件

生产环境

建议修改配置：

# 在 logging_config.yaml 中修改
handlers:
  console:
    level: WARNING  # 生产环境减少控制台输出

loggers:
  app:
    level: INFO  # 生产环境减少日志量

通过环境变量覆盖配置：

# 设置日志目录
export LOG_DIR=/var/log/myapp

# 设置日志级别
export LOG_LEVEL=INFO

最佳实践

1. 模块级日志记录器

在每个模块顶部创建日志记录器：

from app.logger import get_logger
logger = get_logger(__name__)

2. 结构化日志

添加额外上下文信息：

logger.info("用户登录", extra={
    "user_id": user.id,
    "ip": request.client.host
})

3. 异常处理

始终记录异常堆栈：

try:
    # 业务代码
except Exception as e:
    logger.error("操作失败", exc_info=True)

4. 敏感信息处理

避免记录敏感信息：

# 不要这样做
logger.info(f"用户登录: username={username}, password={password}")

# 应该这样做
logger.info("用户登录", extra={"username": username})

错误查询接口

接口说明

• 路径: /api/errors/{error_id}
• 方法: GET
• 参数:
  • error_id: 错误ID（由系统生成）
• 响应:
  • 200: 成功返回错误详情
  • 404: 未找到错误ID
  • 500: 服务器内部错误

使用流程

1. 当发生错误时，系统返回包含错误ID的响应：

   {
   "code": "ERR-123456789",
   "message": "Internal server error",
   "documentation": "/api/errors/ERR-123456789"
   }
   

2. 使用错误ID查询详情：

   GET /api/errors/ERR-123456789
   

3. 分析返回的堆栈跟踪信息定位问题

常见问题

Q1: 日志文件未创建

• 检查磁盘空间
• 确认配置文件路径正确

Q2: 日志级别不生效

• 检查环境变量覆盖
• 确认配置文件中级别设置正确
• 重启应用使配置生效

Q3: 错误ID查询失败

• 确认错误日志文件存在
• 检查日志文件是否包含该错误ID
• 确认日志格式符合预期

---

本日志系统为应用提供全面的日志管理解决方案，帮助开发团队快速定位和解决问题。通过合理配置和使用，可大幅提高系统可观测性和故障排查效率。