index.rst

Structured Logging in Python

Release v|version| (:doc:`What's new? <changelog>`).

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 :ref:`easily <standard-library-lite>`). The logger that's returned by :func:`~structlog.get_logger()` is freely :doc:`configurable <configuration>` and uses a simple :class:`~structlog.PrintLogger` by default.

For…

• …reasons why structured logging in general and structlog in particular are the way to go, consult :doc:`why`.
• …more realistic examples, peek into :doc:`examples`.
• …getting started right away, jump straight into :doc:`getting-started`.

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

User's Guide

Basics

.. toctree::
   :maxdepth: 1

   why
   getting-started
   loggers
   configuration
   thread-local
   processors
   examples

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.

.. toctree::
   :maxdepth: 2

   standard-library
   twisted
   logging-best-practices

Advanced Topics

.. toctree::
   :maxdepth: 1

   custom-wrappers
   performance

Project Information

.. toctree::
   :maxdepth: 1

   contributing
   license
   changelog

API Reference

.. toctree::
   :maxdepth: 4

   api

Indices and tables

• :ref:`genindex`
• :ref:`modindex`
• :ref:`search`