structlog Package

structlog Package

structlog.get_logger(**initial_values)

Convenience function that returns a logger according to configuration.

>>> from structlog import get_logger
>>> log = get_logger(y=23)
>>> log.msg('hello', x=42)
y=23 x=42 event='hello'
Parameters:initial_values – Values that are used to pre-populate your contexts.
Return type:A proxy that creates a correctly configured bound logger when necessary.

See Configuration for details.

If you prefer CamelCase, there’s an alias for your reading pleasure: structlog.getLogger().


structlog.getLogger(**initial_values)

CamelCase alias for structlog.get_logger().

This function is supposed to be in every source file – we don’t want it to stick out like a sore thumb in frameworks like Twisted or Zope.


structlog.wrap_logger(logger, processors=None, wrapper_class=None, context_class=None, cache_logger_on_first_use=None, **initial_values)

Create a new bound logger for an arbitrary logger.

Default values for processors, wrapper_class, and context_class can be set using configure().

If you set an attribute here, configure() calls have no effect for the respective attribute.

In other words: selective overwriting of the defaults while keeping some is possible.

Parameters:initial_values – Values that are used to pre-populate your contexts.
Return type:A proxy that creates a correctly configured bound logger when necessary.

See configure() for the meaning of the rest of the arguments.


structlog.configure(processors=None, wrapper_class=None, context_class=None, logger_factory=None, cache_logger_on_first_use=None)

Configures the global defaults.

They are used if wrap_logger() has been called without arguments.

Also sets the global class attribute is_configured to True on first call. Can be called several times, keeping an argument at None leaves is unchanged from the current setting.

Use reset_defaults() to undo your changes.

Parameters:
  • processors (list) – List of processors.
  • wrapper_class (type) –

    Class to use for wrapping loggers instead of structlog.BoundLogger.

    See Python Standard Library, Twisted, and Custom Wrappers.

  • context_class – Class to be used for internal dictionary.
  • logger_factory (callable) –
  • cache_logger_on_first_use (bool) –

    wrap_logger doesn’t return an actual wrapped logger but a proxy that assembles one when it’s first used. If this option is set to True, this assembled logger is cached.

    See Performance.

    New in version 0.3.0.


structlog.configure_once(*args, **kw)

Configures iff structlog isn’t configured yet.

It does not matter whether is was configured using configure() or configure_once() before.

Raises a RuntimeWarning if repeated configuration is attempted.


structlog.reset_defaults()

Resets global default values to builtins.

That means [format_exc_info(), KeyValueRenderer] for processors, BoundLogger for wrapper_class, OrderedDict for context_class, PrintLogger for logger_factory, and False for cache_logger_on_first_use.

Also sets the global class attribute is_configured to True.


class structlog.BoundLogger(logger, processors, context)

A generic BoundLogger that can wrap anything.

Every unknown method will be passed to the wrapped logger. If that’s too much magic for you, try structlog.twisted.BoundLogger or :class:`structlog.twisted.BoundLogger which also take advantage of knowing the wrapped class which generally results in better performance.

Not intended to be instantiated by yourself. See wrap_logger() and get_logger().

new(**new_values)

Clear context and binds initial_values using bind().

Only necessary with dict implementations that keep global state like those wrapped by structlog.threadlocal.wrap_dict() when threads are re-used.

Return type:self.__class__
bind(**new_values)

Return a new logger with new_values added to the existing ones.

Return type:self.__class__
unbind(*keys)

Return a new logger with keys removed from the context.

Raises KeyError:
 If the key is not part of the context.
Return type:self.__class__

class structlog.PrintLogger(file=None)

Prints events into a file.

Parameters:file (file) – File to print to. (default: stdout)
>>> from structlog import PrintLogger
>>> PrintLogger().msg('hello')
hello

Useful if you just capture your stdout with tools like runit or if you forward your stderr to syslog.

Also very useful for testing and examples since logging is sometimes finicky in doctests.

msg(message)

Print message.

err(message)

Print message.

debug(message)

Print message.

info(message)

Print message.

warning(message)

Print message.

error(message)

Print message.

critical(message)

Print message.

log(message)

Print message.


class structlog.ReturnLogger

Returns the string that it’s called with.

>>> from structlog import ReturnLogger
>>> ReturnLogger().msg('hello')
'hello'
>>> ReturnLogger().msg('hello', when='again')
(('hello',), {'when': 'again'})

Useful for unit tests.

Changed in version 0.3.0: Allow for arbitrary arguments and keyword arguments to be passed in.

msg(*args, **kw)

Return tuple of args, kw or just args[0] if only one arg passed

err(*args, **kw)

Return tuple of args, kw or just args[0] if only one arg passed

debug(*args, **kw)

Return tuple of args, kw or just args[0] if only one arg passed

info(*args, **kw)

Return tuple of args, kw or just args[0] if only one arg passed

warning(*args, **kw)

Return tuple of args, kw or just args[0] if only one arg passed

error(*args, **kw)

Return tuple of args, kw or just args[0] if only one arg passed

critical(*args, **kw)

Return tuple of args, kw or just args[0] if only one arg passed

log(*args, **kw)

Return tuple of args, kw or just args[0] if only one arg passed


exception structlog.DropEvent

If raised by an processor, the event gets silently dropped.

Derives from BaseException because it’s technically not an error.


class structlog.BoundLoggerBase(logger, processors, context)

Immutable context carrier.

Doesn’t do any actual logging; examples for useful subclasses are:

See also Custom Wrappers.

new(**new_values)

Clear context and binds initial_values using bind().

Only necessary with dict implementations that keep global state like those wrapped by structlog.threadlocal.wrap_dict() when threads are re-used.

Return type:self.__class__
bind(**new_values)

Return a new logger with new_values added to the existing ones.

Return type:self.__class__
unbind(*keys)

Return a new logger with keys removed from the context.

Raises KeyError:
 If the key is not part of the context.
Return type:self.__class__
_logger = None

Wrapped logger.

Note

Despite underscore available read-only to custom wrapper classes.

See also Custom Wrappers.

_process_event(method_name, event, event_kw)

Combines creates an event_dict and runs the chain.

Call it to combine your event and context into an event_dict and process using the processor chain.

Parameters:
  • method_name (str) – The name of the logger method. Is passed into the processors.
  • event – The event – usually the first positional argument to a logger.
  • event_kw – Additional event keywords. For example if someone calls log.msg('foo', bar=42), event would to be 'foo' and event_kw {'bar': 42}.
Raises :

structlog.DropEvent if log entry should be dropped.

Return type:

tuple of (*args, **kw)

Note

Despite underscore available to custom wrapper classes.

See also Custom Wrappers.

_proxy_to_logger(method_name, event=None, **event_kw)

Run processor chain on event & call method_name on wrapped logger.

DRY convenience method that runs _process_event(), takes care of handling structlog.DropEvent, and finally calls method_name on _logger with the result.

Parameters:
  • method_name (str) – The name of the method that’s going to get called. Technically it should be identical to the method the user called because it also get passed into processors.
  • event – The event – usually the first positional argument to a logger.
  • event_kw – Additional event keywords. For example if someone calls log.msg('foo', bar=42), event would to be 'foo' and event_kw {'bar': 42}.

Note

Despite underscore available to custom wrapper classes.

See also Custom Wrappers.


threadlocal Module

Primitives to keep context global but thread (and greenlet) local.


structlog.threadlocal.wrap_dict(dict_class)[source]

Wrap a dict-like class and return the resulting class.

The wrapped class and used to keep global in the current thread.

Parameters:dict_class (type) – Class used for keeping context.
Return type:type

structlog.threadlocal.tmp_bind(logger, **tmp_values)[source]

Bind tmp_values to logger & memorize current state. Rewind afterwards.

>>> from structlog import wrap_logger, PrintLogger
>>> from structlog.threadlocal import tmp_bind, wrap_dict
>>> logger = wrap_logger(PrintLogger(),  context_class=wrap_dict(dict))
>>> with tmp_bind(logger, x=5) as tmp_logger:
...     logger = logger.bind(y=3)
...     tmp_logger.msg('event')
y=3 x=5 event='event'
>>> logger.msg('event')
event='event'

structlog.threadlocal.as_immutable(logger)[source]

Extract the context from a thread local logger into an immutable logger.

Parameters:logger (BoundLogger) – A logger with possibly thread local state.
Return type:BoundLogger with an immutable context.

processors Module

Processors useful regardless of the logging framework.


class structlog.processors.JSONRenderer(**dumps_kw)[source]

Render the event_dict using json.dumps(event_dict, **json_kw).

Parameters:json_kw – Are passed unmodified to json.dumps().
>>> from structlog.processors import JSONRenderer
>>> JSONRenderer(sort_keys=True)(None, None, {'a': 42, 'b': [1, 2, 3]})
'{"a": 42, "b": [1, 2, 3]}'

Bound objects are attempted to be serialize using a __structlog__` method.  If none is defined, ``repr() is used:

>>> class C1(object):
...     def __structlog__(self):
...         return ['C1!']
...     def __repr__(self):
...         return '__structlog__ took precedence'
>>> class C2(object):
...     def __repr__(self):
...         return 'No __structlog__, so this is used.'
>>> from structlog.processors import JSONRenderer
>>> JSONRenderer(sort_keys=True)(None, None, {'c1': C1(), 'c2': C2()})
'{"c1": ["C1!"], "c2": "No __structlog__, so this is used."}'

Please note that additionally to strings, you can also return any type the standard library JSON module knows about – like in this example a list.

Changed in version 0.2.0: Added support for __structlog__ serialization method.


class structlog.processors.KeyValueRenderer(sort_keys=False, key_order=None)[source]

Render event_dict as a list of Key=repr(Value) pairs.

Parameters:
  • sort_keys (bool) – Whether to sort keys when formatting.
  • key_order (list) –

    List of keys that should be rendered in this exact order. Missing keys will be rendered as None, extra keys depending on sort_keys and the dict class.

    New in version 0.2.0.

>>> from structlog.processors import KeyValueRenderer
>>> KeyValueRenderer(sort_keys=True)(None, None, {'a': 42, 'b': [1, 2, 3]})
'a=42 b=[1, 2, 3]'
>>> KeyValueRenderer(key_order=['b', 'a'])(None, None,
...                                       {'a': 42, 'b': [1, 2, 3]})
'b=[1, 2, 3] a=42'

structlog.processors.format_exc_info(logger, name, event_dict)[source]

Replace an exc_info field by an exception string field:

If event_dict contains the key exc_info, there are two possible behaviors:

  • If the value is a tuple, render it into the key exception.
  • If the value true but no tuple, obtain exc_info ourselves and render that.

If there is no exc_info key, the event_dict is not touched. This behavior is analogue to the one of the stdlib’s logging.

>>> from structlog.processors import format_exc_info
>>> try:
...     raise ValueError
... except ValueError:
...     format_exc_info(None, None, {'exc_info': True})
{'exception': 'Traceback (most recent call last):...

class structlog.processors.TimeStamper(fmt=None, utc=True)[source]

Add a timestamp to event_dict.

Parameters:
  • format (str) – strftime format string, or "iso" for ISO 8601, or None for a UNIX timestamp.
  • utc (bool) – Whether timestamp should be in UTC or local time.
>>> from structlog.processors import TimeStamper
>>> TimeStamper()(None, None, {})  
{'timestamp': 1378994017}
>>> TimeStamper(fmt='iso')(None, None, {})  
{'timestamp': '2013-09-12T13:54:26.996778Z'}
>>> TimeStamper(fmt='%Y')(None, None, {})  
{'timestamp': '2013'}

stdlib Module

Processors and helpers specific to the logging module from the Python standard library.


class structlog.stdlib.BoundLogger(logger, processors, context)[source]

Python Standard Library version of structlog.BoundLogger. Works exactly like the generic one except that it takes advantage of knowing the logging methods in advance.

Use it like:

configure(
    wrapper_class=structlog.stdlib.BoundLogger,
)

class structlog.stdlib.LoggerFactory[source]

Build a standard library logger when an instance is called.

>>> from structlog import configure
>>> from structlog.stdlib import LoggerFactory
>>> configure(logger_factory=LoggerFactory())
__call__()[source]

Deduces the caller’s module name and create a stdlib logger.

Return type:logging.Logger

structlog.stdlib.filter_by_level(logger, name, event_dict)[source]

Check whether logging is configured to accept messages from this log level.

Should be the first processor if stdlib’s filtering by level is used so possibly expensive processors like exception formatters are avoided in the first place.

>>> import logging
>>> from structlog.stdlib import filter_by_level
>>> logging.basicConfig(level=logging.WARN)
>>> logger = logging.getLogger()
>>> filter_by_level(logger, 'warn', {})
{}
>>> filter_by_level(logger, 'debug', {})
Traceback (most recent call last):
...
DropEvent

twisted Module

Processors and tools specific to the Twisted networking engine.

See also structlog’s Twisted support.


class structlog.twisted.BoundLogger(logger, processors, context)[source]

Twisted-specific version of structlog.BoundLogger.

Works exactly like the generic one except that it takes advantage of knowing the logging methods in advance.

Use it like:

configure(
    wrapper_class=structlog.twisted.BoundLogger,
)
bind(**new_values)

Return a new logger with new_values added to the existing ones.

Return type:self.__class__
unbind(*keys)

Return a new logger with keys removed from the context.

Raises KeyError:
 If the key is not part of the context.
Return type:self.__class__
new(**new_values)

Clear context and binds initial_values using bind().

Only necessary with dict implementations that keep global state like those wrapped by structlog.threadlocal.wrap_dict() when threads are re-used.

Return type:self.__class__
msg(event=None, **kw)[source]

Process event and call log.msg() with the result.

err(event=None, **kw)[source]

Process event and call log.err() with the result.


class structlog.twisted.LoggerFactory[source]

Build a Twisted logger when an instance is called.

>>> from structlog import configure
>>> from structlog.twisted import LoggerFactory
>>> configure(logger_factory=LoggerFactory())

class structlog.twisted.EventAdapter(dictRenderer=None)[source]

Adapt an event_dict to Twisted logging system.

Particularly, make a wrapped twisted.python.log.err behave as expected.

Parameters:dictRenderer (callable) – Renderer that is used for the actual log message. Please note that structlog comes with a dedicated JSONRenderer.

Must be the last processor in the chain and requires a dictRenderer for the actual formatting as an constructor argument in order to be able to fully support the original behaviors of log.msg() and log.err().


class structlog.twisted.JSONRenderer(**dumps_kw)[source]

Behaves like structlog.processors.JSONRenderer except that it formats tracebacks and failures itself if called with err().

Not an adapter like EventAdapter but a real formatter. Nor does it require to be adapted using it.

Use together with a JSONLogObserverWrapper-wrapped Twisted logger like plainJSONStdOutLogger() for pure-JSON logs.


structlog.twisted.plainJSONStdOutLogger()[source]

Return a logger that writes only the message to stdout.

Transforms non-JSONRenderer messages to JSON.

Ideal for JSONifying log entries from Twisted plugins and libraries that are outside of your control:

$ twistd -n --logger structlog.twisted.plainJSONStdOutLogger web
{"event": "Log opened.", "system": "-"}
{"event": "twistd 13.1.0 (python 2.7.3) starting up.", "system": "-"}
{"event": "reactor class: twisted...EPollReactor.", "system": "-"}
{"event": "Site starting on 8080", "system": "-"}
{"event": "Starting factory <twisted.web.server.Site ...>", ...}
...

Composes PlainFileLogObserver and JSONLogObserverWrapper to a usable logger.

New in version 0.2.0.


structlog.twisted.JSONLogObserverWrapper(observer)[source]

Wrap a log observer and render non-JSONRenderer entries to JSON.

Parameters:observer (ILogObserver) – Twisted log observer to wrap. For example PlainFileObserver or Twisted’s stock FileLogObserver

New in version 0.2.0.


class structlog.twisted.PlainFileLogObserver(file)[source]

Write only the the plain message without timestamps or anything else.

Great to just print JSON to stdout where you catch it with something like runit.

Parameters:file (file) – File to print to.

New in version 0.2.0.

Table Of Contents

Related Topics

This Page