structlog-structured-logging

structlog — Structured Logging for Python

structlog turns log entries into dictionaries processed through a chain of functions, giving you structured output (JSON, logfmt, pretty console) without sacrificing performance. It has been in production since 2013 and supports threads, asyncio, and greenlets.

Why structlog over stdlib logging

stdlib logging	structlog
String messages, hard to parse	Key-value dictionaries, machine-readable
Global mutable state	Immutable bound loggers, safe to pass around
Complex handler/formatter hierarchy	Simple processor chain of plain callables
No built-in context propagation	contextvars integration out of the box
Verbose boilerplate per file	One get_logger() call per file

Installation

pip install structlog
# For pretty dev exceptions (recommended):
pip install structlog rich
# Windows only (for colors):
pip install structlog rich colorama

Core Concepts

Event dict

Every log call builds a dictionary (event_dict). Context bound via bind() is merged with the kwargs of the log call.

Processor chain

A list of callables, each with signature (logger, method_name, event_dict) -> event_dict. They run in order; the last one must return a string/bytes (the renderer).

Bound logger

The object returned by get_logger(). It's immutable — calling bind() returns a new logger. Use contextvars for mutable global context.

---

Basic Usage

import structlog

log = structlog.get_logger()

# Simple log
log.info("user_login", user_id=42, ip="1.2.3.4")
# → 2024-01-01 12:00:00 [info     ] user_login   user_id=42 ip=1.2.3.4

# Bind context to a local logger
log = log.bind(request_id="abc-123", user_id=42)
log.info("processing_started")
log.warning("slow_query", duration_ms=1500)
# Both entries include request_id and user_id automatically

# Unbind a key
log = log.unbind("user_id")

# Replace all context
log = log.new(request_id="new-456")