后端日志模块说明

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

设计目标

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

文件命名

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

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 后滚动产生

环境变量

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 对象。

{
  "@timestamp": "2026-07-16T13:20:10.123",
  "level": "INFO",
  "logger": "app.access",
  "message": "request completed method=GET path=/api/v1/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"
}

异常日志会额外包含：

{
  "exception": "Traceback ..."
}

使用方式

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

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 已完成接入：

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 贯穿链路。

3.7 KiB Raw Blame History Unescape Escape