Structlog Skill
Quick Start
import structlog
# Basic usage
log = structlog.get_logger()
log.info("hello, %s!", "world", key="value", more_than_strings=[1, 2, 3])
Common Patterns
Basic Configuration
import structlog
structlog.configure(
processors=[
structlog.contextvars.merge_contextvars,
structlog.processors.add_log_level,
structlog.processors.StackInfoRenderer(),
structlog.dev.set_exc_info,
structlog.processors.TimeStamper(fmt="%Y-%m-%d %H:%M:%S", utc=False),
structlog.dev.ConsoleRenderer()
],
wrapper_class=structlog.make_filtering_bound_logger(logging.NOTSET),
context_class=dict,
logger_factory=structlog.PrintLoggerFactory(),
cache_logger_on_first_use=False
)
JSON Logging
import structlog
# Configure for JSON output
structlog.configure(
processors=[structlog.processors.JSONRenderer()]
)
log = structlog.get_logger()
log.info("Processing request", request_id="req-123", user_id=456)
# Output: {"event": "Processing request", "request_id": "req-123", "user_id": 456}
Standard Library Integration
import logging
import structlog
# Configure standard logging
logging.basicConfig(
format="%(message)s",
stream=sys.stdout,
level=logging.INFO
)
# Configure structlog to use standard library
structlog.configure(
processors=[
structlog.stdlib.filter_by_level,
structlog.stdlib.add_logger_name,
structlog.stdlib.add_log_level,
structlog.stdlib.PositionalArgumentsFormatter(),
structlog.processors.StackInfoRenderer(),
structlog.processors.format_exc_info,
structlog.stdlib.render_to_log_kwargs,
],
context_class=dict,
logger_factory=structlog.stdlib.LoggerFactory(),
wrapper_class=structlog.stdlib.BoundLogger,
cache_logger_on_first_use=True,
)
Context Binding
import structlog
log = structlog.get_logger()
# Bind context that persists across log calls
request_log = log.bind(request_id="req-789", user="alice")
request_log.info("Processing started")
request_log.info("Database query executed", query="SELECT * FROM users")
request_log.info("Processing completed")
# Output includes request_id and user in all log entries
Custom Processors
import time
def add_custom_context(logger, log_method, event_dict):
"""Add custom context to every log entry"""
event_dict["custom_field"] = "custom_value"
event_dict["timestamp"] = time.time()
return event_dict
structlog.configure(
processors=[
add_custom_context,
structlog.processors.JSONRenderer()
]
)
Exception Handling
import structlog
structlog.configure(
processors=[
structlog.processors.dict_tracebacks,
structlog.processors.JSONRenderer(),
],
)
log = structlog.get_logger()
try:
1 / 0
except ZeroDivisionError:
log.exception("Division error occurred")
Testing with Structlog
import pytest
import structlog
from structlog.testing import LogCapture
@pytest.fixture
def log_output():
return LogCapture()
@pytest.fixture(autouse=True)
def configure_structlog(log_output):
structlog.configure(
processors=[log_output]
)
def test_logging(log_output):
log = structlog.get_logger()
log.info("test message", key="value")
assert len(log_output.entries) == 1
assert log_output.entries[0]["event"] == "test message"
assert log_output.entries[0]["key"] == "value"
Performance-Optimized 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()
],
context_class=dict,
logger_factory=structlog.stdlib.LoggerFactory(),
wrapper_class=structlog.stdlib.BoundLogger,
cache_logger_on_first_use=True,
)
Advanced Console Output
import logging.config
import structlog
timestamper = structlog.processors.TimeStamper(fmt="%Y-%m-%d %H:%M:%S")
pre_chain = [
structlog.stdlib.add_log_level,
structlog.stdlib.ExtraAdder(),
timestamper,
]
logging.config.dictConfig({
"version": 1,
"disable_existing_loggers": False,
"formatters": {
"plain": {
"()": structlog.stdlib.ProcessorFormatter,
"processors": [
structlog.stdlib.ProcessorFormatter.remove_processors_meta,
structlog.dev.ConsoleRenderer(colors=False),
],
"foreign_pre_chain": pre_chain,
},
"colored": {
"()": structlog.stdlib.ProcessorFormatter,
"processors": [
structlog.stdlib.ProcessorFormatter.remove_processors_meta,
structlog.dev.ConsoleRenderer(colors=True),
],
"foreign_pre_chain": pre_chain,
},
},
"handlers": {
"default": {
"level": "DEBUG",
"class": "logging.StreamHandler",
"formatter": "colored",
},
"file": {
"level": "DEBUG",
"class": "logging.handlers.WatchedFileHandler",
"filename": "app.log",
"formatter": "plain",
},
},
"loggers": {
"": {
"handlers": ["default", "file"],
"level": "DEBUG",
}
}
})
Key Features
- Structured Logging: Log events as dictionaries with context
- Multiple Output Formats: Console, JSON, logfmt, and custom renderers
- Context Binding: Persistent context across log calls
- Standard Library Integration: Works seamlessly with Python's logging module
- Performance: Optimized for high-throughput applications
- Testing Support: Built-in testing utilities
- Exception Handling: Enhanced exception formatting and rendering
- Custom Processors: Flexible pipeline for log processing
Best Practices
- Configure Once: Set up structlog configuration at application startup
- Use Context: Bind relevant context (request_id, user_id) early in request handling
- Choose Right Renderer: Use ConsoleRenderer for development, JSONRenderer for production
- Test Logging: Use LogCapture for unit testing logging behavior
- Performance: Cache loggers and use efficient processors for production
Converted and distributed by TomeVault — claim your Tome and manage your conversions.