# 后端日志模块说明

本文档对应页面/功能模块：全平台通用能力、系统设置、审计中心、任务详情、训练任务日志、运维监控。

## 设计目标

- 后端服务统一使用 `backend/app/core/logging.py` 初始化日志。
- 日志文件按日期命名，单个文件超过 20MB 自动滚动。
- 日志只保留最近 10 天，过期文件自动清理。
- 业务日志使用 JSON Lines 格式，便于 Filebeat、Vector、Logstash、ELK、OpenSearch 等日志平台采集。
- `ERROR` 及以上日志独立写入错误日志文件，便于告警与问题定位。
- 日志字段必须包含代码文件、行号、函数、日志内容、请求 ID、进程和线程信息。

## 文件命名

默认日志目录由 `LOG_DIR` 控制，本地默认是 `./logs`。

```text
logs/
  backend-2026-07-16.log      # INFO/ERROR 等全部应用日志，JSON Lines
  backend-2026-07-16.1.log    # 当天主日志超过 20MB 后滚动产生
  error-2026-07-16.log        # ERROR/CRITICAL 错误日志，JSON Lines
  error-2026-07-16.1.log      # 当天错误日志超过 20MB 后滚动产生
```

## 环境变量

```env
LOG_LEVEL=INFO
LOG_DIR=./logs
LOG_FILE_PREFIX=backend
LOG_ERROR_FILE_PREFIX=error
LOG_MAX_BYTES=20971520
LOG_RETENTION_DAYS=10
```

## JSON 字段

每一行都是一个完整 JSON 对象。

```json
{
  "@timestamp": "2026-07-16T13:20:10.123",
  "level": "INFO",
  "logger": "app.access",
  "message": "request completed method=GET path=/modelTF/health status_code=200 duration_ms=3.12 client=127.0.0.1",
  "module": "logging",
  "function": "request_logging_middleware",
  "file": "D:\\AI\\codex-code\\YG_FT\\backend\\app\\core\\logging.py",
  "line": 169,
  "process": 1234,
  "thread": 5678,
  "thread_name": "MainThread",
  "request_id": "6f9d1c3c-8be0-4c8d-a5b2-18f9d41f9a0c"
}
```

异常日志会额外包含：

```json
{
  "exception": "Traceback ..."
}
```

## 使用方式

业务代码中不要直接 `print`，统一使用：

```python
from app.core.logging import get_logger

logger = get_logger(__name__)

logger.info("dataset uploaded dataset_id=%s", dataset_id)
logger.warning("gpu queue is busy project_id=%s", project_id)
logger.exception("training job failed job_id=%s", job_id)
```

`logger.exception(...)` 只能在 `except` 代码块中使用，它会自动写入堆栈信息，并同时进入主日志和错误日志。

## FastAPI 接入

应用入口 `backend/app/main.py` 已完成接入：

```python
settings = get_settings()
configure_logging(settings)
setup_request_logging(app)
```

请求日志会自动生成或透传 `X-Request-ID`，并在响应头中返回同一个请求 ID，方便前端、后端、算力服务、日志平台串联排障。

## ELK/日志平台采集建议

- 采集路径：`/app/logs/*.log` 或生产环境挂载后的日志目录。
- 解析方式：按行读取，每行作为 JSON 文档解析。
- 索引建议：
  - 主日志：`yg-ft-backend-*`
  - 错误日志：`yg-ft-backend-error-*`
- 推荐保留字段：`@timestamp`、`level`、`logger`、`message`、`file`、`line`、`function`、`request_id`、`tenant_id`、`project_id`、`job_id`。
- 业务开发后续应在关键模块日志中补充 `tenant_id`、`project_id`、`job_id` 等上下文字段，便于企业审计和问题定位。

## 注意事项

- 当前日志落本地磁盘，生产环境建议把日志目录挂载到独立数据盘。
- 日志文件保留 10 天是应用侧兜底策略，企业侧长期留存应由 ELK、对象存储或归档服务承担。
- 敏感字段如 token、密码、密钥、原始用户数据内容不得写入日志。
- 算力节点和应用节点分开部署时，建议两侧都采用 JSON Lines 格式，并使用统一 `request_id/job_id` 贯穿链路。