django-structlog

项目概述

django-structlog 是一个为 Django 应用提供结构化日志（Structured Logging）的开源库，基于强大的 structlog 库构建。该项目专为企业级 Django 应用设计，提供了完整的日志追踪和上下文管理能力。

• GitHub 仓库: jrobichaud/django-structlog
• 官方文档: https://django-structlog.readthedocs.io/en/latest/
• 许可证: MIT License
• Star 数量: 497+ ⭐

解决的核心痛点

1. 分布式系统日志追踪难题

痛点: 在微服务或异步任务架构中，一个用户请求可能触发多个服务调用和后台任务，传统日志难以追踪完整的请求链路。

解决方案:

• 自动为每个请求生成唯一的 request_id
• 支持通过 HTTP Header 传递 X-Request-ID 和 X-Correlation-ID
• 将请求上下文自动传递到 Celery 异步任务中
• 所有相关日志都携带相同的追踪 ID，便于日志聚合分析

2. 传统日志格式不利于机器解析

痛点: 传统的文本日志难以被日志收集系统（如 ELK、Splunk）解析和查询。

解决方案:

• 输出结构化的 JSON 格式日志
• 每条日志都包含标准化的元数据字段
• 支持多种输出格式（JSON、Key-Value、Console）
• 便于与现代日志分析平台集成

3. 缺乏请求生命周期的完整可观测性

痛点: 难以追踪 HTTP 请求从开始到结束的完整过程，特别是异步请求和流式响应。

解决方案:

• 自动记录 request_started、request_finished、request_failed 事件
• 支持 StreamingHttpResponse 的生命周期追踪
• 支持 ASGI 异步请求的取消检测（request_cancelled）
• 自动记录响应状态码、处理时间等关键指标

4. 用户行为追踪困难

痛点: 难以将日志与具体用户关联，不利于问题排查和用户行为分析。

解决方案:

• 自动绑定已认证用户的 user_id
• 自动记录请求来源 IP 地址
• 支持自定义用户标识字段
• 与 Django Authentication 和 DRF 无缝集成

5. Celery 任务日志缺乏上下文

痛点: Celery 异步任务的日志与触发它的 Web 请求割裂，难以关联分析。

解决方案:

• 自动将 Web 请求的上下文传递到 Celery 任务
• 支持任务嵌套时的父子关系追踪
• 提供 task_id、parent_id 等任务元数据
• 支持 Celery 任务的生命周期事件记录

适用场景

✅ 强烈推荐使用的场景

1. 微服务架构应用

   • 需要跨服务追踪请求链路
   • 使用 API Gateway 或服务网格

2. 使用 Celery 的异步任务系统

   • 需要关联 Web 请求和后台任务
   • 复杂的任务依赖关系

3. 需要集中式日志管理

   • 使用 ELK、Splunk、Datadog 等日志平台
   • 需要日志聚合分析和告警

4. 高并发 Web 应用

   • 需要追踪单个用户的请求路径
   • 需要性能监控和问题诊断

5. ASGI 异步应用

   • 使用 Django 3.0+ 的异步视图
   • 需要追踪异步请求的生命周期

6. 合规性要求高的应用

   • 需要完整的审计日志
   • 需要追踪用户操作记录

⚠️ 可能不太适合的场景

1. 简单的单体应用 - 如果应用规模很小，传统日志可能已经足够
2. 性能要求极致的场景 - 结构化日志会有轻微的性能开销
3. 遗留系统改造 - 需要评估改造成本

核心功能特性

1. 请求中间件

• 自动记录所有 HTTP 请求的生命周期
• 支持同步和异步视图
• 自动绑定请求元数据（request_id, user_id, ip 等）

2. Celery 集成

• 上下文自动传递到异步任务
• 任务嵌套关系追踪
• 任务生命周期事件记录

3. Django Management Commands 支持

• 为管理命令添加 command_id 和 command_name
• 支持嵌套命令的父子关系追踪

4. 信号机制

• 提供多个 Django Signal 用于自定义日志行为
• 可以动态绑定或修改日志元数据

5. 灵活配置

• 可自定义 4XX/5XX 状态码的日志级别
• 支持禁用 IP 记录（GDPR 合规）
• 可自定义用户标识字段

重要注意事项

⚠️ 必须注意的配置要点

1. Python 和 Django 版本要求

   - Python 3.8+
   - Django 3.2+
   - structlog 21.4.0+
   

2. 必须添加到 INSTALLED_APPS

   INSTALLED_APPS = [
       # ...
       "django_structlog",
       # ...
   ]
   

3. 中间件顺序很重要

   MIDDLEWARE = [
       # ...
       'django_structlog.middlewares.RequestMiddleware',
       # 应该在其他业务中间件之前
   ]
   

4. Celery 集成的特殊要求

   • 必须使用 task_protocol v2（默认值）
   • 如果使用 JSON 序列化，上下文必须是 JSON 可序列化的
   • 需要安装 celery extra: pip install django-structlog[celery]

5. 配置 structlog 处理器

   import structlog
   
   structlog.configure(
       processors=[
           structlog.contextvars.merge_contextvars,  # 必须放在第一位
           # ... 其他处理器
       ],
       # 不要使用 context_class=structlog.threadlocal.wrap_dict(dict)
   )
   

🔒 安全和隐私注意事项

1. IP 地址记录

   • 默认会记录用户 IP，可能涉及 GDPR 合规
   • 可通过 DJANGO_STRUCTLOG_IP_LOGGING_ENABLED = False 禁用

2. 敏感信息过滤

   • 确保不要在日志中记录密码、令牌等敏感信息
   • 使用信号机制过滤敏感字段

3. 日志存储

   • JSON 日志可能包含大量元数据，注意存储空间
   • 建议配置日志轮转策略

📊 性能考虑

1. 日志级别管理

   • 生产环境建议使用 INFO 或 WARNING 级别
   • 避免在高频路径记录 DEBUG 日志

2. Celery 上下文传递

   • 避免传递过大的上下文数据
   • 使用 modify_context_before_task_publish 信号清理不必要的数据

3. 异步支持

   • 在 ASGI 模式下性能更佳
   • 支持异步视图的完整生命周期追踪

🔧 最佳实践

1. 统一日志格式

   import structlog
   
   logger = structlog.getLogger(__name__)
   logger.info("user_action", action="login", status="success")
   

2. 使用事件驱动的日志

   • 记录事件而不是消息
   • 使用结构化字段而不是字符串插值

3. 充分利用信号

   • 使用 bind_extra_request_metadata 添加业务相关元数据
   • 使用 modify_context_before_task_publish 优化 Celery 上下文

4. 监控和告警

   • 基于 request_failed 事件设置告警
   • 监控 5XX 状态码的趋势

快速开始

安装

# 基础安装
pip install django-structlog

# 带 Celery 支持
pip install django-structlog[celery]

# 带 Management Commands 支持
pip install django-structlog[commands]

基本配置

# settings.py
INSTALLED_APPS = [
    # ...
    "django_structlog",
]

MIDDLEWARE = [
    # ...
    'django_structlog.middlewares.RequestMiddleware',
]

# 可选配置
DJANGO_STRUCTLOG_CELERY_ENABLED = True  # 启用 Celery 集成
DJANGO_STRUCTLOG_COMMAND_LOGGING_ENABLED = True  # 启用命令日志

总结

django-structlog 是为现代 Django 企业应用量身打造的日志解决方案，特别适合需要完整可观测性、分布式追踪和日志分析的场景。它通过自动化的上下文管理和结构化输出，大幅降低了日志管理的复杂度，是构建可维护、可监控 Django 应用的重要工具。

更多信息:

• 📖 完整文档
• 🔍 搜索更多代码示例
• 💬 提交 Issue