Python核心：Django的日志记录全方位解析

下面是一份2026年视角下 Django 日志记录全方位解析，从零基础到生产级实践，覆盖核心概念、默认行为、自定义配置、最佳实践、常见坑点、结构化日志（JSON）、第三方增强工具，以及真实生产中的决策路径。

目标读者：Django 中级开发者（已能写 CRUD），想把日志从“print 乱打”升级到“可观测、可搜索、可告警”。

1. Django 日志体系核心四件套（必须记住）

组件	对应 Python logging 中的概念	作用说明	Django 默认行为（DEBUG=False 时）
Logger	logger 对象	你代码中调用的入口（如 logger.info()）	按模块名自动创建（如 django.request）
Handler	输出目的地	决定日志写到哪里（console/file/Sentry/MQ）	console + django.server 只输出 ERROR+
Formatter	日志格式化器	控制每条日志长什么样（时间、级别、文件名等）	简单文本格式（含时间、级别、消息）
Filter	过滤器	动态决定某条日志是否真的输出	默认基本没有

Django 默认使用 Python 的 logging 模块，并提供了一个合理的默认配置（LOGGING = {} 时生效）。

2. Django 默认日志行为（DEBUG vs 非DEBUG）

环境	django 内置日志输出情况	django.request 日志（404/500）	开发时 print 替代建议
DEBUG=True	几乎所有 DEBUG+ 信息都输出到 console	详细（含 traceback）	直接用 logger.debug() 更好
DEBUG=False	只输出 ERROR+ 到 console；server 只输出 WARNING+	只输出 ERROR（500）	必须自定义配置才能看到 INFO/WARNING

生产环境常见痛点：没配置 → 看不到任何 INFO/WARNING → 问题来了只能看 500 traceback。

3. 生产级 LOGGING 配置模板（2026 推荐）

# settings.py
import os
from pathlib import Path

BASE_DIR = Path(__file__).resolve().parent.parent

LOGGING = {
    'version': 1,
    'disable_existing_loggers': False,          # 重要：False 保留 Django 默认 logger
    'formatters': {
        'verbose': {
            'format': '[{asctime}] {levelname:7} {name:30} {message}  ({filename}:{lineno})',
            'datefmt': '%Y-%m-%d %H:%M:%S',
            'style': '{',
        },
        'simple': {
            'format': '{levelname} {message}',
            'style': '{',
        },
        'json': {   # 结构化日志（推荐生产）
            '()': 'pythonjsonlogger.jsonlogger.JsonFormatter',
            'format': '%(asctime)s %(levelname)s %(name)s %(message)s %(request)s %(user)s %(pathname)s %(lineno)d',
        },
    },
    'filters': {
        'require_debug_false': {
            '()': 'django.utils.log.RequireDebugFalse',
        },
        'require_debug_true': {
            '()': 'django.utils.log.RequireDebugTrue',
        },
    },
    'handlers': {
        'console': {
            'level': 'DEBUG',
            'filters': ['require_debug_true'],   # 只在 DEBUG=True 时输出到控制台
            'class': 'logging.StreamHandler',
            'formatter': 'verbose',
        },
        'file': {
            'level': 'INFO',
            'class': 'logging.handlers.RotatingFileHandler',
            'filename': os.path.join(BASE_DIR, 'logs/app.log'),
            'maxBytes': 10 * 1024 * 1024,   # 10MB
            'backupCount': 5,
            'formatter': 'verbose',
        },
        'error_file': {
            'level': 'ERROR',
            'class': 'logging.handlers.RotatingFileHandler',
            'filename': os.path.join(BASE_DIR, 'logs/error.log'),
            'maxBytes': 10 * 1024 * 1024,
            'backupCount': 10,
            'formatter': 'verbose',
        },
        # Sentry / Logtail / Datadog 等可加在这里
    },
    'loggers': {
        '': {   # root logger
            'handlers': ['console', 'file'],
            'level': 'INFO',
            'propagate': False,
        },
        'django': {
            'handlers': ['console', 'file'],
            'level': 'INFO',
            'propagate': False,
        },
        'django.request': {   # 捕获 404/500
            'handlers': ['error_file', 'console'],
            'level': 'ERROR',
            'propagate': False,
        },
        'myapp': {   # 你的业务模块
            'handlers': ['console', 'file'],
            'level': 'DEBUG',
            'propagate': False,
        },
    },
}

关键点解释：

• '': {...} → root logger，兜底所有未配置的 logger
• django.request → 专门捕获 HTTP 异常
• require_debug_true → 开发环境多输出，生产环境少噪音
• RotatingFileHandler → 自动切分日志文件，防止磁盘爆

4. 结构化日志（JSON）生产首选（2025–2026 趋势）

安装依赖：

pip install python-json-logger
# 或更强大：pip install structlog django-structlog

配置示例（settings.py 中添加 formatter）：

'formatters': {
    'json': {
        '()': 'pythonjsonlogger.jsonlogger.JsonFormatter',
        'format': '%(asctime)s %(levelname)s %(name)s %(message)s %(pathname)s %(lineno)d %(exc_info)s %(request)s',
    },
}
'handlers': {
    'json_file': {
        'class': 'logging.handlers.RotatingFileHandler',
        'filename': 'logs/app.jsonl',
        'formatter': 'json',
    },
}

或者用 structlog + django-structlog（更推荐，上下文自动注入 request_id、user_id、ip 等）：

pip install structlog django-structlog

然后在 settings.py 中启用即可自动带上 request 上下文。

5. 代码中如何优雅打日志（最佳实践）

import logging

logger = logging.getLogger(__name__)   # 推荐！按模块名自动分层

# 不同级别使用场景
logger.debug("详细调试信息，只开发环境看")          # 开发排查
logger.info("正常业务事件：用户登录、订单创建")       # 核心业务埋点
logger.warning("可容忍异常：第三方 API 超时")         # 需要关注但不致命
logger.error("严重错误：数据库写入失败", exc_info=True)  # 带栈追踪
logger.exception("捕获异常时最推荐")   # 自动带 exc_info=True

# 带上下文（推荐 structlog 风格）
logger.info(
    "user_login",
    extra={
        "user_id": user.id,
        "ip": request.META.get("REMOTE_ADDR"),
        "method": request.method,
    }
)

什么不要 log：

• 用户密码、token、身份证号等敏感信息（即使加密也别打）
• 完整 request body（可能含敏感数据）
• 海量 debug（生产环境 DEBUG=False + INFO 级别以上）

6. 生产监控集成（2026 主流选择）

工具/平台	集成难度	推荐场景	配置方式简述
Sentry	★★☆☆☆	错误捕获 + 性能 + 日志	pip install sentry-sdk
ELK / OpenSearch	★★★★☆	自建日志中心、搜索	Filebeat → JSON logs
Datadog / New Relic	★★★☆☆	APM + 日志 + 指标一体	官方 agent 或 python 库
SigNoz / Grafana Loki	★★★★☆	开源可观测性首选	JSON + OTLP 或 Promtail
Logtail / Better Stack	★★☆☆☆	简单、便宜、好看	HTTP handler 或文件 tail

7. 常见坑 & 避坑总结

坑点	症状	正确做法
生产环境没日志	只有 500 页面看不出原因	root logger 设 INFO + file handler
日志文件不分割	一个文件几十 GB	RotatingFileHandler 或 TimedRotating
打日志阻塞主线程	高并发下响应慢	用 QueueHandler + 异步 listener
敏感信息泄露	日志里出现 token	加过滤器或自定义 formatter 脱敏
logger 名写错	业务日志没输出	统一用 logging.getLogger(__name__)
Celery / Channels 没日志	后台任务看不到日志	在 celery worker 配置相同 LOGGING

一句话总结（2026 最实用版）：

开发：DEBUG=True + console verbose
生产：INFO → JSON 文件 + Rotating + Sentry（错误） + 业务关键事件埋 INFO + 上下文（request_id/user_id/ip）
进阶：structlog/django-structlog + OpenTelemetry → 全链路可观测

需要具体场景的配置片段（Celery、DRF、异步视图、Sentry 集成、脱敏过滤器等）？告诉我你的 Django 版本和部署环境（Docker/K8s/Render/Railway 等），我给你更精准的代码。