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 |
claude-dev-suite