.. :orphan:

structlog makes `structured logging <http://journal.paul.querna.org/articles/2011/12/26/log-for-machines-in-json/>`_ easy in Python with *any* underlying logger.
It's licensed under the `Apache License, version 2 <http://choosealicense.com/licenses/apache/>`_, available from `PyPI <https://pypi.python.org/pypi/structlog/>`_, and the source code can be found on `GitHub <https://github.com/hynek/structlog>`_.

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

Motivation
----------

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.
Effectively all you'll care about it to build a context as you go (e.g. if a user logs in, you bind the user name to your current logger) and log events when they happen (i.e. the user does something log-worthy):

.. code-block:: pycon

   >>> # stdlib logging boilerplate
   >>> import logging, sys
   >>> logging.basicConfig(stream=sys.stdout, format='%(message)s')
   >>> # Now let's wrap the logger and bind some values.
   >>> from structlog import BoundLogger, KeyValueRenderer
   >>> logger = logging.getLogger('example_logger')
   >>> log = BoundLogger.wrap(logger)
   >>> log = log.bind(user='anonymous', some_key=23)
   >>> # Do some application stuff like user authentication.
   >>> # As result, we have new values to bind to our logger.
   >>> log = log.bind(user='hynek', source='http', another_key=42)
   >>> log.warning('user.logged_in', happy=True)
   some_key=23 user='hynek' source='http' another_key=42 happy=True event='user.logged_in'


This ability to bind values to a logger saves you from using conditionals, closures, or special methods to log out all relevant data.

Additionally, structlog offers you a simple but flexible way to *filter* and *modify* your log entries using so called processors once you decide to actually log an event.
The possibilities range from logging in JSON, over counting events as metrics, to dropping log entries triggered by your monitoring system.
