API Reference

Note

The examples here use a very simplified configuration using the minimalist 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, **initial_values)

Convenience function that returns a logger according to configuration.

>>> from structlog import get_logger >>> log = get_logger(y=23) >>> log.info("hello", x=42) y=23 x=42 event='hello' 

Parameters:

• args (Any) – Optional positional arguments that are passed unmodified to the logger factory. Therefore it depends on the factory what they mean.

• initial_values (Any) – 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.

Return type:

Any

See Configuration for details.

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

Added 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)

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 (Any) – Values that are used to pre-populate your contexts.

• logger_factory_args (Iterable[Any] | None) – 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.

Return type:

Any

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

Added 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)

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 (Iterable[Callable[[Any, str, MutableMapping[str, Any]], Mapping[str, Any] | str | bytes | bytearray | Tuple[Any, ...]]] | None) – The processor chain. See Processors for details.

• wrapper_class (type[BindableLogger] | None) – Class to use for wrapping loggers instead of structlog.BoundLogger. See Standard Library Logging, Twisted, and Custom wrappers.

• context_class (type[Dict[str, Any] | Dict[Any, Any]] | None) – Class to be used for internal context keeping. The default is a dict and since dictionaries are ordered as of Python 3.6, there’s few reasons to change this option.

• logger_factory (Callable[[...], Any] | None) – Factory to be called to create a new logger that shall be wrapped.

• cache_logger_on_first_use (bool | None) – 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.

Added in version 0.3.0: cache_logger_on_first_use

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

Configures if structlog isn’t configured yet.

It does not matter whether it was configured using configure or configure_once before.

Raises:

RuntimeWarning – if repeated configuration is attempted.

structlog.reset_defaults()

Resets global default values to builtin defaults.

is_configured starts returning False afterwards.

structlog.is_configured()

Return whether structlog has been configured.

If False, structlog is running with builtin defaults.

structlog.get_config()

Get a dictionary with the current configuration.

Note

Changes to the returned dictionary do not affect structlog.

class structlog.BoundLogger(logger, processors, context)

A generic BoundLogger that can wrap anything.

Every unknown method will be passed to the wrapped logger. If that’s too much magic for you, try structlog.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)

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

new(**new_values)

Clear context and binds new_values using bind.

Only necessary with dict implementations that keep global state like those wrapped by structlog.threadlocal.wrap_dict when threads are reused.

unbind(*keys)

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)

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.

All familiar log methods are present, with async variants of each that are prefixed by an a. Therefore, the async version of log.info("hello") is await log.ainfo("hello").

Additionally it has a log(self, level: int, **kw: Any) method to mirror logging.Logger.log and structlog.stdlib.BoundLogger.log.

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.

• You can have (much) more fine-grained filtering by writing a simple processor.

Parameters:

min_level (int | str) –

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.

If you pass a string, it must be one of: critical, error, warning, info, debug, notset (upper/lower case doesn’t matter).

Added in version 20.2.0.

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

Added in version 20.1.0: The log() method.

Added in version 22.2.0: Async variants alog(), adebug(), ainfo(), and so forth.

Changed in version 25.1.0: min_level can now be a string.

structlog.get_context(bound_logger)

Return bound_logger’s context.

The type of bound_logger and the type returned depend on your configuration.

Parameters:

bound_logger (BindableLogger) – The bound logger whose context you want.

Returns:

The actual context from bound_logger. It is not copied first.

Return type:

Dict[str, Any] | Dict[Any, Any]

Added in version 20.2.0.

class structlog.PrintLogger(file=None)

Print events into a file.

Parameters:

file (TextIO | None) – File to print to. (default: sys.stdout)

>>> from structlog import PrintLogger >>> PrintLogger().info("hello") hello 

Useful if you follow current logging best practices.

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

Changed in version 22.1.0: The implementation has been switched to use print for better monkeypatchability.

critical(message)

Print message.

debug(message)

Print message.

err(message)

Print message.

error(message)

Print message.

failure(message)

Print message.

fatal(message)

Print message.

info(message)

Print message.

log(message)

Print message.

msg(message)

Print message.

warning(message)

Print message.

class structlog.PrintLoggerFactory(file=None)

Produce PrintLoggers.

To be used with structlog.configure‘s logger_factory.

Parameters:

file (TextIO | None) – File to print to. (default: sys.stdout)

Positional arguments are silently ignored.

Added in version 0.4.0.

class structlog.WriteLogger(file=None)

Write events into a file.

Parameters:

file (TextIO | None) – File to print to. (default: sys.stdout)

>>> from structlog import WriteLogger >>> WriteLogger().info("hello") hello 

Useful if you follow current logging best practices.

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

A little faster and a little less versatile than structlog.PrintLogger.

Added in version 22.1.0.

critical(message)

Write and flush message.

debug(message)

Write and flush message.

err(message)

Write and flush message.

error(message)

Write and flush message.

failure(message)

Write and flush message.

fatal(message)

Write and flush message.

info(message)

Write and flush message.

log(message)

Write and flush message.

msg(message)

Write and flush message.

warning(message)

Write and flush message.

class structlog.WriteLoggerFactory(file=None)

Produce WriteLoggers.

To be used with structlog.configure‘s logger_factory.

Parameters:

file (TextIO | None) – File to print to. (default: sys.stdout)

Positional arguments are silently ignored.

Added in version 22.1.0.

class structlog.BytesLogger(file=None)

Writes bytes into a file.

Parameters:

file (BinaryIO | None) – 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).

Added in version 20.2.0.

critical(message)

Write message.

debug(message)

Write message.

err(message)

Write message.

error(message)

Write message.

failure(message)

Write message.

fatal(message)

Write message.

info(message)

Write message.

log(message)

Write message.

msg(message)

Write message.

warning(message)

Write message.

class structlog.BytesLoggerFactory(file=None)

Produce BytesLoggers.

To be used with structlog.configure‘s logger_factory.

Parameters:

file (BinaryIO | None) – File to print to. (default: sys.stdout.buffer)

Positional arguments are silently ignored.

Added in version 20.2.0.

exception structlog.DropEvent

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

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

class structlog.BoundLoggerBase(logger, processors, context)

Immutable context carrier.

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

• the generic BoundLogger that can wrap anything,

• structlog.stdlib.BoundLogger.

• structlog.twisted.BoundLogger,

See also Custom wrappers.

_logger: Any

Wrapped logger.

Note

Despite underscore available read-only to custom wrapper classes.

See also Custom wrappers.

_process_event(method_name, event, event_kw)

Combines creates an event_dict and runs the chain.

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

Parameters:

• method_name (str) – The name of the logger method. Is passed into the processors.

• event (str | None) – The event – usually the first positional argument to a logger.

• event_kw (dict[str, Any]) – Additional event keywords. For example if someone calls log.info("foo", bar=42), event would to be "foo" and event_kw {"bar": 42}.

Raises:

• structlog.DropEvent – if log entry should be dropped.

• ValueError – if the final processor doesn’t return a str, bytes, bytearray, tuple, or a dict.

Returns:

tuple of (*args, **kw)

Return type:

tuple[Sequence[Any], Mapping[str, Any]]

Note

Despite underscore available to custom wrapper classes.

See also Custom wrappers.

Changed in version 14.0.0: Allow final processor to return a dict.

Changed in version 20.2.0: Allow final processor to return bytes.

Changed in version 21.2.0: Allow final processor to return a bytearray.

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

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

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

Parameters:

• method_name (str) – The name of the method that’s going to get called. Technically it should be identical to the method the user called because it also get passed into processors.

• event (str | None) – The event – usually the first positional argument to a logger.

• event_kw (Any) – Additional event keywords. For example if someone calls log.info("foo", bar=42), event would to be "foo" and event_kw {"bar": 42}.

Note

Despite underscore available to custom wrapper classes.

See also Custom wrappers.

bind(**new_values)

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

new(**new_values)

Clear context and binds new_values using bind.

Only necessary with dict implementations that keep global state like those wrapped by structlog.threadlocal.wrap_dict when threads are reused.

try_unbind(*keys)

Like unbind(), but best effort: missing keys are ignored.

Added in version 18.2.0.

unbind(*keys)

Return a new logger with keys removed from the context.

Raises:

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

structlog.dev Module

Helpers that make development with structlog more pleasant.

See also the narrative documentation in Console Output.

class structlog.dev.ConsoleRenderer(pad_event_to=30, colors=True, force_colors=False, repr_native_str=False, level_styles=None, exception_formatter=<function plain_traceback>, sort_keys=True, event_key='event', timestamp_key='timestamp', columns=None, pad_level=True, pad_event=None)

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.

Tip

Since ConsoleRenderer is mainly a development helper, it is less strict about immutability than the rest of structlog for better ergonomics. Notably, the currently active instance can be obtained by calling ConsoleRenderer.get_active() and it offers properties to configure its behavior after instantiation.

Parameters:

• columns (list[Column] | None) –

  A list of Column objects defining both the order and format of the key-value pairs in the output. If passed, most other arguments become meaningless.

  Must contain a column with key='' that defines the default formatter.

  See also

  Console output configuration

• pad_event_to (int) – Pad the event to this many characters. Ignored if columns are passed.

• colors (bool) – Use colors for a nicer output. True by default. On Windows only if Colorama is installed. Ignored if columns are passed.

• force_colors (bool) – 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. Only meaningful on Windows. Ignored if columns are passed.

• repr_native_str (bool) – When True, repr is also applied to strs. The event key is never repr -ed. Ignored if columns are passed.

• level_styles (dict[str, str] | None) – When present, use these styles for colors. This must be a dict from level names (strings) to terminal sequences (for example, Colorama) styles. The default can be obtained by calling ConsoleRenderer.get_default_level_styles. Ignored when columns are passed.

• exception_formatter (ExceptionRenderer) – A callable to render exc_infos. If Rich or better-exceptions are installed, they are used for pretty-printing by default (rich taking precedence). You can also manually set it to plain_traceback, better_traceback, an instance of RichTracebackFormatter like rich_traceback, or implement your own.

• sort_keys (bool) – Whether to sort keys when formatting. True by default. Ignored if columns are passed.

• event_key (str) – The key to look for the main log message. Needed when you rename it e.g. using structlog.processors.EventRenamer. Ignored if columns are passed.

• timestamp_key (str) – The key to look for timestamp of the log message. Needed when you rename it e.g. using structlog.processors.EventRenamer. Ignored if columns are passed.

• pad_level (bool) – Whether to pad log level with blanks to the longest amongst all level label.

Requires the Colorama package if colors is True on Windows.

Raises:

ValueError – If there’s not exactly one default column formatter.

Added in version 16.0.0.

Added in version 16.1.0: colors

Added in version 17.1.0: repr_native_str

Added in version 18.1.0: force_colors

Added in version 18.1.0: level_styles

Changed in version 19.2.0: Colorama now initializes lazily to avoid unwanted initializations as ConsoleRenderer is used by default.

Changed in version 19.2.0: Can be pickled now.

Changed in version 20.1.0: Colorama does not initialize lazily on Windows anymore because it breaks rendering.

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

Added in version 21.2.0: exception_formatter

Changed in version 21.2.0: 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.0: The colors keyword now defaults to True on non-Windows systems, and either True or False in Windows depending on whether Colorama is installed.

Added in version 21.3.0: sort_keys

Added in version 22.1.0: event_key

Added in version 23.2.0: timestamp_key

Added in version 23.3.0: columns

Added in version 24.2.0: pad_level

property colors: bool

Whether to use colorful output styles.

Setting this will update the renderer’s styles immediately and reset level styles to the defaults according to the new color setting – even if the color value is the same.

Added in version 25.5.0.

property columns: list[Column]

The columns configuration for this console renderer.

Warning

Just like with passing columns argument, many of the other arguments you may have passed are ignored.

Parameters:

value –

A list of Column objects defining both the order and format of the key-value pairs in the output.

Must contain a column with key='' that defines the default formatter.

Raises:

ValueError – If there’s not exactly one default column formatter.

Added in version 25.5.0.

property event_key: str

The key to look for the main log message.

Setting this will rebuild columns to reflect the change.

Added in version 25.5.0.

property exception_formatter: Callable[[TextIO, Tuple[Type[BaseException], BaseException, TracebackType | None]], None]

The exception formatter used by this console renderer.

Added in version 25.5.0.

property force_colors: bool

Force colorful output even in non-interactive environments.

Setting this will update the renderer’s styles immediately and reset level styles to the defaults according to the current color setting – even if the value is the same.

Added in version 25.5.0.

classmethod get_active()

If structlog is configured to use ConsoleRenderer, it’s returned.

It does not have to be the last processor.

Raises:

• NoConsoleRendererConfiguredError – If no ConsoleRenderer is found in the current configuration.

• MultipleConsoleRenderersConfiguredError – If more than one is found in the current configuration. This is almost certainly a bug.

Added in version 25.5.0.

classmethod get_default_column_styles(colors, force_colors=False)

Configure and return the appropriate styles class for console output.

This method handles the setup of colorful or plain styles, including proper colorama initialization on Windows systems when colors are enabled.

Parameters:

• colors (bool) – Whether to use colorful output styles.

• force_colors (bool) – Force colorful output even in non-interactive environments. Only relevant on Windows with colorama.

Returns:

The configured styles.

Raises:

SystemError – On Windows when colors=True but colorama is not installed.

Return type:

ColumnStyles

Added in version 25.5.0.

static get_default_level_styles(colors=True)

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 (bool) – Whether to use colorful styles. This must match the colors parameter to ConsoleRenderer. Default: True.

property level_styles: dict[str, str]

The level styles mapping for this console renderer.

Setting this property will reset to defaults if set to None, otherwise it applies the provided mapping. In all cases, columns are rebuilt to reflect the change.

Added in version 25.5.0.

property pad_event_to: int

The number of characters to pad the event to.

Setting this will rebuild columns to reflect the change.

Added in version 25.5.0.

property pad_level: bool

Whether to pad log level with blanks to the longest amongst all level labels.

Setting this will rebuild columns to reflect the change.

Added in version 25.5.0.

property repr_native_str: bool

Whether native strings are passed through repr() in non-event values.

Added in version 25.5.0.

property sort_keys: bool

Whether to sort keys when formatting.

Added in version 25.5.0.

property timestamp_key: str

The key to look for the timestamp of the log message.

Setting this will rebuild columns to reflect the change.

Added in version 25.5.0.

class structlog.dev.ColumnStyles(reset, bright, level_critical, level_exception, level_error, level_warn, level_info, level_debug, level_notset, timestamp, logger_name, kv_key, kv_value)

Column styles settings for console rendering.

These are console ANSI codes that are printed before the respective fields. This allows for a certain amount of customization if you don’t want to configure your columns.

Added in version 25.5.0: It was handled by private structures before.

exception structlog.dev.NoConsoleRendererConfiguredError

A user asked for the current structlog.dev.ConsoleRenderer but none is configured.

Added in version 25.5.0.

exception structlog.dev.MultipleConsoleRenderersConfiguredError

A user asked for the current structlog.dev.ConsoleRenderer and more than one is configured.

Added in version 25.5.0.

class structlog.dev.Column(key, formatter)

A column defines the way a key-value pair is formatted, and, by it’s position to the columns argument of ConsoleRenderer, the order in which it is rendered.

Parameters:

• key (str) – The key for which this column is responsible. Leave empty to define it as the default formatter.

• formatter (ColumnFormatter) – The formatter for columns with key.

Added in version 23.3.0.

class structlog.dev.ColumnFormatter(typing.Protocol)

Protocol for column formatters.

See KeyValueColumnFormatter and LogLevelColumnFormatter for examples.

Added in version 23.3.0.

__call__(key, value)

Format value for key.

This method is responsible for formatting, key, the =, and the value. That means that it can use any string instead of the = and it can leave out both the key or the value.

If it returns an empty string, the column is omitted completely.

class structlog.dev.KeyValueColumnFormatter(key_style, value_style, reset_style, value_repr, width=0, prefix='', postfix='')

Format a key-value pair.

Parameters:

• key_style (str | None) – The style to apply to the key. If None, the key is omitted.

• value_style (str) – The style to apply to the value.

• reset_style (str) – The style to apply whenever a style is no longer needed.

• value_repr (Callable[[object], str]) – A callable that returns the string representation of the value.

• width (int) – The width to pad the value to. If 0, no padding is done.

• prefix (str) – A string to prepend to the formatted key-value pair. May contain styles.

• postfix (str) – A string to append to the formatted key-value pair. May contain styles.

Added in version 23.3.0.

class structlog.dev.LogLevelColumnFormatter(level_styles, reset_style, width=None)

Format a log level according to level_styles.

The width is padded to the longest level name (if level_styles is passed – otherwise there’s no way to know the lengths of all levels).

Parameters:

• level_styles (dict[str, str] | None) – A dictionary of level names to styles that are applied to it. If None, the level is formatted as a plain [level].

• reset_style (str) – What to use to reset the style after the level name. Ignored if if level_styles is None.

• width (int) – The width to pad the level to. If 0, no padding is done.

Added in version 23.3.0.

Added in version 24.2.0: width

structlog.dev.plain_traceback(sio, exc_info)

“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 nor better-exceptions are present.

Added in version 21.2.0.

class structlog.dev.RichTracebackFormatter(color_system='truecolor', show_locals=True, max_frames=100, theme=None, word_wrap=True, extra_lines=3, width=None, code_width=88, indent_guides=True, locals_max_length=10, locals_max_string=80, locals_hide_dunder=True, locals_hide_sunder=False, suppress=())

A Rich traceback renderer with the given options.

Pass an instance as ConsoleRenderer’s exception_formatter argument.

See rich.traceback.Traceback for details on the arguments.

If width is None, the terminal width is used. If the width can’t be determined, fall back to 80.

Added in version 23.2.0.

Changed in version 25.4.0: Default width is None to have full width and reflow support. Passing -1 as width is deprecated, use None instead. word_wrap is now True by default.

Added in version 25.4.0: code_width

structlog.dev.rich_traceback(*args, **kw)

Pretty-print exc_info to sio using the Rich package.

To be passed into ConsoleRenderer’s exception_formatter argument.

This is a RichTracebackFormatter with default arguments and used by default if Rich is installed.

Added in version 21.2.0.

structlog.dev.better_traceback(sio, exc_info)

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.

Added in version 21.2.0.

structlog.dev.set_exc_info(logger, method_name, event_dict)

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

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

Added in version 19.2.0.

structlog.testing Module

Helpers to test your application’s logging behavior.

Added in version 20.1.0.

See Testing.

structlog.testing.capture_logs(processors=())

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!

Parameters:

processors (Iterable[Callable[[Any, str, MutableMapping[str, Any]], Mapping[str, Any] | str | bytes | bytearray | Tuple[Any, ...]]]) – Processors to apply before the logs are captured.

Added in version 20.1.0.

Added in version 25.5.0: processors parameter

class structlog.testing.LogCapture

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.typing.EventDict]) – The captured log entries.

Added in version 20.1.0.

Changed in version 24.3.0: Added mapping from “exception” to “error” Added mapping from “warn” to “warning”

class structlog.testing.CapturingLogger

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.

Added in version 20.2.0.

>>> from pprint import pprint >>> cl = structlog.testing.CapturingLogger() >>> cl.info("hello") >>> cl.info("hello", when="again") >>> pprint(cl.calls) [CapturedCall(method_name='info', args=('hello',), kwargs={}),  CapturedCall(method_name='info', args=('hello',), kwargs={'when': 'again'})] 

class structlog.testing.CapturingLoggerFactory

Produce and cache CapturingLoggers.

Each factory produces and reuses 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.

Added in version 20.2.0.

class structlog.testing.CapturedCall(method_name, args, kwargs)

A call as captured by CapturingLogger.

Can also be unpacked like a tuple.

Parameters:

• method_name (str) – The method name that got called.

• args (tuple[Any, ...]) – A tuple of the positional arguments.

• kwargs (dict[str, Any]) – A dict of the keyword arguments.

Added in version 20.2.0.

class structlog.testing.ReturnLogger

Return the arguments that it’s called with.

>>> from structlog import ReturnLogger >>> ReturnLogger().info("hello") 'hello' >>> ReturnLogger().info("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, **kw)

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

debug(*args, **kw)

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

err(*args, **kw)

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

error(*args, **kw)

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

failure(*args, **kw)

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

fatal(*args, **kw)

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

info(*args, **kw)

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

log(*args, **kw)

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

msg(*args, **kw)

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

warning(*args, **kw)

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

class structlog.testing.ReturnLoggerFactory

Produce and cache ReturnLoggers.

To be used with structlog.configure‘s logger_factory.

Positional arguments are silently ignored.

Added in version 0.4.0.

structlog.contextvars Module

Primitives to deal with a concurrency supporting context, as introduced in Python 3.7 as contextvars.

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

Changed in version 23.3.0: Callsite parameters are now also collected under asyncio.

See Context Variables.

structlog.contextvars.bind_contextvars(**kw)

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().

Added 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.bound_contextvars(**kw)

Bind kw to the current context-local context. Unbind or restore kw afterwards. Do not affect other keys.

Can be used as a context manager or decorator.

Added in version 21.4.0.

structlog.contextvars.get_contextvars()

Return a copy of the structlog-specific context-local context.

Added in version 21.2.0.

structlog.contextvars.get_merged_contextvars(bound_logger)

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

Added in version 21.2.0.

structlog.contextvars.merge_contextvars(logger, method_name, event_dict)

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.

Added in version 20.1.0.

Changed in version 21.1.0: See toplevel note.

structlog.contextvars.clear_contextvars()

Clear the context-local context.

The typical use-case for this function is to invoke it early in request- handling code.

Added in version 20.1.0.

Changed in version 21.1.0: See toplevel note.

structlog.contextvars.unbind_contextvars(*keys)

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.

Added in version 20.1.0.

Changed in version 21.1.0: See toplevel note.

structlog.contextvars.reset_contextvars(**kw)

Reset contextvars corresponding to the given Tokens.

Added in version 21.1.0.

structlog.threadlocal Module

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

See Legacy Thread-local Context, but please use Context Variables instead.

Deprecated since version 22.1.0.

structlog.processors Module

Processors useful regardless of the logging framework.

class structlog.processors.JSONRenderer(serializer=<function dumps>, **dumps_kw)

Render the event_dict using serializer(event_dict, **dumps_kw).

Parameters:

• dumps_kw (Any) – Are passed unmodified to serializer. If default is passed, it will disable support for __structlog__-based serialization.

• serializer (Callable[..., str | bytes]) –

  A json.dumps()-compatible callable that will be used to format the string. This can be used to use alternative JSON encoders (default: json.dumps()).

  See also

  Performance for examples.

Added in version 0.2.0: Support for __structlog__ serialization method.

Added in version 15.4.0: serializer parameter.

Added in version 18.2.0: Serializer’s default parameter can be overwritten now.

>>> from structlog.processors import JSONRenderer >>> JSONRenderer(sort_keys=True)(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, "", {"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 dumps_kw, support for __structlog__ is disabled. That can be useful with more elegant serialization methods like functools.singledispatch: Better Python Object Serialization. It can also be helpful if you are using orjson and want to rely on it to serialize datetime.datetime and other objects natively.

Tip

If you use this processor, you may also wish to add structured tracebacks for exceptions. You can do this by adding the dict_tracebacks to your list of processors:

>>> structlog.configure( ...  processors=[ ...  structlog.processors.dict_tracebacks, ...  structlog.processors.JSONRenderer(), ...  ], ... ) >>> log = structlog.get_logger() >>> var = "spam" >>> try: ...  1 / 0 ... except ZeroDivisionError: ...  log.exception("Cannot compute!") {"event": "Cannot compute!", "exception": [{"exc_type": "ZeroDivisionError", "exc_value": "division by zero", "exc_notes": [], "syntax_error": null, "is_cause": false, "frames": [{"filename": "<doctest default[3]>", "lineno": 2, "name": "<module>", "locals": {..., "var": "'spam'"}}], "is_group": false, "exceptions": []}]} 

class structlog.processors.KeyValueRenderer(sort_keys=False, key_order=None, drop_missing=False, repr_native_str=True)

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

Parameters:

• sort_keys (bool) – Whether to sort keys when formatting.

• key_order (Sequence[str] | None) – 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 (bool) – When True, extra keys in key_order will be dropped rather than rendered as None.

• repr_native_str (bool) – When True, repr() is also applied to native strings.

Added in version 0.2.0: key_order

Added in version 16.1.0: drop_missing

Added in version 17.1.0: repr_native_str

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

class structlog.processors.LogfmtRenderer(sort_keys=False, key_order=None, drop_missing=False, bool_as_flag=True)

Render event_dict using the logfmt format.

Parameters:

• sort_keys (bool) – Whether to sort keys when formatting.

• key_order (Sequence[str] | None) – List of keys that should be rendered in this exact order. Missing keys are rendered with empty values, extra keys depending on sort_keys and the dict class.

• drop_missing (bool) – When True, extra keys in key_order will be dropped rather than rendered with empty values.

• bool_as_flag (bool) – When True, render {"flag": True} as flag, instead of flag=true. {"flag": False} is always rendered as flag=false.

Raises:

ValueError – If a key contains non-printable or whitespace characters.

Added in version 21.5.0.

>>> from structlog.processors import LogfmtRenderer >>> event_dict = {"a": 42, "b": [1, 2, 3], "flag": True} >>> LogfmtRenderer(sort_keys=True)(None, "", event_dict) 'a=42 b="[1, 2, 3]" flag' >>> LogfmtRenderer(key_order=["b", "a"], bool_as_flag=False)(None, "", event_dict) 'b="[1, 2, 3]" a=42 flag=true' 

class structlog.processors.EventRenamer(to, replace_by=None)

Rename the event key in event dicts.

This is useful if you want to use consistent log message keys across platforms and/or use the event key for something custom.

Warning

It’s recommended to put this processor right before the renderer, since some processors may rely on the presence and meaning of the event key.

Parameters:

• to (str) – Rename event_dict["event"] to event_dict[to]

• replace_by (str | None) – Rename event_dict[replace_by] to event_dict["event"]. replace_by missing from event_dict is handled gracefully.

Added in version 22.1.0.

See also the Renaming the event key recipe.

structlog.processors.add_log_level(logger, method_name, event_dict)

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.

Added in version 15.0.0.

Changed in version 20.2.0: Importable from structlog.processors (additionally to structlog.stdlib).

Changed in version 24.1.0: Added mapping from “exception” to “error”

class structlog.processors.UnicodeDecoder(encoding='utf-8', errors='replace')

Decode byte string values in event_dict.

Parameters:

• encoding (str) – Encoding to decode from (default: "utf-8").

• errors (str) – How to cope with encoding errors (default: "replace").

Useful to prevent b"abc" being rendered as as 'b"abc"'.

Just put it in the processor chain before the renderer.

Added in version 15.4.0.

class structlog.processors.UnicodeEncoder(encoding='utf-8', errors='backslashreplace')

Encode unicode values in event_dict.

Parameters:

• encoding (str) – Encoding to encode to (default: "utf-8").

• errors (str) – How to cope with encoding errors (default "backslashreplace").

Just put it in the processor chain before the renderer.

Note

Not very useful in a Python 3-only world.

class structlog.processors.ExceptionRenderer(exception_formatter=<function _format_exception>)

Replace an exc_info field with an exception field which is rendered by exception_formatter.

The contents of the exception field depends on the return value of the exception_formatter that is passed:

• The default produces a formatted string via Python’s built-in traceback formatting (this is format_exc_info).

• If you pass a ExceptionDictTransformer, it becomes a list of stack dicts that can be serialized to JSON.

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

1. If the value is a tuple, render it into the key exception.

2. If the value is an Exception render it into the key exception.

3. 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 analog to the one of the stdlib’s logging.

Parameters:

exception_formatter (ExceptionTransformer) – A callable that is used to format the exception from the exc_info field into the exception field.

See also

Exceptions for a broader explanation of structlog’s exception features.

Added in version 22.1.0.

structlog.processors.format_exc_info(logger, name, event_dict)

Replace an exc_info field with an exception string field using Python’s built-in traceback formatting.

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

1. If the value is a tuple, render it into the key exception.

2. If the value is an Exception render it into the key exception.

3. If the value is 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 analog to the one of the stdlib’s logging.

See also

Exceptions for a broader explanation of structlog’s exception features.

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

structlog.processors.dict_tracebacks(logger, name, event_dict)

Replace an exc_info field with an exception field containing structured tracebacks suitable for, e.g., JSON output.

It is a shortcut for ExceptionRenderer with a ExceptionDictTransformer.

The treatment of the exc_info key is identical to format_exc_info.

Added in version 22.1.0.

See also

Exceptions for a broader explanation of structlog’s exception features.

>>> from structlog.processors import dict_tracebacks >>> try: ...  raise ValueError("onoes") ... except ValueError: ...  dict_tracebacks(None, "", {"exc_info": True}) {'exception': [{'exc_type': 'ValueError', 'exc_value': 'onoes', ..., 'frames': [{'filename': ... 

class structlog.processors.StackInfoRenderer(additional_ignores=None)

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 and works analogously to the stack_info argument of the Python standard library logging.

Parameters:

additional_ignores (list[str] | None) – By default, stack frames coming from structlog are ignored. With this argument you can add additional names that are ignored, before the stack starts being rendered. They are matched using startswith(), so they don’t have to match exactly. The names are used to find the first relevant name, therefore once a frame is found that doesn’t start with structlog or one of additional_ignores, no filtering is applied to subsequent frames.

Added in version 0.4.0.

Added in version 22.1.0: additional_ignores

class structlog.processors.ExceptionPrettyPrinter(file=None, exception_formatter=<function _format_exception>)

Pretty print exceptions rendered by exception_formatter and remove them from the event_dict.

Parameters:

• file (TextIO | None) – Target file for output (default: sys.stdout).

• exception_formatter (ExceptionTransformer) – A callable that is used to format the exception from the exc_info field into the exception field.

This processor is mostly for development and testing so you can read exceptions properly formatted.

It behaves like format_exc_info, except that it removes the exception data from the event dictionary after printing it using the passed exception_formatter, which defaults to Python’s built-in traceback formatting.

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.

Added in version 0.4.0.

Changed in version 16.0.0: Added support for passing exceptions as exc_info on Python 3.

Changed in version 25.4.0: Fixed exception_formatter so that it overrides the default if set.

class structlog.processors.TimeStamper(fmt=None, utc=True, key='timestamp')

Add a timestamp to event_dict.

Parameters:

• fmt (str | None) – 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.

Changed in version 19.2.0: Can be pickled now.

>>> from structlog.processors import TimeStamper >>> TimeStamper()(None, "", {}) {'timestamp': 1378994017} >>> TimeStamper(fmt="iso")(None, "", {}) {'timestamp': '2013-09-12T13:54:26.996778Z'} >>> TimeStamper(fmt="%Y", key="year")(None, "", {}) {'year': '2013'} 

class structlog.processors.MaybeTimeStamper(fmt=None, utc=True, key='timestamp')

A timestamper that only adds a timestamp if there is none.

This allows you to overwrite the timestamp key in the event dict for example when the event is coming from another system.

It takes the same arguments as TimeStamper.

Added in version 23.2.0.

>>> from structlog.processors import MaybeTimeStamper >>> MaybeTimeStamper()(None, "", {}) {'timestamp': 1690036074.494428} >>> MaybeTimeStamper()(None, "", {"timestamp": 42}) {'timestamp': 42} 

class structlog.processors.CallsiteParameter(*values)

Callsite parameters that can be added to an event dictionary with the structlog.processors.CallsiteParameterAdder processor class.

The string values of the members of this enum will be used as the keys for the callsite parameters in the event dictionary.

Added in version 21.5.0.

Added in version 25.5.0: QUAL_NAME parameter.

FILENAME = 'filename'

The basename part of the full path to the python source file of the callsite.

FUNC_NAME = 'func_name'

The name of the function that the callsite was in.

LINENO = 'lineno'

The line number of the callsite.

MODULE = 'module'

The python module the callsite was in. This mimics the module attribute of logging.LogRecord objects and will be the basename, without extension, of the full path to the python source file of the callsite.

PATHNAME = 'pathname'

The full path to the python source file of the callsite.

PROCESS = 'process'

The ID of the process the callsite was executed in.

PROCESS_NAME = 'process_name'

The name of the process the callsite was executed in.

QUAL_NAME = 'qual_name'

The qualified name of the callsite (includes scope and class names). Requires Python 3.11+.

THREAD = 'thread'

The ID of the thread the callsite was executed in.

THREAD_NAME = 'thread_name'

The name of the thread the callsite was executed in.

class structlog.processors.CallsiteParameterAdder(parameters={CallsiteParameter.FILENAME, CallsiteParameter.FUNC_NAME, CallsiteParameter.LINENO, CallsiteParameter.MODULE, CallsiteParameter.PATHNAME, CallsiteParameter.PROCESS, CallsiteParameter.PROCESS_NAME, CallsiteParameter.QUAL_NAME, CallsiteParameter.THREAD, CallsiteParameter.THREAD_NAME}, additional_ignores=None)

Adds parameters of the callsite that an event dictionary originated from to the event dictionary. This processor can be used to enrich events dictionaries with information such as the function name, line number and filename that an event dictionary originated from.

If the event dictionary has an embedded logging.LogRecord object and did not originate from structlog then the callsite information will be determined from the logging.LogRecord object. For event dictionaries without an embedded logging.LogRecord object the callsite will be determined from the stack trace, ignoring all intra-structlog calls, calls from the logging module, and stack frames from modules with names that start with values in additional_ignores, if it is specified.

The keys used for callsite parameters in the event dictionary are the string values of CallsiteParameter enum members.

Parameters:

• parameters (Collection[CallsiteParameter]) – A collection of CallsiteParameter values that should be added to the event dictionary.

• additional_ignores (list[str] | None) – Additional names with which a stack frame’s module name must not start for it to be considered when determening the callsite.

Note

When used with structlog.stdlib.ProcessorFormatter the most efficient configuration is to either use this processor in foreign_pre_chain of structlog.stdlib.ProcessorFormatter and in processors of structlog.configure, or to use it in processors of structlog.stdlib.ProcessorFormatter without using it in processors of structlog.configure and foreign_pre_chain of structlog.stdlib.ProcessorFormatter.

Added in version 21.5.0.

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.recreate_defaults(*, log_level=0)

Recreate defaults on top of standard library’s logging.

The output looks the same, but goes through logging.

As with vanilla defaults, the backwards-compatibility guarantees don’t apply to the settings applied here.

Parameters:

log_level (int | None) –

If None, don’t configure standard library logging at all.

Otherwise configure it to log to sys.stdout at log_level (logging.NOTSET being the default).

If you need more control over logging, pass None here and configure it yourself.

Added in version 22.1.0.

Changed in version 23.3.0: Added add_logger_name.

Changed in version 25.1.0: Added PositionalArgumentsFormatter.

structlog.stdlib.get_logger(*args, **initial_values)

Only calls structlog.get_logger, but has the correct type hints.

Warning

Does not check whether – or ensure that – you’ve configured structlog for standard library logging!

See Standard Library Logging for details.

Added in version 20.2.0.

class structlog.stdlib.BoundLogger(logger, processors, context)

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.

Added in version 23.1.0: Async variants alog(), adebug(), ainfo(), and so forth.

Changed in version 24.2.0: Callsite parameters are now also collected by structlog.processors.CallsiteParameterAdder for async log methods.

async acritical(event, *args, **kw)

Log using critical(), but asynchronously in a separate thread.

Added in version 23.1.0.

async adebug(event, *args, **kw)

Log using debug(), but asynchronously in a separate thread.

Added in version 23.1.0.

async aerror(event, *args, **kw)

Log using error(), but asynchronously in a separate thread.

Added in version 23.1.0.

async aexception(event, *args, **kw)

Log using exception(), but asynchronously in a separate thread.

Added in version 23.1.0.

async ainfo(event, *args, **kw)

Log using info(), but asynchronously in a separate thread.

Added in version 23.1.0.

async alog(level, event, *args, **kw)

Log using log(), but asynchronously in a separate thread.

Added in version 23.1.0.

async awarning(event, *args, **kw)

Log using warning(), but asynchronously in a separate thread.

Added in version 23.1.0.

bind(**new_values)

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

critical(event=None, *args, **kw)

Process event and call logging.Logger.critical with the result.

debug(event=None, *args, **kw)

Process event and call logging.Logger.debug with the result.

error(event=None, *args, **kw)

Process event and call logging.Logger.error with the result.

exception(event=None, *args, **kw)

Process event and call logging.Logger.exception with the result, after setting exc_info to True if it’s not already set.

info(event=None, *args, **kw)

Process event and call logging.Logger.info with the result.

log(level, event=None, *args, **kw)

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

try_unbind(*keys)

Like unbind(), but best effort: missing keys are ignored.

Added in version 18.2.0.

unbind(*keys)

Return a new logger with keys removed from the context.

Raises:

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

warn(event=None, *args, **kw)

Process event and call logging.Logger.warning with the result.

warning(event=None, *args, **kw)

Process event and call logging.Logger.warning with the result.

class structlog.stdlib.AsyncBoundLogger(logger, processors, context, *, _sync_bl=None, _loop=None)

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.

Added in version 20.2.0.

Changed in version 20.2.0: fix _dispatch_to_sync contextvars usage

Deprecated since version 23.1.0: Use the regular BoundLogger with its a-prefixed methods instead.

Changed in version 23.3.0: Callsite parameters are now also collected for async log methods.

sync_bl: BoundLogger

The wrapped synchronous logger. It is useful to be able to log synchronously occasionally.

class structlog.stdlib.LoggerFactory(ignore_frame_names=None)

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[str] | None) – 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"]. This argument is called additional_ignores in other APIs throughout structlog.

__call__(*args)

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_args_and_kwargs(_, __, event_dict)

Render event_dict into positional and keyword arguments for logging.Logger logging methods. See logging.Logger.debug method for keyword arguments reference.

The event field is passed in the first positional argument, positional arguments from positional_args field are passed in subsequent positional arguments, keyword arguments are extracted from the event_dict and the rest of the event_dict is added as extra.

This allows you to defer formatting to logging.

Added in version 25.1.0.

structlog.stdlib.render_to_log_kwargs(_, __, event_dict)

Render event_dict into keyword arguments for logging.Logger logging methods. See logging.Logger.debug method for keyword arguments reference.

The event field is translated into msg, keyword arguments are extracted from the event_dict and the rest of the event_dict is added as extra.

This allows you to defer formatting to logging.

Added in version 17.1.0.

Changed in version 22.1.0: exc_info, stack_info, and stacklevel are passed as proper kwargs and not put into extra.

Changed in version 24.2.0: stackLevel corrected to stacklevel.

structlog.stdlib.filter_by_level(logger, method_name, event_dict)

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)

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.

Added in version 15.0.0.

Changed in version 20.2.0: Importable from structlog.processors (additionally to structlog.stdlib).

Changed in version 24.1.0: Added mapping from “exception” to “error”

structlog.stdlib.add_log_level_number(logger, method_name, event_dict)

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.

Added in version 18.2.0.

structlog.stdlib.add_logger_name(logger, method_name, event_dict)

Add the logger name to the event dict.

class structlog.stdlib.ExtraAdder(allow=None)

Add extra attributes of logging.LogRecord objects to the event dictionary.

This processor can be used for adding data passed in the extra parameter of the logging module’s log methods to the event dictionary.

Parameters:

allow (Collection[str] | None) –

An optional collection of attributes that, if present in logging.LogRecord objects, will be copied to event dictionaries.

If allow is None all attributes of logging.LogRecord objects that do not exist on a standard logging.LogRecord object will be copied to event dictionaries.

Added in version 21.5.0.

class structlog.stdlib.PositionalArgumentsFormatter(remove_positional_args=True)

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=None, processors=(), foreign_pre_chain=None, keep_exc_info=False, keep_stack_info=False, logger=None, pass_foreign_args=False, use_get_message=True, *args, **kwargs)

Call structlog processors on logging.LogRecords.

This is an implementation of a logging.Formatter that can be used to format log entries from both structlog and logging.

Its static method wrap_for_formatter must be the final processor in structlog’s processor chain.

Please refer to Rendering using structlog-based formatters within logging for examples.

Parameters:

• foreign_pre_chain (Sequence[Processor] | None) – If not None, it is used as a processor chain that is applied to non-structlog log entries before the event dictionary is passed to processors. (default: None)

• processors (Sequence[Processor] | None) –

  A chain of structlog processors that is used to process all log entries. The last one must render to a str which then gets passed on to logging for output.

  Compared to structlog’s regular processor chains, there’s a few differences:

  • The event dictionary contains two additional keys:

    1. _record: a logging.LogRecord that either was created

       using logging APIs, or is a wrapped structlog log entry created by wrap_for_formatter.

    2. _from_structlog: a bool that indicates whether or not _record was created by a structlog logger.

    Since you most likely don’t want _record and _from_structlog in your log files, we’ve added the static method remove_processors_meta to ProcessorFormatter that you can add just before your renderer.

  • Since this is a logging formatter, raising structlog.DropEvent will crash your application.

• keep_exc_info (bool) – 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 (bool) – Same as keep_exc_info except for stack_info. (default: False)

• logger (logging.Logger | None) – 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 (bool) – If True, pass a foreign log record’s args attribute to the event_dict under positional_args key. (default: False)

• processor (Processor | None) –

  A single structlog processor used for rendering the event dictionary before passing it off to logging. Must return a str. The event dictionary does not contain _record and _from_structlog.

  This parameter exists for historic reasons. Please use processors instead.

• use_get_message (bool) – If True, use record.getMessage to get a fully rendered log message, otherwise use str(record.msg). (default: True)

Raises:

TypeError – If both or neither processor and processors are passed.

Added in version 17.1.0.

Added in version 17.2.0: keep_exc_info and keep_stack_info

Added in version 19.2.0: logger

Added in version 19.2.0: pass_foreign_args

Added in version 21.3.0: processors

Deprecated since version 21.3.0: processor (singular) in favor of processors (plural). Removal is not planned.

Added in version 23.3.0: use_get_message

static remove_processors_meta(_, __, event_dict)

Remove _record and _from_structlog from event_dict.

These keys are added to the event dictionary, before ProcessorFormatter’s processors are run.

Added in version 21.3.0.

static wrap_for_formatter(logger, name, event_dict)

Wrap logger, name, and event_dict.

The result is later unpacked by ProcessorFormatter when formatting log entries.

Use this static method as the renderer (in other words, final processor) if you want to use ProcessorFormatter in your logging configuration.

structlog.tracebacks Module

Extract a structured traceback from an exception.

Based on work by Will McGugan <hynek/structlog#407>`_ from rich.traceback.

structlog.tracebacks.extract(exc_type, exc_value, traceback, *, show_locals=False, locals_max_length=10, locals_max_string=80, locals_hide_dunder=True, locals_hide_sunder=False, use_rich=True, _seen=None)

Extract traceback information.

Parameters:

• exc_type (type[BaseException]) – Exception type.

• exc_value (BaseException) – Exception value.

• traceback (TracebackType | None) – Python Traceback object.

• show_locals (bool) – Enable display of local variables. Defaults to False.

• locals_max_length (int) – Maximum length of containers before abbreviating, or None for no abbreviation.

• locals_max_string (int) – Maximum length of string before truncating, or None to disable truncating.

• locals_hide_dunder (bool) – Hide locals prefixed with double underscore. Defaults to True.

• locals_hide_sunder (bool) – Hide locals prefixed with single underscore. This implies hiding locals_hide_dunder. Defaults to False.

• use_rich (bool) – If True (the default), use rich to compute the repr. If False or if rich is not installed, fall back to a simpler algorithm.

Returns:

A Trace instance with structured information about all exceptions.

Return type:

Trace

Added in version 22.1.0.

Changed in version 24.3.0: Added locals_max_length, locals_hide_sunder, locals_hide_dunder and use_rich arguments.

Changed in version 25.4.0: Handle exception groups.

Changed in version 25.5.0: Handle loops in exception cause chain.

class structlog.tracebacks.ExceptionDictTransformer(*, show_locals=True, locals_max_length=10, locals_max_string=80, locals_hide_dunder=True, locals_hide_sunder=False, suppress=(), max_frames=50, use_rich=True)

Return a list of exception stack dictionaries for an exception.

These dictionaries are based on Stack instances generated by extract() and can be dumped to JSON.

Parameters:

• show_locals (bool) – Whether or not to include the values of a stack frame’s local variables.

• locals_max_length (int) – Maximum length of containers before abbreviating, or None for no abbreviation.

• locals_max_string (int) – Maximum length of string before truncating, or None to disable truncating.

• locals_hide_dunder (bool) – Hide locals prefixed with double underscore. Defaults to True.

• locals_hide_sunder (bool) – Hide locals prefixed with single underscore. This implies hiding locals_hide_dunder. Defaults to False.

• suppress (Iterable[str | ModuleType]) – Optional sequence of modules or paths for which to suppress the display of locals even if show_locals is True.

• max_frames (int) – Maximum number of frames in each stack. Frames are removed from the inside out. The idea is, that the first frames represent your code responsible for the exception and last frames the code where the exception actually happened. With larger web frameworks, this does not always work, so you should stick with the default.

• use_rich (bool) – If True (the default), use rich to compute the repr of locals. If False or if rich is not installed, fall back to a simpler algorithm.

See also

Exceptions for a broader explanation of structlog’s exception features.

Changed in version 24.3.0: Added locals_max_length, locals_hide_sunder, locals_hide_dunder, suppress and use_rich arguments.

Changed in version 25.1.0: locals_max_length and locals_max_string may be None to disable truncation.

Changed in version 25.4.0: Handle exception groups.

class structlog.tracebacks.Trace(stacks)

Container for a list of stack traces.

class structlog.tracebacks.Stack(exc_type, exc_value, exc_notes=<factory>, syntax_error=None, is_cause=False, frames=<factory>, is_group=False, exceptions=<factory>)

Represents an exception and a list of stack frames.

Changed in version 25.2.0: Added the exc_notes field.

Changed in version 25.4.0: Added the is_group and exceptions fields.

class structlog.tracebacks.Frame(filename, lineno, name, locals=None)

Represents a single stack frame.

class structlog.tracebacks.SyntaxError_(offset, filename, line, lineno, msg)

Contains detailed information about SyntaxError exceptions.

structlog.typing Module

Type information used throughout structlog.

For now, they are considered provisional. Especially BindableLogger will probably change to something more elegant.

Added in version 22.2.0.

class structlog.typing.BindableLogger(*args, **kwargs)

Protocol: Methods shared among all bound loggers and that are relied on by structlog.

Added in version 20.2.0.

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.typing.FilteringBoundLogger(*args, **kwargs)

Protocol: A BindableLogger that filters by a level.

The only way to instantiate one is using make_filtering_bound_logger.

Added in version 20.2.0.

Added in version 22.2.0: String interpolation using positional arguments.

Added in version 22.2.0: Async variants alog(), adebug(), ainfo(), and so forth.

Changed in version 22.3.0: String interpolation is only attempted if positional arguments are passed.

Added in version 25.5.0: String interpolation using dictionary-based arguments if the first and only argument is a mapping.

Note

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

class structlog.typing.ExceptionTransformer(*args, **kwargs)

Protocol: A callable that transforms an ExcInfo into another datastructure.

The result should be something that your renderer can work with, e.g., a str or a JSON-serializable dict.

Used by structlog.processors.format_exc_info() and structlog.processors.ExceptionPrettyPrinter.

Parameters:

exc_info – Is the exception tuple to format

Returns:

Anything that can be rendered by the last processor in your chain, for example, a string or a JSON-serializable structure.

Added in version 22.1.0.

Note

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

structlog.typing.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.

Added in version 20.2.0.

alias of MutableMapping[str, Any]

structlog.typing.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.

Added in version 20.2.0.

structlog.typing.Processor

A callable that is part of the processor chain.

See Processors.

Added in version 20.2.0.

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

structlog.typing.Context

A dict-like context carrier.

Added in version 20.2.0.

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

structlog.typing.ExcInfo

An exception info tuple as returned by sys.exc_info.

Added in version 20.2.0.

alias of Tuple[Type[BaseException], BaseException, TracebackType | None]

structlog.typing.ExceptionRenderer

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

Used by structlog.dev.ConsoleRenderer.

Added in version 21.2.0.

alias of Callable[[TextIO, Tuple[Type[BaseException], BaseException, TracebackType | None]], None]

structlog.twisted Module

Processors and tools specific to the Twisted networking engine.

See also structlog’s Twisted support.

class structlog.twisted.BoundLogger(logger, processors, context)

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.

err(event=None, **kw)

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

msg(event=None, **kw)

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

new(**new_values)

Clear context and binds new_values using bind.

Only necessary with dict implementations that keep global state like those wrapped by structlog.threadlocal.wrap_dict when threads are reused.

unbind(*keys)

Return a new logger with keys removed from the context.

Raises:

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

class structlog.twisted.LoggerFactory

Build a Twisted logger when an instance is called.

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

__call__(*args)

Positional arguments are silently ignored.

Rvalue:

A new Twisted logger.

Changed in version 0.4.0: Added support for optional positional arguments.

class structlog.twisted.EventAdapter(dictRenderer=None)

Adapt an event_dict to Twisted logging system.

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

Parameters:

dictRenderer (Callable[[WrappedLogger, str, EventDict], str] | None) – Renderer that is used for the actual log message. Please note that structlog comes with a dedicated JSONRenderer.

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

class structlog.twisted.JSONRenderer(serializer=<function dumps>, **dumps_kw)

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. Also does not require to be adapted using it.

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

structlog.twisted.plainJSONStdOutLogger()

Return a logger that writes only the message to stdout.

Transforms non-JSONRenderer messages to JSON.

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

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

Composes PlainFileLogObserver and JSONLogObserverWrapper to a usable logger.

Added in version 0.2.0.

structlog.twisted.JSONLogObserverWrapper(observer)

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

Added in version 0.2.0.

class structlog.twisted.PlainFileLogObserver(file)

Write only the plain message without timestamps or anything else.

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

Parameters:

file (TextIO) – File to print to.

Added in version 0.2.0.