structlog 25.5.0

Structured Logging for Python

structlog is the production-ready logging solution for Python:

• Simple: Everything is about functions that take and return dictionaries – all hidden behind familiar APIs.
• Powerful: Functions and dictionaries aren’t just simple but also powerful. structlog leaves you in control.
• Fast: structlog is not hamstrung by designs of yore. Its flexibility comes not at the price of performance.

Thanks to its flexible design, you choose whether you want structlog to take care of the output of your log entries or whether you prefer to forward them to an existing logging system like the standard library's logging module.

The output format is just as flexible and structlog comes with support for JSON, logfmt, as well as pretty console output out-of-the-box:

Sponsors

structlog would not be possible without our amazing sponsors. Especially those generously supporting us at the The Organization tier and higher:

Please consider joining them to help make structlog’s maintenance more sustainable!

Introduction

structlog has been successfully used in production at every scale since 2013, while embracing cutting-edge technologies like asyncio, context variables, or type hints as they emerged. Its paradigms proved influential enough to help design structured logging packages across ecosystems.

Project Links

• Get Help (use the structlog tag on Stack Overflow)
• PyPI
• GitHub
• Documentation
• Changelog
• Third-party Extensions

structlog for Enterprise

Available as part of the Tidelift Subscription.

The maintainers of structlog and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source packages you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact packages you use.

Release Information

Deprecated

• structlog.dev.ConsoleRenderer()'s pad_event argument has been renamed to pad_event_to to differentiate it from the boolean pad_level argument. pad_event is now deprecated.

Added

• Added structlog.dev.ConsoleRenderer.get_active() that returns the currently active structlog.dev.ConsoleRenderer(). #749

• structlog.dev.ConsoleRenderer() now supports setting the exception_formatter attribute.

  You can now disable the pretty-printing of exceptions by setting it to structlog.dev.plain_traceback:

  cr = structlog.dev.ConsoleRenderer.get_active()
  cr.exception_formatter = structlog.dev.plain_traceback
  

  Same goes for sort_keys, columns, colors, force_colors, level_styles, pad_event_to, event_key, timestamp_key, and repr_native_str.

  #749 #756 #757 #759

• Added structlog.dev.ConsoleRenderer.get_default_column_styles() for reuse the default column styles. #741

• structlog.testing.capture_logs() now optionally accepts processors to apply before capture. #728

• structlog.dev.RichTracebackFormatter now exposes the upstream code_width parameter. Default width is now None for full terminal width. Full terminal width is now handled by Rich itself, bringing support for reflow and COLUMN environment variable. Passing -1 for width is now deprecated and automatically replaced by None. #717

• Native loggers now allow the passing of a dictionary for dictionary-based interpolation log.info("hello %(name)s!", {"name": "world"}). #748

• On Python 3.11+, structlog.processors.CallsiteParameterAdder now supports CallsiteParameter.QUAL_NAME that adds the qualified name of the callsite, including scope and class names. This is only available for structlog-originated events since the standard library has no equivalent.

• structlog.stdlib.LoggerFactory now supports the stacklevel parameter. #763

Changed

• structlog.dev.rich_traceback() now throws a more helpful error when Rich is missing. #735

Fixed

• structlog.processors.MaybeTimeStamper now respects the key argument when determining whether to overwrite the timestamp field. #747

• structlog.tracebacks.extract() no longer raises a RecursionError when the cause chain of an exception contains itself. #739

• Default config now respects FORCE_COLOR on Windows. #758

---

Full Changelog →

Credits

structlog is written and maintained by Hynek Schlawack. The idea of bound loggers is inspired by previous work by Jean-Paul Calderone and David Reid.

The development is kindly supported by my employer Variomedia AG, structlog’s Tidelift subscribers, and all my amazing GitHub Sponsors.

The logs-loving beaver logo has been contributed by Lynn Root.