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.pyimportosfrompathlibimportPath 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 趋势）

安装依赖：

pipinstallpython-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 等）：

pipinstallstructlog django-structlog

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

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

importlogging 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 等），我给你更精准的代码。