Structured Logging for Python

Release v14.0.0dev (What’s new?).

structlog makes structured logging in Python easy by augmenting your existing logger. It allows you to split your log entries up into key/value pairs and build them incrementally without annoying boilerplate code.

It’s licensed under Apache License, version 2, available from PyPI, the source code can be found on GitHub, the documentation at http://www.structlog.org/.

structlog targets Python 2.6, 2.7, 3.3, 3.4, and PyPy with no additional dependencies for core functionality.

If you need any help, visit us on #structlog on Freenode!

The Pitch

structlog makes structured logging with incremental context building and arbitrary formatting as easy as:

>>> from structlog import get_logger
>>> log = get_logger()
>>> log = log.bind(user='anonymous', some_key=23)
>>> log = log.bind(user='hynek', another_key=42)
>>> log.info('user.logged_in', happy=True)
some_key=23 user='hynek' another_key=42 happy=True event='user.logged_in'

Please note that this example does not use standard library logging (but could so easily). The logger that’s returned by get_logger() is freely configurable and uses a simple PrintLogger by default.

For…

  • …reasons why structured logging in general and structlog in particular are the way to go, consult Why….
  • …more realistic examples, peek into Examples.
  • …getting started right away, jump straight into Getting Started.

Since structlog avoids monkey-patching and events are fully free-form, you can start using it today!

User’s Guide

Integration with Existing Systems

structlog can be used immediately with any existing logger. However it comes with special wrappers for the Python standard library and Twisted that are optimized for their respective underlying loggers and contain less magic.

Advanced Topics

Indices and tables