# 日志系统使用文档

## 概述

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

## 目录结构

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

## 快速开始

### 1. 安装依赖

```bash
pip install PyYAML
```

### 2. 初始化日志系统

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

```python
from app.logger import setup_logging

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

### 3. 在模块中使用日志

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

```python
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 接口查询错误详情：

```http
GET /api/errors/{error_id}
```

响应示例：

```json
{
  "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`

### 基本配置

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

### 日志格式

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

### 日志处理器

```yaml
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
```

### 日志记录器配置

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

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

## 环境配置

### 开发环境

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

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

### 生产环境

建议修改配置：

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

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

通过环境变量覆盖配置：

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

# 设置日志级别
export LOG_LEVEL=INFO
```

## 最佳实践

### 1. 模块级日志记录器

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

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

### 2. 结构化日志

添加额外上下文信息：

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

### 3. 异常处理

始终记录异常堆栈：

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

### 4. 敏感信息处理

避免记录敏感信息：

```python
# 不要这样做
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的响应：

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

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

```http
GET /api/errors/ERR-123456789
```

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



## 常见问题

### Q1: 日志文件未创建

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

### Q2: 日志级别不生效

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

### Q3: 错误ID查询失败

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

------

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