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, bytearray, 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 not None.

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, bytearray, 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 or get_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 returning True.

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 to True, 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, bytearray, 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 or configure_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 returning False 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, bytearray, 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 or 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().

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.

unbind(*keys: str) → structlog._base.BoundLoggerBase¶

Return a new logger with keys removed from the context.

Raises: KeyError – If the key is not part of the context.

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 the structlog.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 like logging.INFO or pass the values directly. See this table from the logging docs for possible values.

New in version 20.2.0.

Changed in version 21.1.0: The returned loggers are now pickleable.

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.

critical(message: str) → None¶: Print message.

debug(message: str) → None¶: Print message.

err(message: str) → None¶: Print message.

error(message: str) → None¶: Print message.

failure(message: str) → None¶: Print message.

fatal(message: str) → None¶: Print message.

info(message: str) → None¶: Print message.

log(message: str) → None¶: Print message.

msg(message: str) → None[source]¶: Print message.

warning(message: str) → None¶: Print message.

class structlog.PrintLoggerFactory(file: Optional[TextIO] = None)[source]¶

Produce PrintLoggers.

To be used with structlog.configure‘s logger_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.

critical(message: bytes) → None¶: Write message.

debug(message: bytes) → None¶: Write message.

err(message: bytes) → None¶: Write message.

error(message: bytes) → None¶: Write message.

failure(message: bytes) → None¶: Write message.

fatal(message: bytes) → None¶: Write message.

info(message: bytes) → None¶: Write message.

log(message: bytes) → None¶: Write message.

msg(message: bytes) → None[source]¶: Write message.

warning(message: bytes) → None¶: Write message.

class structlog.BytesLoggerFactory(file: Optional[BinaryIO] = None)[source]¶

Produce BytesLoggers.

To be used with structlog.configure‘s logger_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, bytearray, 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,
structlog.stdlib.BoundLogger.
structlog.twisted.BoundLogger,

`structlog.dev` Module¶

Helpers that make development with structlog more pleasant.

See also the narrative documentation in Development.

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, exception_formatter: Callable[[TextIO, Tuple[Type[BaseException], BaseException, Optional[types.TracebackType]]], None] = <function plain_traceback>)[source]¶

Render event_dict nicely aligned, possibly in colors, and ordered.

If event_dict contains a true-ish exc_info key, it will be rendered after the log line. If rich or better-exceptions are present, in colors and with extra context.

Parameters

pad_event – Pad the event to this many characters.
colors – Use colors for a nicer output. True by default if colorama is installed.
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 to False is useful if you want to have human-readable non-ASCII output on Python 2. The event key is never repr -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
exception_formatter – A callable to render exc_infos. If rich or better-exceptions are installed, they are used for pretty-printing by default (rich taking precendence). You can also manually set it to plain_traceback, better_traceback, rich_traceback, or implement your own.

Requires the colorama package if colors is True on Windows.

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 as ConsoleRenderer 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.

Changed in version 21.1: It is additionally possible to set the logger name using the logger_name key in the event_dict.

New in version 21.2: exception_formatter

Changed in version 21.2: ConsoleRenderer now handles the exc_info event dict key itself. Do not use the structlog.processors.format_exc_info processor together with ConsoleRenderer anymore! It will keep working, but you can’t have customize exception formatting and a warning will be raised if you ask for it.

Changed in version 21.2: The colors keyword now defaults to True on non-Windows systems, and either True or False in Windows depending on whether colorama is installed.

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’s level_styles parameter. For example, if you are adding custom levels in your home-grown add_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.dev.plain_traceback(sio: TextIO, exc_info: Tuple[Type[BaseException], BaseException, Optional[types.TracebackType]]) → None[source]¶

“Pretty”-print exc_info to sio using our own plain formatter.

To be passed into ConsoleRenderer’s exception_formatter argument.

Used by default if neither rich not better-exceptions are present.

New in version 21.2.

structlog.dev.rich_traceback(sio: TextIO, exc_info: Tuple[Type[BaseException], BaseException, Optional[types.TracebackType]]) → None[source]¶

Pretty-print exc_info to sio using the rich package.

To be passed into ConsoleRenderer’s exception_formatter argument.

Used by default if rich is installed.

New in version 21.2.

structlog.dev.better_traceback(sio: TextIO, exc_info: Tuple[Type[BaseException], BaseException, Optional[types.TracebackType]]) → None[source]¶

Pretty-print exc_info to sio using the better-exceptions package.

To be passed into ConsoleRenderer’s exception_formatter argument.

Used by default if better-exceptions is installed and rich is absent.

New in version 21.2.

structlog.dev.set_exc_info(logger: Any, method_name: str, event_dict: MutableMapping[str, Any]) → MutableMapping[str, Any][source]¶

Set event_dict["exc_info"] = True if method_name is "exception".

Do nothing if the name is different or exc_info is already set.

`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.

Variables: entries (List[structlog.types.EventDict]) – The captured log entries.

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 CapturingLoggers.

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 just args[0] if only one arg passed

debug(*args: Any, **kw: Any) → Any¶: Return tuple of args, kw or just args[0] if only one arg passed

err(*args: Any, **kw: Any) → Any¶: Return tuple of args, kw or just args[0] if only one arg passed

error(*args: Any, **kw: Any) → Any¶: Return tuple of args, kw or just args[0] if only one arg passed

failure(*args: Any, **kw: Any) → Any¶: Return tuple of args, kw or just args[0] if only one arg passed

fatal(*args: Any, **kw: Any) → Any¶: Return tuple of args, kw or just args[0] if only one arg passed

info(*args: Any, **kw: Any) → Any¶: Return tuple of args, kw or just args[0] if only one arg passed

log(*args: Any, **kw: Any) → Any¶: Return tuple of args, kw or just args[0] if only one arg passed

msg(*args: Any, **kw: Any) → Any[source]¶: Return tuple of args, kw or just args[0] if only one arg passed

warning(*args: Any, **kw: Any) → Any¶: Return tuple of args, kw or just args[0] if only one arg passed

class structlog.testing.ReturnLoggerFactory[source]¶

Produce and cache ReturnLoggers.

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.

Modern Approach¶

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.get_threadlocal() → Union[Dict[str, Any], Dict[Any, Any]][source]¶

Return a copy of the current thread-local context.

New in version 21.2.0.

>>> from structlog.threadlocal import bind_threadlocal, get_threadlocal
>>> bind_threadlocal(x=1)
>>> get_threadlocal()
{'x': 1}

structlog.threadlocal.get_merged_threadlocal(bound_logger: structlog.types.BindableLogger) → Union[Dict[str, Any], Dict[Any, Any]][source]¶

Return a copy of the current thread-local context merged with the context from bound_logger.

New in version 21.2.0.

>>> from structlog import get_logger
>>> from structlog.threadlocal import bind_threadlocal, get_merged_threadlocal
>>> bind_threadlocal(x=1)
>>> log = get_logger()
>>> log = log.bind(y=2)
>>> get_merged_threadlocal(log)
{'x': 1, 'y': 2}

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_threadlocal_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.

Old Approach¶

The following APIs use a different approach, that we discourage nowadays. Please see Thread-Local Context for details.

structlog.threadlocal.wrap_dict(dict_class: Type[Union[Dict[str, Any], Dict[Any, Any]]]) → Type[Union[Dict[str, Any], Dict[Any, 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: structlog.threadlocal.TLLogger) → structlog.threadlocal.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.

Changed in version 21.1.0: Reimplemented without using a single dict as context carrier for improved isolation. Every key-value pair is a separate contextvars.ContextVar now.

See Context Variables.

structlog.contextvars.bind_contextvars(**kw: Any) → Mapping[str, contextvars.Token[Any]][source]¶

Put keys and values into the context-local context.

Use this instead of bind() when you want some context to be global (context-local).

Return the mapping of contextvars.Tokens resulting from setting the backing ContextVars. Suitable for passing to reset_contextvars().

New in version 20.1.0.

Changed in version 21.1.0: Return the contextvars.Token mapping rather than None. See also the toplevel note.

structlog.contextvars.get_contextvars() → Dict[str, Any][source]¶: Return a copy of the structlog-specific context-local context.

New in version 21.2.0.

structlog.contextvars.get_merged_contextvars(bound_logger: structlog.types.BindableLogger) → Dict[str, Any][source]¶: Return a copy of the current context-local context merged with the context from bound_logger.

New in version 21.2.0.

structlog.contextvars.merge_contextvars(logger: Any, method_name: str, event_dict: MutableMapping[str, Any]) → MutableMapping[str, 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.

Changed in version 21.1.0: See toplevel note.

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.

Changed in version 21.1.0: See toplevel note.

structlog.contextvars.unbind_contextvars(*keys: str) → None[source]¶

Remove keys from the context-local context if they are present.

Use this instead of unbind() when you want to remove keys from a global (context-local) context.

New in version 20.1.0.

Changed in version 21.1.0: See toplevel note.

structlog.contextvars.reset_contextvars(**kw: contextvars.Token[Any]) → None[source]¶: Reset contextvars corresponding to the given Tokens.

New in version 21.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 using serializer(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 like functools.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 of Key=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 as None.
repr_native_str – When True, repr() is also applied to native strings. Setting this to False 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 from structlog.stdlib.

New in version 15.0.0.

Changed in version 20.2.0: Importable from structlog.processors (additionally to structlog.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 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 is an Exception 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 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.

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 both exception as well as exc_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, or None 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.

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, bytearray, 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 setting exc_info to True.

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, bytearray, Tuple[Any, ...]]]], context: Union[Dict[str, Any], Dict[Any, Any]], *, _sync_bl: Optional[Any] = None, _loop: Optional[Any] = None)[source]¶

Wraps a BoundLogger & exposes its logging methods as async 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.

Changed in version 20.2.0: fix _dispatch_to_sync contextvars usage

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 example structlog.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 for logging.log.

The event field is translated into msg and the rest of the event_dict is added as extra.

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 from structlog.stdlib.

New in version 15.0.0.

Changed in version 20.2.0: Importable from structlog.processors (additionally to structlog.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 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.

class structlog.stdlib.ProcessorFormatter(processor: Callable[[Any, str, MutableMapping[str, Any]], Union[Mapping[str, Any], str, bytes, bytearray, Tuple[Any, ...]]], foreign_pre_chain: Optional[Sequence[Callable[[Any, str, MutableMapping[str, Any]], Union[Mapping[str, Any], str, bytes, bytearray, 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.LogRecords.

This logging.Formatter allows to configure logging to call processor on structlog-borne log entries (origin is determined solely on the fact whether the msg field on the logging.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.Handlers.

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. If None, formatting is left to logging. (default: None)
keep_exc_info – exc_info on logging.LogRecords is added to the event_dict and removed afterwards. Set this to True to keep it on the logging.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 like filter_by_level. (default: None)
pass_foreign_args – If True, pass a foreign log record’s args attribute to the event_dict under positional_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 your logging 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.

class structlog.types.BindableLogger(*args, **kwargs)[source]¶

Protocol: 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.

Note

Currently Sphinx has no support for Protocols, so please click [source] for this entry to see the full definition.

class structlog.types.FilteringBoundLogger(*args, **kwargs)[source]¶

Protocol: A BindableLogger that filters by a level.

The only way to instantiate one is using make_filtering_bound_logger.

New in version 20.2.0.

Note

Currently Sphinx has no support for Protocols, so please click [source] for this entry to see the full definition.

structlog.types.EventDict¶

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.

alias of MutableMapping[str, Any]

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¶

A callable that is part of the processor chain.

See Processors.

New in version 20.2.

alias of Callable[[Any, str, MutableMapping[str, Any]], Union[Mapping[str, Any], str, bytes, bytearray, Tuple[Any, …]]]

structlog.types.Context¶

A dict-like context carrier.

New in version 20.2.

alias of Union[Dict[str, Any], Dict[Any, Any]]

structlog.types.ExcInfo¶

An exception info tuple as returned by sys.exc_info.

New in version 20.2.

alias of Tuple[Type[BaseException], BaseException, Optional[types.TracebackType]]

structlog.types.ExceptionFormatter¶

A callable that pretty-prints an ExcInfo into a file-like object.

Used by structlog.dev.ConsoleRenderer.

New in version 21.2.

alias of Callable[[TextIO, Tuple[Type[BaseException], BaseException, Optional[types.TracebackType]]], None]

`structlog.twisted` Module¶

Processors and tools specific to the Twisted networking engine.

API Reference¶

structlog Package¶

structlog.dev Module¶

structlog.testing Module¶

structlog.threadlocal Module¶

Modern Approach¶

Old Approach¶

structlog.contextvars Module¶

structlog.processors Module¶

structlog.stdlib Module¶

structlog.types Module¶

structlog.twisted Module¶

`structlog` Package¶

`structlog.dev` Module¶

`structlog.testing` Module¶

`structlog.threadlocal` Module¶

`structlog.contextvars` Module¶

`structlog.processors` Module¶

`structlog.stdlib` Module¶

`structlog.types` Module¶

`structlog.twisted` Module¶