API Reference¶
Note
The examples here use a very simplified configuration using the minimalistic structlog.processors.KeyValueRenderer
for brevity and to enable doctests.
The output is going to be different (nicer!) with the default configuration.
structlog
Package¶
-
structlog.
get_logger
(*args: Any, **initial_values: Any) → Any[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.
- Returns
A proxy that creates a correctly configured bound logger when necessary. The type of that bound logger depends on your configuration and is
structlog.BoundLogger
by default.
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: Any, **initial_values: Any) → Any¶ 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: Any, processors: Optional[Iterable[Callable[[Any, str, MutableMapping[str, Any]], Union[Mapping[str, Any], str, bytes, Tuple[Any, …]]]]] = None, wrapper_class: Optional[Type[structlog.types.BindableLogger]] = None, context_class: Optional[Type[Union[Dict[str, Any], Dict[Any, Any]]]] = None, cache_logger_on_first_use: Optional[bool] = None, logger_factory_args: Optional[Iterable[Any]] = None, **initial_values: Any) → Any[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 – Values that are passed unmodified as
*logger_factory_args
to the logger factory if notNone
.
- Returns
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: Optional[Iterable[Callable[[Any, str, MutableMapping[str, Any]], Union[Mapping[str, Any], str, bytes, Tuple[Any, …]]]]] = None, wrapper_class: Optional[Type[structlog.types.BindableLogger]] = None, context_class: Optional[Type[Union[Dict[str, Any], Dict[Any, Any]]]] = None, logger_factory: Optional[Callable[[…], Any]] = None, cache_logger_on_first_use: Optional[bool] = None) → None[source]¶ Configures the global defaults.
They are used if
wrap_logger
orget_logger
are called without arguments.Can be called several times, keeping an argument at
None
leaves it unchanged from the current setting.After calling for the first time,
is_configured
starts returningTrue
.Use
reset_defaults
to undo your changes.- Parameters
processors – The processor chain. See Processors for details.
wrapper_class – Class to use for wrapping loggers instead of
structlog.BoundLogger
. See Standard Library Logging, Twisted, and Custom Wrappers.context_class – Class to be used for internal context keeping.
logger_factory – Factory to be called to create a new logger that shall be wrapped.
cache_logger_on_first_use –
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 toTrue
, this assembled logger is cached. See Performance.
New in version 0.3.0: cache_logger_on_first_use
-
structlog.
configure_once
(processors: Optional[Iterable[Callable[[Any, str, MutableMapping[str, Any]], Union[Mapping[str, Any], str, bytes, Tuple[Any, …]]]]] = None, wrapper_class: Optional[Type[structlog.types.BindableLogger]] = None, context_class: Optional[Type[Union[Dict[str, Any], Dict[Any, Any]]]] = None, logger_factory: Optional[Callable[[…], Any]] = None, cache_logger_on_first_use: Optional[bool] = None) → None[source]¶ Configures if structlog isn’t configured yet.
It does not matter whether it was configured using
configure
orconfigure_once
before.Raises a
RuntimeWarning
if repeated configuration is attempted.
-
structlog.
reset_defaults
() → None[source]¶ Resets global default values to builtin defaults.
is_configured
starts returningFalse
afterwards.
-
structlog.
is_configured
() → bool[source]¶ Return whether
structlog
has been configured.If
False
,structlog
is running with builtin defaults.
-
structlog.
get_config
() → Dict[str, Any][source]¶ Get a dictionary with the current configuration.
Note
Changes to the returned dictionary do not affect
structlog
.
-
class
structlog.
BoundLogger
(logger: Any, processors: Iterable[Callable[[Any, str, MutableMapping[str, Any]], Union[Mapping[str, Any], str, bytes, Tuple[Any, …]]]], context: Union[Dict[str, Any], Dict[Any, Any]])[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.stdlib.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: Any) → structlog._base.BoundLoggerBase¶ Return a new logger with new_values added to the existing ones.
-
new
(**new_values: Any) → structlog._base.BoundLoggerBase¶ 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.
-
-
structlog.
make_filtering_bound_logger
(min_level: int) → Type[structlog.types.FilteringBoundLogger][source]¶ Create a new
FilteringBoundLogger
that only logs min_level or higher.The logger is optimized such that log levels below min_level only consist of a
return None
.Compared to using
structlog
’s standard library integration and thestructlog.stdlib.filter_by_level
processor:It’s faster because once the logger is built at program start, it’s a static class.
For the same reason you can’t change the log level once configured. Use the dynamic approach of Standard Library Logging instead, if you need this feature.
- Parameters
min_level – The log level as an integer. You can use the constants from
logging
likelogging.INFO
or pass the values directly. See this table from the logging docs for possible values.
New in version 20.2.0.
-
structlog.
get_context
(bound_logger: structlog.types.BindableLogger) → Union[Dict[str, Any], Dict[Any, Any]][source]¶ Return bound_logger’s context.
The type of bound_logger and the type returned depend on your configuration.
- Parameters
bound_logger – The bound logger whose context you want.
- Returns
The actual context from bound_logger. It is not copied first.
New in version 20.2.
-
class
structlog.
PrintLogger
(file: Optional[TextIO] = None)[source]¶ Print events into a file.
- Parameters
file – File to print to. (default:
sys.stdout
)
>>> from structlog import PrintLogger >>> PrintLogger().msg("hello") hello
Useful if you follow current logging best practices.
Also very useful for testing and examples since logging is finicky in doctests.
-
class
structlog.
PrintLoggerFactory
(file: Optional[TextIO] = None)[source]¶ Produce
PrintLogger
s.To be used with
structlog.configure
‘slogger_factory
.- Parameters
file – File to print to. (default:
sys.stdout
)
Positional arguments are silently ignored.
New in version 0.4.0.
-
class
structlog.
BytesLogger
(file: Optional[BinaryIO] = None)[source]¶ Writes bytes into a file.
- Parameters
file – File to print to. (default:
sys.stdout
.buffer
)
Useful if you follow current logging best practices together with a formatter that returns bytes (e.g. orjson).
New in version 20.2.0.
-
class
structlog.
BytesLoggerFactory
(file: Optional[BinaryIO] = None)[source]¶ Produce
BytesLogger
s.To be used with
structlog.configure
‘slogger_factory
.- Parameters
file – File to print to. (default:
sys.stdout
.buffer
)
Positional arguments are silently ignored.
New in version 20.2.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: Any, processors: Iterable[Callable[[Any, str, MutableMapping[str, Any]], Union[Mapping[str, Any], str, bytes, Tuple[Any, …]]]], context: Union[Dict[str, Any], Dict[Any, Any]])[source]¶ Immutable context carrier.
Doesn’t do any actual logging; examples for useful subclasses are:
the generic
BoundLogger
that can wrap anything,
See also Custom Wrappers.
-
_logger
: Any¶ Wrapped logger.
-
_process_event
(method_name: str, event: Optional[str], event_kw: Dict[str, Any]) → Tuple[Sequence[Any], Mapping[str, Any]][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 – 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 str, bytes, tuple, or a dict.- Returns
tuple
of(*args, **kw)
Changed in version 14.0.0: Allow final processor to return a
dict
.
-
_proxy_to_logger
(method_name: str, event: Optional[str] = None, **event_kw: Any) → Any[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 – 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: Any) → structlog._base.BoundLoggerBase[source]¶ Return a new logger with new_values added to the existing ones.
-
new
(**new_values: Any) → structlog._base.BoundLoggerBase[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.
structlog.dev
Module¶
Helpers that make development with structlog
more pleasant.
-
class
structlog.dev.
ConsoleRenderer
(pad_event: int = 30, colors: bool = True, force_colors: bool = False, repr_native_str: bool = False, level_styles: Optional[Union[structlog.dev._Styles, Type[structlog.dev._Styles]]] = None)[source]¶ Render
event_dict
nicely aligned, possibly in colors, and ordered.If
event_dict
contains anexception
key (for example fromformat_exc_info()
), it will be rendered after the log line.- Parameters
pad_event – Pad the event to this many characters.
colors – Use colors for a nicer output.
force_colors – Force colors even for non-tty destinations. Use this option if your logs are stored in a file that is meant to be streamed to the console.
repr_native_str – When
True
,repr
is also applied to native strings (i.e. unicode on Python 3 and bytes on Python 2). Setting this toFalse
is useful if you want to have human-readable non-ASCII output on Python 2. Theevent
key is neverrepr
-ed.level_styles – When present, use these styles for colors. This must be a dict from level names (strings) to colorama styles. The default can be obtained by calling
ConsoleRenderer.get_default_level_styles
Requires the colorama package if colors is
True
.New in version 16.0.
New in version 16.1: colors
New in version 17.1: repr_native_str
New in version 18.1: force_colors
New in version 18.1: level_styles
Changed in version 19.2:
colorama
now initializes lazily to avoid unwanted initializations asConsoleRenderer
is used by default.Changed in version 19.2: Can be pickled now.
Changed in version 20.1:
colorama
does not initialize lazily on Windows anymore because it breaks rendering.-
static
get_default_level_styles
(colors: bool = True) → Any[source]¶ Get the default styles for log levels
This is intended to be used with
ConsoleRenderer
’slevel_styles
parameter. For example, if you are adding custom levels in your home-grownadd_log_level()
you could do:my_styles = ConsoleRenderer.get_default_level_styles() my_styles["EVERYTHING_IS_ON_FIRE"] = my_styles["critical"] renderer = ConsoleRenderer(level_styles=my_styles)
- Parameters
colors – Whether to use colorful styles. This must match the colors parameter to
ConsoleRenderer
. Default:True
.
structlog.testing
Module¶
Helpers to test your application’s logging behavior.
New in version 20.1.0.
See Testing.
-
structlog.testing.
capture_logs
() → Generator[List[MutableMapping[str, Any]], None, None][source]¶ Context manager that appends all logging statements to its yielded list while it is active. Disables all configured processors for the duration of the context manager.
Attention: this is not thread-safe!
New in version 20.1.0.
-
class
structlog.testing.
LogCapture
[source]¶ Class for capturing log messages in its entries list. Generally you should use
structlog.testing.capture_logs
, but you can use this class if you want to capture logs with other patterns.New in version 20.1.0.
-
class
structlog.testing.
CapturingLogger
[source]¶ Store the method calls that it’s been called with.
This is nicer than
ReturnLogger
for unit tests because the bound logger doesn’t have to cooperate.Any method name is supported.
New in version 20.2.0.
>>> from pprint import pprint >>> cl = structlog.testing.CapturingLogger() >>> cl.msg("hello") >>> cl.msg("hello", when="again") >>> pprint(cl.calls) [CapturedCall(method_name='msg', args=('hello',), kwargs={}), CapturedCall(method_name='msg', args=('hello',), kwargs={'when': 'again'})]
-
class
structlog.testing.
CapturingLoggerFactory
[source]¶ Produce and cache
CapturingLogger
s.Each factory produces and re-uses only one logger.
You can access it via the
logger
attribute.To be used with
structlog.configure
‘s logger_factory.Positional arguments are silently ignored.
New in version 20.2.0.
-
class
structlog.testing.
CapturedCall
(method_name: str, args: Tuple[Any, …], kwargs: Dict[str, Any])[source]¶ A call as captured by
CapturingLogger
.Can also be unpacked like a tuple.
- Parameters
method_name – The method name that got called.
args – A tuple of the positional arguments.
kwargs – A dict of the keyword arguments.
New in version 20.2.0.
-
class
structlog.testing.
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'})
Changed in version 0.3.0: Allow for arbitrary arguments and keyword arguments to be passed in.
-
critical
(*args: Any, **kw: Any) → Any¶ Return tuple of
args, kw
or justargs[0]
if only one arg passed
-
debug
(*args: Any, **kw: Any) → Any¶ Return tuple of
args, kw
or justargs[0]
if only one arg passed
-
err
(*args: Any, **kw: Any) → Any¶ Return tuple of
args, kw
or justargs[0]
if only one arg passed
-
error
(*args: Any, **kw: Any) → Any¶ Return tuple of
args, kw
or justargs[0]
if only one arg passed
-
failure
(*args: Any, **kw: Any) → Any¶ Return tuple of
args, kw
or justargs[0]
if only one arg passed
-
fatal
(*args: Any, **kw: Any) → Any¶ Return tuple of
args, kw
or justargs[0]
if only one arg passed
-
info
(*args: Any, **kw: Any) → Any¶ Return tuple of
args, kw
or justargs[0]
if only one arg passed
-
log
(*args: Any, **kw: Any) → Any¶ Return tuple of
args, kw
or justargs[0]
if only one arg passed
-
msg
(*args: Any, **kw: Any) → Any[source]¶ Return tuple of
args, kw
or justargs[0]
if only one arg passed
-
warning
(*args: Any, **kw: Any) → Any¶ Return tuple of
args, kw
or justargs[0]
if only one arg passed
-
-
class
structlog.testing.
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.
structlog.threadlocal
Module¶
Primitives to keep context global but thread (and greenlet) local.
See Thread Local Context.
-
structlog.threadlocal.
merge_threadlocal
(logger: Any, method_name: str, event_dict: MutableMapping[str, Any]) → MutableMapping[str, Any][source]¶ A processor that merges in a global (thread-local) context.
Use this as your first processor in
structlog.configure()
to ensure thread-local context is included in all log calls.New in version 19.2.0.
Changed in version 20.1.0: This function used to be called
merge_threalocal_context
and that name is still kept around for backward compatibility.
-
structlog.threadlocal.
clear_threadlocal
() → None[source]¶ Clear the thread-local context.
The typical use-case for this function is to invoke it early in request-handling code.
New in version 19.2.0.
-
structlog.threadlocal.
bind_threadlocal
(**kw: Any) → None[source]¶ Put keys and values into the thread-local context.
Use this instead of
bind()
when you want some context to be global (thread-local).New in version 19.2.0.
-
structlog.threadlocal.
wrap_dict
(dict_class: Type[MutableMapping[str, Any]]) → Type[MutableMapping[str, Any]][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 – Class used for keeping context.
-
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") x=5 y=3 event='event' >>> logger.msg("event") event='event'
-
structlog.threadlocal.
as_immutable
(logger: TLLogger) → TLLogger[source]¶ Extract the context from a thread local logger into an immutable logger.
- Parameters
logger (structlog.types.BindableLogger) – A logger with possibly thread local state.
- Returns
BoundLogger
with an immutable context.
structlog.contextvars
Module¶
Primitives to deal with a concurrency supporting context, as introduced in
Python 3.7 as contextvars
.
New in version 20.1.0.
See Context Variables.
-
structlog.contextvars.
merge_contextvars
(logger: Any, method_name: str, event_dict: Dict[str, Any]) → Union[Dict[str, Any], Dict[Any, Any]][source]¶ A processor that merges in a global (context-local) context.
Use this as your first processor in
structlog.configure()
to ensure context-local context is included in all log calls.New in version 20.1.0.
-
structlog.contextvars.
clear_contextvars
() → None[source]¶ Clear the context-local context.
The typical use-case for this function is to invoke it early in request- handling code.
New in version 20.1.0.
structlog.processors
Module¶
Processors useful regardless of the logging framework.
-
class
structlog.processors.
JSONRenderer
(serializer: Callable[[...], Union[str, bytes]] = <function dumps>, **dumps_kw: Any)[source]¶ Render the
event_dict
usingserializer(event_dict, **json_kw)
.- Parameters
json_kw – Are passed unmodified to serializer. If default is passed, it will disable support for
__structlog__
-based serialization.serializer – A
json.dumps()
-compatible callable that will be used to format the string. This can be used to use alternative JSON encoders like simplejson or RapidJSON (faster but Python 3-only) (default:json.dumps()
).
New in version 0.2.0: Support for
__structlog__
serialization method.New in version 15.4.0: serializer parameter.
New in version 18.2.0: Serializer’s default parameter can be overwritten now.
>>> 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: ... def __structlog__(self): ... return ["C1!"] ... def __repr__(self): ... return "__structlog__ took precedence" >>> class C2: ... 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.
If you choose to pass a default parameter as part of json_kw, support for
__structlog__
is disabled. This can be useful when used together with more elegant serialization methods likefunctools.singledispatch()
: Better Python Object Serialization.
-
class
structlog.processors.
KeyValueRenderer
(sort_keys: bool = False, key_order: Optional[Sequence[str]] = None, drop_missing: bool = False, repr_native_str: bool = True)[source]¶ Render
event_dict
as a list ofKey=repr(Value)
pairs.- Parameters
sort_keys – Whether to sort keys when formatting.
key_order – 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.drop_missing – When
True
, extra keys in key_order will be dropped rather than rendered asNone
.repr_native_str – When
True
,repr()
is also applied to native strings (i.e. unicode on Python 3 and bytes on Python 2). Setting this toFalse
is useful if you want to have human-readable non-ASCII output on Python 2.
New in version 0.2.0: key_order
New in version 16.1.0: drop_missing
New in version 17.1.0: repr_native_str
>>> 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.
add_log_level
(logger: logging.Logger, method_name: str, event_dict: MutableMapping[str, Any]) → MutableMapping[str, Any][source]¶ Add the log level to the event dict under the
level
key.Since that’s just the log method name, this processor works with non-stdlib logging as well. Therefore it’s importable both from
structlog.processors
as well as fromstructlog.stdlib
.New in version 15.0.0.
Changed in version 20.2.0: Importable from
structlog.processors
(additionally tostructlog.stdlib
).
-
class
structlog.processors.
UnicodeDecoder
(encoding: str = 'utf-8', errors: str = 'replace')[source]¶ Decode byte string values in
event_dict
.- Parameters
encoding – Encoding to decode from (default:
"utf-8"
).errors – How to cope with encoding errors (default:
"replace"
).
Useful if you’re running Python 3 as otherwise
b"abc"
will be rendered as'b"abc"'
.Just put it in the processor chain before the renderer.
New in version 15.4.0.
-
class
structlog.processors.
UnicodeEncoder
(encoding: str = 'utf-8', errors: str = 'backslashreplace')[source]¶ Encode unicode values in
event_dict
.- Parameters
encoding – Encoding to encode to (default:
"utf-8"
).errors – How to cope with encoding errors (default
"backslashreplace"
).
Useful if you’re running Python 2 as otherwise
u"abc"
will be rendered as'u"abc"'
.Just put it in the processor chain before the renderer.
-
structlog.processors.
format_exc_info
(logger: Any, name: str, event_dict: MutableMapping[str, Any]) → MutableMapping[str, Any][source]¶ Replace an
exc_info
field by anexception
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 is an Exception and you’re running Python 3, 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.
StackInfoRenderer
[source]¶ Add stack information with key
stack
ifstack_info
isTrue
.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: Optional[TextIO] = None)[source]¶ Pretty print exceptions and remove them from the
event_dict
.- Parameters
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 bothexception
as well asexc_info
keys.New in version 0.4.0.
Changed in version 16.0.0: Added support for passing exceptions as
exc_info
on Python 3.
-
class
structlog.processors.
TimeStamper
(fmt: Optional[str] = None, utc: bool = True, key: str = 'timestamp')[source]¶ Add a timestamp to
event_dict
.- Parameters
fmt – strftime format string, or
"iso"
for ISO 8601, orNone
for a UNIX timestamp.utc – Whether timestamp should be in UTC or local time.
key – Target key in event_dict for added timestamps.
Changed in version 19.2: Can be pickled now.
>>> 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'}
structlog.stdlib
Module¶
Processors and helpers specific to the logging
module from the Python
standard library.
See also structlog’s standard library support.
-
structlog.stdlib.
get_logger
(*args: Any, **initial_values: Any) → structlog.stdlib.BoundLogger[source]¶ Only calls
structlog.get_logger
, but has the correct type hints.Warning
Does not check whether you’ve configured
structlog
correctly!See Standard Library Logging for details.
New in version 20.2.0.
-
class
structlog.stdlib.
BoundLogger
(logger: Any, processors: Iterable[Callable[[Any, str, MutableMapping[str, Any]], Union[Mapping[str, Any], str, bytes, Tuple[Any, …]]]], context: Union[Dict[str, Any], Dict[Any, Any]])[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, )
It also contains a bunch of properties that pass-through to the wrapped
logging.Logger
which should make it work as a drop-in replacement.-
bind
(**new_values: Any) → structlog.stdlib.BoundLogger[source]¶ Return a new logger with new_values added to the existing ones.
-
critical
(event: Optional[str] = None, *args: Any, **kw: Any) → Any[source]¶ Process event and call
logging.Logger.critical
with the result.
-
debug
(event: Optional[str] = None, *args: Any, **kw: Any) → Any[source]¶ Process event and call
logging.Logger.debug
with the result.
-
error
(event: Optional[str] = None, *args: Any, **kw: Any) → Any[source]¶ Process event and call
logging.Logger.error
with the result.
-
exception
(event: Optional[str] = None, *args: Any, **kw: Any) → Any[source]¶ Process event and call
logging.Logger.error
with the result, after settingexc_info
toTrue
.
-
info
(event: Optional[str] = None, *args: Any, **kw: Any) → Any[source]¶ Process event and call
logging.Logger.info
with the result.
-
log
(level: int, event: Optional[str] = None, *args: Any, **kw: Any) → Any[source]¶ Process event and call the appropriate logging method depending on level.
-
new
(**new_values: Any) → structlog.stdlib.BoundLogger[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.
-
try_unbind
(*keys: str) → structlog.stdlib.BoundLogger[source]¶ Like
unbind()
, but best effort: missing keys are ignored.New in version 18.2.0.
-
unbind
(*keys: str) → structlog.stdlib.BoundLogger[source]¶ Return a new logger with keys removed from the context.
- Raises
KeyError – If the key is not part of the context.
-
warn
(event: Optional[str] = None, *args: Any, **kw: Any) → Any¶ Process event and call
logging.Logger.warning
with the result.
-
warning
(event: Optional[str] = None, *args: Any, **kw: Any) → Any[source]¶ Process event and call
logging.Logger.warning
with the result.
-
-
class
structlog.stdlib.
AsyncBoundLogger
(logger: logging.Logger, processors: Iterable[Callable[[Any, str, MutableMapping[str, Any]], Union[Mapping[str, Any], str, bytes, Tuple[Any, …]]]], context: Union[Dict[str, Any], Dict[Any, Any]], *, _sync_bl: Any = None, _loop: Any = None)[source]¶ Wraps a
BoundLogger
& exposes its logging methods asasync
versions.Instead of blocking the program, they are run asynchronously in a thread pool executor.
This means more computational overhead per log call. But it also means that the processor chain (e.g. JSON serialization) and I/O won’t block your whole application.
Only available for Python 3.7 and later.
- Variables
sync_bl (structlog.stdlib.BoundLogger) – The wrapped synchronous logger. It is useful to be able to log synchronously occasionally.
New in version 20.2.0.
-
class
structlog.stdlib.
LoggerFactory
(ignore_frame_names: Optional[List[str]] = 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 – 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: Any) → logging.Logger[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.Changed in version 0.4.0: Added support for optional positional arguments. Using the first one for naming the constructed logger.
-
structlog.stdlib.
render_to_log_kwargs
(_: logging.Logger, __: str, event_dict: MutableMapping[str, Any]) → MutableMapping[str, Any][source]¶ Render
event_dict
into keyword arguments forlogging.log
.The
event
field is translated intomsg
and the rest of the event_dict is added asextra
.This allows you to defer formatting to
logging
.New in version 17.1.0.
-
structlog.stdlib.
filter_by_level
(logger: logging.Logger, method_name: str, event_dict: MutableMapping[str, Any]) → MutableMapping[str, Any][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: logging.Logger, method_name: str, event_dict: MutableMapping[str, Any]) → MutableMapping[str, Any][source]¶ Add the log level to the event dict under the
level
key.Since that’s just the log method name, this processor works with non-stdlib logging as well. Therefore it’s importable both from
structlog.processors
as well as fromstructlog.stdlib
.New in version 15.0.0.
Changed in version 20.2.0: Importable from
structlog.processors
(additionally tostructlog.stdlib
).
-
structlog.stdlib.
add_log_level_number
(logger: logging.Logger, method_name: str, event_dict: MutableMapping[str, Any]) → MutableMapping[str, Any][source]¶ Add the log level number to the event dict.
Log level numbers map to the log level names. The Python stdlib uses them for filtering logic. This adds the same numbers so users can leverage similar filtering. Compare:
level in ("warning", "error", "critical") level_number >= 30
The mapping of names to numbers is in
structlog.stdlib._log_levels._NAME_TO_LEVEL
.New in version 18.2.0.
-
structlog.stdlib.
add_logger_name
(logger: logging.Logger, method_name: str, event_dict: MutableMapping[str, Any]) → MutableMapping[str, Any][source]¶ Add the logger name to the event dict.
-
class
structlog.stdlib.
PositionalArgumentsFormatter
(remove_positional_args: bool = 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 theevent
key. This works in the same way as the stdlib handles arguments to the various log methods: if the tuple contains only a singledict
argument it is used for keyword placeholders in theevent
string, otherwise it will be used for positional placeholders.positional_args
is populated bystructlog.stdlib.BoundLogger
or can be set manually.The remove_positional_args flag can be set to
False
to keep thepositional_args
key in the event dict; by default it will be removed from the event dict after formatting a message.
-
class
structlog.stdlib.
ProcessorFormatter
(processor: Callable[[Any, str, MutableMapping[str, Any]], Union[Mapping[str, Any], str, bytes, Tuple[Any, …]]], foreign_pre_chain: Optional[Sequence[Callable[[Any, str, MutableMapping[str, Any]], Union[Mapping[str, Any], str, bytes, Tuple[Any, …]]]]] = None, keep_exc_info: bool = False, keep_stack_info: bool = False, logger: Optional[logging.Logger] = None, pass_foreign_args: bool = False, *args: Any, **kwargs: Any)[source]¶ Call
structlog
processors on :logging.LogRecord
s.This
logging.Formatter
allows to configurelogging
to call processor onstructlog
-borne log entries (origin is determined solely on the fact whether themsg
field on thelogging.LogRecord
is a dict or not).This allows for two interesting use cases:
You can format non-
structlog
log entries.You can multiplex log records into multiple
logging.Handler
s.
Please refer to Standard Library Logging for examples.
- Parameters
processor – A
structlog
processor.foreign_pre_chain – If not
None
, it is used as an iterable of processors that is applied to non-structlog
log entries before processor. IfNone
, formatting is left tologging
. (default:None
)keep_exc_info –
exc_info
onlogging.LogRecord
s is added to theevent_dict
and removed afterwards. Set this toTrue
to keep it on thelogging.LogRecord
. (default: False)keep_stack_info – Same as keep_exc_info except for Python 3’s
stack_info
. (default: False)logger – Logger which we want to push through the
structlog
processor chain. This parameter is necessary for some of the processors likefilter_by_level
. (default: None)pass_foreign_args – If True, pass a foreign log record’s
args
attribute to theevent_dict
underpositional_args
key. (default: False)
New in version 17.1.0.
New in version 17.2.0: keep_exc_info and keep_stack_info
New in version 19.2.0: logger
New in version 19.2.0: pass_foreign_args
-
static
wrap_for_formatter
(logger: logging.Logger, name: str, event_dict: MutableMapping[str, Any]) → Tuple[Tuple[MutableMapping[str, Any]], Dict[str, Dict[str, Any]]][source]¶ Wrap logger, name, and event_dict.
The result is later unpacked by
ProcessorFormatter
when formatting log entries.Use this static method as the renderer (i.e. final processor) if you want to use
ProcessorFormatter
in yourlogging
configuration.
structlog.types
Module¶
Type information used throughout structlog
.
For now, they are considered provisional. Especially BindableLogger
will
probably change to something more elegant.
New in version 20.2.
-
protocol
structlog.types.
BindableLogger
[source]¶ Methods shared among all bound loggers and that are relied on by
structlog
.New in version 20.2.
Additionally to the methods listed below, bound loggers must have a
__init__
method with the following signature:-
__init__
(self, wrapped_logger: WrappedLogger, processors: Iterable[Processor], context: Context) → None
Unfortunately it’s impossible to define initializers using PEP 544 Protocols.
They currently also have to carry a
Context
as a_context
attribute. This protocol is runtime checkable.Classes that implement this protocol must have the following methods / attributes:
-
bind
(**new_values: Any) → structlog.types.BindableLogger[source]¶
-
new
(**new_values: Any) → structlog.types.BindableLogger[source]¶
-
try_unbind
(*keys: str) → structlog.types.BindableLogger[source]¶
-
unbind
(*keys: str) → structlog.types.BindableLogger[source]¶
-
-
protocol
structlog.types.
FilteringBoundLogger
[source]¶ A
BindableLogger
that filters by a level.Currently, the only way to instantiate one is using
make_filtering_bound_logger
.New in version 20.2.0.
This protocol is runtime checkable.
Classes that implement this protocol must have the following methods / attributes:
-
structlog.types.
EventDict
= typing.MutableMapping[str, typing.Any]¶ An event dictionary as it is passed into processors.
It’s created by copying the configured
Context
but doesn’t need to support copy itself.New in version 20.2.
-
structlog.types.
WrappedLogger
= typing.Any¶ A logger that is wrapped by a bound logger and is ultimately responsible for the output of the log entries.
structlog
makes no assumptions about it.New in version 20.2.
-
structlog.types.
Processor
= typing.Callable[[typing.Any, str, typing.MutableMapping[str, typing.Any]], typing.Union[typing.Mapping[str, typing.Any], str, bytes, typing.Tuple[typing.Any, ...]]]¶ A callable that is part of the processor chain.
See Processors.
New in version 20.2.
-
structlog.types.
Context
= typing.Union[typing.Dict[str, typing.Any], typing.Dict[typing.Any, typing.Any]]¶ A dict-like context carrier.
New in version 20.2.
-
structlog.types.
ExcInfo
= typing.Tuple[typing.Type[BaseException], BaseException, typing.Union[traceback, NoneType]]¶ An exception info tuple as returned by
sys.exc_info
.New in version 20.2.
structlog.twisted
Module¶
Processors and tools specific to the Twisted networking engine.
See also structlog’s Twisted support.
-
class
structlog.twisted.
BoundLogger
(logger: Any, processors: Iterable[Callable[[Any, str, MutableMapping[str, Any]], Union[Mapping[str, Any], str, bytes, Tuple[Any, …]]]], context: Union[Dict[str, Any], Dict[Any, Any]])[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: Any) → structlog._base.BoundLoggerBase¶ Return a new logger with new_values added to the existing ones.
-
err
(event: Optional[str] = None, **kw: Any) → Any[source]¶ Process event and call
log.err()
with the result.
-
msg
(event: Optional[str] = None, **kw: Any) → Any[source]¶ Process event and call
log.msg()
with the result.
-
new
(**new_values: Any) → structlog._base.BoundLoggerBase¶ 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.
-
-
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: Optional[Callable[[Any, str, MutableMapping[str, Any]], str]] = None)[source]¶ Adapt an
event_dict
to Twisted logging system.Particularly, make a wrapped twisted.python.log.err behave as expected.
- Parameters
dictRenderer – 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
(serializer: Callable[[...], Union[str, bytes]] = <function dumps>, **dumps_kw: Any)[source]¶ Behaves like
structlog.processors.JSONRenderer
except that it formats tracebacks and failures itself if called witherr()
.Note
This ultimately means that the messages get logged out using
msg()
, and noterr()
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. Also does not require to be adapted using it.Use together with a
JSONLogObserverWrapper
-wrapped Twisted logger likeplainJSONStdOutLogger
for pure-JSON logs.
-
structlog.twisted.
plainJSONStdOutLogger
() → structlog.twisted.JSONLogObserverWrapper[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: Any) → None[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.