structlog Package¶
structlog
Package¶
-
structlog.
get_logger
(*args, **initial_values)[source]¶ 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: - args – Optional positional arguments that are passed unmodified to the logger factory. Therefore it depends on the factory what they mean.
- 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()
.New in version 0.4.0: args
-
structlog.
getLogger
(*args, **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, logger_factory_args=None, **initial_values)[source]¶ 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.
- logger_factory_args (tuple) – Values that are passed unmodified as
*logger_factory_args
to the logger factory if not None.
Return type: A proxy that creates a correctly configured bound logger when necessary.
See
configure()
for the meaning of the rest of the arguments.New in version 0.4.0: logger_factory_args
-
structlog.
configure
(processors=None, wrapper_class=None, context_class=None, logger_factory=None, cache_logger_on_first_use=None)[source]¶ 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 (type) – Class to be used for internal context keeping.
- logger_factory (callable) – Factory to be called to create a new logger that shall be wrapped.
- 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: cache_logger_on_first_use
-
structlog.
configure_once
(*args, **kw)[source]¶ Configures iff structlog isn’t configured yet.
It does not matter whether is was configured using
configure()
orconfigure_once()
before.Raises a RuntimeWarning if repeated configuration is attempted.
-
structlog.
reset_defaults
()[source]¶ Resets global default values to builtins.
That means [
StackInfoRenderer
,format_exc_info()
,KeyValueRenderer
] for processors,BoundLogger
for wrapper_class,OrderedDict
for context_class,PrintLoggerFactory
for logger_factory, and False for cache_logger_on_first_use.Also sets the global class attribute
is_configured
to False.
-
class
structlog.
BoundLogger
(logger, processors, context)[source]¶ 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
orstructlog.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()
andget_logger()
.-
bind
(**new_values)¶ Return a new logger with new_values added to the existing ones.
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__
-
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)[source]¶ Print 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 finicky in doctests.
-
critical
(message)¶ Print message.
-
debug
(message)¶ Print message.
-
err
(message)¶ Print message.
-
error
(message)¶ Print message.
-
failure
(message)¶ Print message.
-
info
(message)¶ Print message.
-
log
(message)¶ Print message.
-
warning
(message)¶ Print message.
-
-
class
structlog.
PrintLoggerFactory
(file=None)[source]¶ Produce
PrintLogger
s.To be used with
structlog.configure()
‘s logger_factory.Parameters: file (file) – File to print to. (default: stdout) Positional arguments are silently ignored.
New in version 0.4.0.
-
class
structlog.
ReturnLogger
[source]¶ Return the arguments 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.
-
critical
(*args, **kw)¶ Return tuple of
args, kw
or justargs[0]
if only one arg passed
-
debug
(*args, **kw)¶ Return tuple of
args, kw
or justargs[0]
if only one arg passed
-
err
(*args, **kw)¶ Return tuple of
args, kw
or justargs[0]
if only one arg passed
-
error
(*args, **kw)¶ Return tuple of
args, kw
or justargs[0]
if only one arg passed
-
failure
(*args, **kw)¶ Return tuple of
args, kw
or justargs[0]
if only one arg passed
-
info
(*args, **kw)¶ Return tuple of
args, kw
or justargs[0]
if only one arg passed
-
log
(*args, **kw)¶ Return tuple of
args, kw
or justargs[0]
if only one arg passed
-
warning
(*args, **kw)¶ Return tuple of
args, kw
or justargs[0]
if only one arg passed
-
-
class
structlog.
ReturnLoggerFactory
[source]¶ Produce and cache
ReturnLogger
s.To be used with
structlog.configure()
‘s logger_factory.Positional arguments are silently ignored.
New in version 0.4.0.
-
exception
structlog.
DropEvent
[source]¶ 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)[source]¶ Immutable context carrier.
Doesn’t do any actual logging; examples for useful subclasses are:
- the generic
BoundLogger
that can wrap anything, structlog.twisted.BoundLogger
,- and
structlog.stdlib.BoundLogger
.
See also Custom Wrappers.
-
_logger
= None¶ Wrapped logger.
-
_process_event
(method_name, event, event_kw)[source]¶ 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.Raises: ValueError
if the final processor doesn’t return a string, tuple, or a dict.Return type: tuple of (*args, **kw)
Changed in version 14.0.0: Allow final processor to return a dict.
-
_proxy_to_logger
(method_name, event=None, **event_kw)[source]¶ Run processor chain on event & call method_name on wrapped logger.
DRY convenience method that runs
_process_event()
, takes care of handlingstructlog.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}
.
-
bind
(**new_values)[source]¶ Return a new logger with new_values added to the existing ones.
Return type: self.__class__
-
new
(**new_values)[source]¶ 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__
- the generic
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 (structlog.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: >>> 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'
New in version 0.2.0: key_order
-
class
structlog.processors.
UnicodeEncoder
(encoding='utf-8', errors='backslashreplace')[source]¶ Encode unicode values in event_dict.
Parameters: Useful for
KeyValueRenderer
if you don’t want to see u-prefixes:>>> from structlog.processors import KeyValueRenderer, UnicodeEncoder >>> KeyValueRenderer()(None, None, {'foo': u'bar'}) "foo=u'bar'" >>> KeyValueRenderer()(None, None, ... UnicodeEncoder()(None, None, {'foo': u'bar'})) "foo='bar'"
or
JSONRenderer
andstructlog.twisted.JSONRenderer
to make sure user-supplied strings don’t break the renderer.Just put it in the processor chain before the renderer.
-
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):...
- If the value is a tuple, render it into the key
-
class
structlog.processors.
StackInfoRenderer
[source]¶ Add stack information with key stack if stack_info is true.
Useful when you want to attach a stack dump to a log entry without involving an exception.
It works analogously to the stack_info argument of the Python 3 standard library logging but works on both 2 and 3.
New in version 0.4.0.
-
class
structlog.processors.
ExceptionPrettyPrinter
(file=None)[source]¶ Pretty print exceptions and remove them from the event_dict.
Parameters: file (file) – Target file for output (default: sys.stdout). This processor is mostly for development and testing so you can read exceptions properly formatted.
It behaves like
format_exc_info()
except it removes the exception data from the event dictionary after printing it.It’s tolerant to having format_exc_info in front of itself in the processor chain but doesn’t require it. In other words, it handles both exception as well as exc_info keys.
New in version 0.4.0.
-
class
structlog.processors.
TimeStamper
(fmt=None, utc=True)[source]¶ Add a timestamp to event_dict.
Note
You probably want to let OS tools take care of timestamping. See also Logging Best Practices.
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.
- key (str) – Target key in event_dict for added timestamps.
>>> 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', key='year')(None, None, {}) {'year': '2013'}
- format (str) – strftime format string, or
stdlib
Module¶
Processors and helpers specific to the logging
module from the Python
standard library.
See also structlog’s standard library support.
-
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:
structlog.configure( wrapper_class=structlog.stdlib.BoundLogger, )
-
bind
(**new_values)¶ Return a new logger with new_values added to the existing ones.
Return type: self.__class__
-
critical
(event=None, *args, **kw)[source]¶ Process event and call
logging.Logger.critical()
with the result.
-
debug
(event=None, *args, **kw)[source]¶ Process event and call
logging.Logger.debug()
with the result.
-
error
(event=None, *args, **kw)[source]¶ Process event and call
logging.Logger.error()
with the result.
-
exception
(event=None, *args, **kw)[source]¶ Process event and call
logging.Logger.error()
with the result, after settingexc_info
to True.
-
info
(event=None, *args, **kw)[source]¶ Process event and call
logging.Logger.info()
with the result.
-
log
(level, event, *args, **kw)[source]¶ Process event and call the appropriate logging method depending on level.
-
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__
-
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__
-
warn
(event=None, *args, **kw)¶ Process event and call
logging.Logger.warning()
with the result.
-
warning
(event=None, *args, **kw)[source]¶ Process event and call
logging.Logger.warning()
with the result.
-
-
class
structlog.stdlib.
LoggerFactory
(ignore_frame_names=None)[source]¶ Build a standard library logger when an instance is called.
Sets a custom logger using
logging.setLoggerClass()
so variables in log format are expanded properly.>>> from structlog import configure >>> from structlog.stdlib import LoggerFactory >>> configure(logger_factory=LoggerFactory())
Parameters: ignore_frame_names (list of str) – When guessing the name of a logger, skip frames whose names start with one of these. For example, in pyramid applications you’ll want to set it to ['venusian', 'pyramid.config']
.-
__call__
(*args)[source]¶ Deduce the caller’s module name and create a stdlib logger.
If an optional argument is passed, it will be used as the logger name instead of guesswork. This optional argument would be passed from the
structlog.get_logger()
call. For examplestructlog.get_logger('foo')
would cause this method to be called with'foo'
as its first positional argument.Return type: logging.Logger Changed in version 0.4.0: Added support for optional positional arguments. Using the first one for naming the constructed 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
-
structlog.stdlib.
add_log_level
(logger, method_name, event_dict)[source]¶ Add the log level to the event dict.
-
structlog.stdlib.
add_logger_name
(logger, method_name, event_dict)[source]¶ Add the logger name to the event dict.
-
class
structlog.stdlib.
PositionalArgumentsFormatter
(remove_positional_args=True)[source]¶ Apply stdlib-like string formatting to the event key.
If the positional_args key in the event dict is set, it must contain a tuple that is used for formatting (using the %s string formatting operator) of the value from the event key. This works in the same way as the stdlib handles arguments to the various log methods: if the tuple contains only a single dict argument it is used for keyword placeholders in the event string, otherwise it will be used for positional placeholders.
positional_args is populated by structlog.stdlib.BoundLogger or can be set manually.
The remove_positional_args flag can be set to False to keep the positional_args key in the event dict; by default it will be removed from the event dict after formatting a message.
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__
-
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__
-
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.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()
andlog.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().Note
This ultimately means that the messages get logged out using msg(), and not err() which renders failures in separate lines.
Therefore it will break your tests that contain assertions using flushLoggedErrors.
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 likeplainJSONStdOutLogger()
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
andJSONLogObserverWrapper
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 FileLogObserverNew in version 0.2.0.