110 lines
3.7 KiB
Markdown
110 lines
3.7 KiB
Markdown
# 后端日志模块说明
|
||
|
||
本文档对应页面/功能模块：全平台通用能力、系统设置、审计中心、任务详情、训练任务日志、运维监控。
|
||
|
||
## 设计目标
|
||
|
||
- 后端服务统一使用 `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` 贯穿链路。
|