下面是一份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，兜底所有未配置的 loggerdjango.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 等），我给你更精准的代码。
