structlog - Quick Reference

When to Use This Skill

Structured logging in Python
Integration with JSON logging
Context binding for request tracing

Deep Knowledge: Use mcp__documentation__fetch_docs with technology: structlog for comprehensive documentation.

Basic Setup

pip install structlog

Essential Patterns

Basic Configuration

import structlog

structlog.configure(
    processors=[
        structlog.stdlib.filter_by_level,
        structlog.stdlib.add_logger_name,
        structlog.stdlib.add_log_level,
        structlog.stdlib.PositionalArgumentsFormatter(),
        structlog.processors.TimeStamper(fmt="iso"),
        structlog.processors.StackInfoRenderer(),
        structlog.processors.format_exc_info,
        structlog.processors.UnicodeDecoder(),
        structlog.processors.JSONRenderer()
    ],
    wrapper_class=structlog.stdlib.BoundLogger,
    context_class=dict,
    logger_factory=structlog.stdlib.LoggerFactory(),
    cache_logger_on_first_use=True,
)

Basic Usage

import structlog

log = structlog.get_logger()

log.info("user_logged_in", user_id=123, ip="192.168.1.1")
log.warning("rate_limit_exceeded", endpoint="/api/users", count=100)
log.error("database_error", error="connection timeout", retry=3)

Context Binding

log = structlog.get_logger()

# Bind context for all subsequent logs
log = log.bind(request_id="abc-123", user_id=42)

log.info("processing_started")  # Includes request_id and user_id
log.info("step_completed", step=1)
log.info("processing_finished")

# New context
log = log.new(request_id="xyz-789")

FastAPI Integration

from fastapi import FastAPI, Request
import structlog

app = FastAPI()

@app.middleware("http")
async def add_request_context(request: Request, call_next):
    structlog.contextvars.clear_contextvars()
    structlog.contextvars.bind_contextvars(
        request_id=request.headers.get("X-Request-ID", str(uuid.uuid4())),
        path=request.url.path,
    )
    return await call_next(request)

Django Integration

# settings.py
LOGGING = {
    "version": 1,
    "disable_existing_loggers": False,
    "formatters": {
        "json": {
            "()": structlog.stdlib.ProcessorFormatter,
            "processor": structlog.processors.JSONRenderer(),
        },
    },
    "handlers": {
        "console": {
            "class": "logging.StreamHandler",
            "formatter": "json",
        },
    },
    "root": {
        "handlers": ["console"],
        "level": "INFO",
    },
}

Exception Logging

try:
    risky_operation()
except Exception:
    log.exception("operation_failed", operation="risky")
    # Automatically includes stack trace

When NOT to Use This Skill

Simple scripts: Standard logging module is sufficient for basic needs
Legacy codebases: Migration effort may not be worth it for small projects
Text-only log requirements: structlog is JSON-first, requires parsing
Non-Python projects: Use language-appropriate logging frameworks
Applications without centralized logging: Standard logging may be simpler

Anti-Patterns

Anti-Pattern	Why It's Bad	Solution
Using ConsoleRenderer in production	Wastes CPU, not machine-parseable	Use JSONRenderer for production
Not clearing context variables	Leaks context across requests	Use `structlog.contextvars.clear_contextvars()`
Logging large objects	Serialization overhead	Log only necessary fields or IDs
Creating new logger per request	Performance overhead	Use `logger.bind()` to add context
Missing exception logging	Loses stack traces	Use `logger.exception()` in except blocks
Not configuring processors	Incomplete/inconsistent output	Configure full processor pipeline

Quick Troubleshooting

Issue	Cause	Solution
Plain text output instead of JSON	ConsoleRenderer configured	Change to `JSONRenderer()` in processors
Context not appearing in logs	Not using context binding	Use `logger.bind()` or `contextvars`
Performance issues	Too many processors	Remove unnecessary processors, use JSONRenderer
Missing timestamps	No TimeStamper processor	Add `TimeStamper(fmt='iso')` to processors
Logs not colorized in dev	Missing dev configuration	Use `ConsoleRenderer(colors=True)` for development
Context bleeding across requests	Not clearing contextvars	Clear context at request start with middleware