Structured Logging in Python

Release v0.3.2 (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

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

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

Why You Want Structured Logging

I believe the widespread use of format strings in logging is based on two presumptions:

  • The first level consumer of a log message is a human.
  • The programmer knows what information is needed to debug an issue.

I believe these presumptions are no longer correct in server side software.

Paul Querna

Structured logging means that you don’t write hard-to-parse and hard-to-keep-consistent prose in your logs but that you log events that happen in a context instead.

Why structlog?

Because it’s easy and you don’t have to replace your underlying logger – you just add structure to your log entries and format them to strings before they hit your real loggers.

structlog supports you with building your context as you go (e.g. if a user logs in, you bind their user name to your current logger) and log events when they happen (i.e. the user does something log-worthy):

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

This ability to bind key/values pairs to a logger frees you from using conditionals, closures, or boilerplate methods to log out all relevant data.

Additionally, structlog offers you a flexible way to filter and modify your log entries using so called processors before the entry is passed to your real logger. The possibilities include logging in JSON, adding arbitrary meta data like timestamps, counting events as metrics, or dropping log entries caused by your monitoring system. structlog is also flexible enough to allow transparent thread local storage for your context if you don’t like the idea of local bindings as in the example above.

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

Intrigued? Get started now or have a look at more realistic examples and be completely convinced!

Indices and tables