Simple, powerful, and fast logging for Python.
This quick bugfix release fixes two regressions and the fact that RichTracebackFormatter has been ignoring its width argument the whole time.
Full changelog below!
This release would not be possible without my generous sponsors! Thank you to all of you making sustainable maintenance possible! If you would like to join them, go to https://github.com/sponsors/hynek and check out the sweet perks!
Variomedia AG (@variomedia), Tidelift (@tidelift), FilePreviews (@filepreviews), Daniel Fortunov (@asqui), Kevin P. Fleming (@kpfleming), and Sören Weber (@SoerenWeber).
Adam Hill (@adamghill), Dan Groshev (@si14), Magnus Watn (@magnuswatn), David Cramer (@dcramer), Moving Content AG (@moving-content), ProteinQure (@ProteinQure), Jesse Snyder (@jessesnyder), Rivo Laks (@rivol), Ionel Cristian Mărieș (@ionelmc), The Westervelt Company (@westerveltco), Philippe Galvan (@PhilippeGalvan), Birk Jernström (@birkjernstrom), Tim Schilling (@tim-schilling), Chris Withers (@cjw296), Christopher Dignam (@chdsbd), Stefan Hagen (@sthagen), Sławomir Ehlert (@slafs), Mostafa Khalil (@khadrawy), Filip Mularczyk (@mukiblejlok), and Mike Fiedler (@miketheman).
Not to forget 6 more amazing humans who chose to be generous but anonymous!
The lazy logger proxy returned by structlog.get_logger() now returns its initial values when asked for context. When asked for context before binding for the first time, it returned an empty dictionary in 23.3.0.
The displayed level name when using structlog.stdlib.BoundLogger.exception() is "error" instead of "exception". Fixes regression in 23.3.0. #584
Don't ignore the width argument of RichTracebackFormatter. #587
The highlight is the configurability of structlog.dev.ConsoleRenderer's output (check out https://www.structlog.org/en/stable/console-output.html#console-output-configuration!) and structlog.processors.CallsiteParameterAdder getting asyncio support.
This release would not be possible without my generous sponsors! Thank you to all of you making sustainable maintenance possible! If you would like to join them, go to https://github.com/sponsors/hynek and check out the sweet perks!
Variomedia AG (@variomedia), Tidelift (@tidelift), FilePreviews (@filepreviews), Daniel Fortunov (@asqui), and Kevin P. Fleming (@kpfleming).
Adam Hill (@adamghill), Dan Groshev (@si14), Magnus Watn (@magnuswatn), David Cramer (@dcramer), Moving Content AG (@moving-content), ProteinQure (@ProteinQure), Jesse Snyder (@jessesnyder), Rivo Laks (@rivol), Ionel Cristian Mărieș (@ionelmc), The Westervelt Company (@westerveltco), Philippe Galvan (@PhilippeGalvan), Birk Jernström (@birkjernstrom), Tim Schilling (@tim-schilling), Chris Withers (@cjw296), Christopher Dignam (@chdsbd), Stefan Hagen (@sthagen), Sławomir Ehlert (@slafs), Mostafa Khalil (@khadrawy), Filip Mularczyk (@mukiblejlok), and Mike Fiedler (@miketheman).
Not to forget 6 more amazing humans who chose to be generous but anonymous!
The colorful development logger is now even more configurable! Choose freely your colors and the order of the key-value pairs! Implement your own formatters for certain keys!
Implementing the output on top of the new columns API has changed the default very slightly, but shouldn't be noticeable. #577
Async log methods (those starting with an a) now also support the collection of callsite information using structlog.processors.CallsiteParameterAdder. #565
structlog.stdlib.recreate_defaults() now also adds structlog.stdlib.add_logger_name to the processors. Check out the updated screenshot!The return value from get_logger() (a BoundLoggerLazyProxy) now passes isinstance-checks against structlog.typing.BindableLogger on Python 3.12. #561
structlog.threadlocal.tmp_bind() now also works with BoundLoggerLazyProxy (in other words: before anything is bound to a bound logger).
stdlib: ProcessorFormatter can now be told to not render the log record message using getMessage and just str(record.msg) instead. #550
stdlib: structlog.stdlib.BoundLogger.exception()'s handling ofLogRecord.exc_info is now set consistent with logging. #571 #572
Not a super exciting release, but it was time to deliver some fixes and quality-of-life features to the people!
This release would not be possible without my generous sponsors! Thank you to all of you making sustainable maintenance possible! If you would like to join them, go to https://github.com/sponsors/hynek and check out the sweet perks!
Variomedia AG (@variomedia), Tidelift (@tidelift), HiredScore (@HiredScore), FilePreviews (@filepreviews), Daniel Fortunov (@asqui), and Kevin P. Fleming (@kpfleming).
Adam Hill (@adamghill), Dan Groshev (@si14), Magnus Watn (@magnuswatn), David Cramer (@dcramer), Moving Content AG (@moving-content), ProteinQure (@ProteinQure), Jesse Snyder (@jessesnyder), Rivo Laks (@rivol), Tom Ballinger (@thomasballinger), Ionel Cristian Mărieș (@ionelmc), The Westervelt Company (@westerveltco), Philippe Galvan (@PhilippeGalvan), Birk Jernström (@birkjernstrom), Tim Schilling (@tim-schilling), Chris Withers (@cjw296), Christopher Dignam (@chdsbd), Stefan Hagen (@sthagen), and Sławomir Ehlert (@slafs).
Not to forget 4 more amazing humans who chose to be generous but anonymous!
Official support for Python 3.12. #515
structlog.processors.MaybeTimeStamper that only adds a timestamp if there isn't one already. #81
structlog.dev.ConsoleRenderer now supports renamed timestamp keys using the timestamp_key parameter. #541
structlog.dev.RichTracebackFormatter that allows to configure the traceback formatting. #542
This release brings the hybrid approach to sync / async logging to structlog's standard library integration. You don't have to configure anything anymore, simply prepend the method name with an a and await it: await logger.ainfo("this is async!"). structlog.stdlib.AsyncBoundLogger will probably be deprecated in the future.
This release also brings support for FORCE_COLOR and NO_COLOR to structlog's default configuration. structlog was originally not meant to be used without configuration, but times have changed and we're breaking new ground!
This release would not be possible without my generous sponsors! Thank you to all of you making sustainable maintenance possible! If you would like to join them, go to https://github.com/sponsors/hynek and check out the sweet perks!
Variomedia AG (@variomedia), Tidelift (@tidelift), Sentry (@getsentry), HiredScore (@HiredScore), FilePreviews (@filepreviews), and Daniel Fortunov (@asqui).
Adam Hill (@adamghill), Dan Groshev (@si14), Magnus Watn (@magnuswatn), David Cramer (@dcramer), Moving Content AG (@moving-content), Stein Magnus Jodal (@jodal), ProteinQure (@ProteinQure), Jesse Snyder (@jessesnyder), Rivo Laks (@rivol), Tom Ballinger (@thomasballinger), @medecau, Ionel Cristian Mărieș (@ionelmc), The Westervelt Company (@westerveltco), Philippe Galvan (@PhilippeGalvan), Birk Jernström (@birkjernstrom), Tim Schilling (@tim-schilling), Chris Withers (@cjw296), Christopher Dignam (@chdsbd), and Stefan Hagen (@sthagen).
Not to forget 2 more amazing humans who chose to be generous but anonymous!
structlog.stdlib.BoundLogger now has, analogously to our native logger, a full set of async log methods prefixed with an a: await log.ainfo("event!") #502
The default configuration now respects the presence of FORCE_COLOR (regardless of its value, unless an empty string). This disables all heuristics whether it makes sense to use colors. #503
The default configuration now respects the presence of NO_COLOR (regardless of its value, unless an empty string). This disables all heuristics whether it makes sense to use colors and overrides FORCE_COLOR. #504
ConsoleRenderer now reuses the _figure_out_exc_info to process the exc_info argument like ExceptionRenderer does. This prevents crashes if the actual Exception is passed for the exc_info argument instead of a tuple or True. #482
FilteringBoundLogger.aexception() now extracts the exception info using sys.exc_info() before passing control to the asyncio executor (where original exception info is no longer available). #488
This is bug-fix release due to overly-zealous string interpolation in the native bound logger. You can now pass anything as event again (but it really should be a string) and log % signs as long as you don't pass positional arguments.
This release would not be possible without my generous sponsors! Thank you to all of you making sustainable maintenance possible! If you would like to join them, go to https://github.com/sponsors/hynek and check out the sweet perks!
Variomedia AG (@variomedia), Tidelift (@tidelift), Sentry (@getsentry), HiredScore (@HiredScore), FilePreviews (@filepreviews), and Daniel Fortunov (@asqui).
@rzijp, Adam Hill (@adamghill), Dan Groshev (@si14), Tamir Bahar (@tmr232), Adi Roiban (@adiroiban), Magnus Watn (@magnuswatn), David Cramer (@dcramer), Moving Content AG (@moving-content), Stein Magnus Jodal (@jodal), Iwan Aucamp (@aucampia), ProteinQure (@ProteinQure), Jesse Snyder (@jessesnyder), Rivo Laks (@rivol), Thomas Ballinger (@thomasballinger), @medecau, Ionel Cristian Mărieș (@ionelmc), The Westervelt Company (@westerveltco), Philippe Galvan (@PhilippeGalvan), Birk Jernström (@birkjernstrom), Jannis Leidel (@jezdez), Tim Schilling (@tim-schilling), Chris Withers (@cjw296), and Christopher Dignam (@chdsbd).
Not to forget 2 more amazing humans who chose to be generous but anonymous!
FilteringBoundLogger (used by default) is now only attempted if positional arguments are passed. This prevents crashes if something different than a string is passed for the event argument. #475
This is another (too) big release, but before I go into new features, allow me to beg you to check out structlog's documentation. I've spent easily half of the time on bringing is up to date, restructuring, and adding usage recipes. Not new in this release, but did you know that the standard library chapter has flowcharts that give you as visual explanations of how the various methods work? This is usually the biggest sticking point when starting to use structlog.
Feature-wise the big thing is that structlog's internal (and extremely fast) loggers (the one created using structlog.make_filtering_bound_logger() got two new features that people have asked for forever:
log.info("hello %s!", "world") works now!await log.ainfo("hello %s!", "world") is the same thing as above, but async.This release would not be possible without my generous sponsors! Thank you to all of you making sustainable maintenance possible! If you would like to join them, go to https://github.com/sponsors/hynek and check out the sweet perks!
Variomedia AG (@variomedia), Tidelift (@tidelift), Sentry (@getsentry), HiredScore (@HiredScore), FilePreviews (@filepreviews), and Daniel Fortunov (@asqui).
@rzijp, Adam Hill (@adamghill), Dan Groshev (@si14), Tamir Bahar (@tmr232), Adi Roiban (@adiroiban), Magnus Watn (@magnuswatn), David Cramer (@dcramer), Moving Content AG (@moving-content), Stein Magnus Jodal (@jodal), Iwan Aucamp (@aucampia), ProteinQure (@ProteinQure), Jesse Snyder (@jessesnyder), Rivo Laks (@rivol), Thomas Ballinger (@thomasballinger), @medecau, Ionel Cristian Mărieș (@ionelmc), The Westervelt Company (@westerveltco), Philippe Galvan (@PhilippeGalvan), Birk Jernström (@birkjernstrom), Jannis Leidel (@jezdez), Tim Schilling (@tim-schilling), Chris Withers (@cjw296), and Christopher Dignam (@chdsbd).
Not to forget 2 more amazing humans who chose to be generous but anonymous!
structlog.__version__). Please use importlib.metadata instead (for Python 3.7: the importlib-metadata PyPI package).structlog.types module is now deprecated in favor of the structlog.typing module. It seems like the Python typing community is settling on this name.FilteringBoundLogger (used by default) now allows for string interpolation using positional arguments:
>>> log.info("Hello %s! The answer is %d.", "World", 42, x=1)
2022-10-07 10:04.31 [info ] Hello World! The answer is 42. x=1
FilteringBoundLogger now also has support for asyncio-based logging. Instead of a wrapper class like structlog.stdlib.AsyncBoundLogger, async equivalents have been added for all logging methods. So instead of log.info("hello") you can also write await log.ainfo("hello") in async functions and methods.
This seems like the better approach and if it's liked by the community, structlog.stdlib.BoundLogger will get those methods too. #457
:) for seconds.This is a (too) big release, so it has many highlights!
Firstly, rendering exceptions in machine-readable logs (usually JSON) got a big upgrade: thanks to structlog.processors.dict_tracebacks you can now have fully structured exceptions in your logs!
To ease getting started with structlog, we're now shipping structlog.stdlib.recreate_defaults() that recreates structlog's default behavior, but on top of standard library's logging. The output looks the same, but it runs through logging's machinery and integrates itself easier. The default configuration now also merges your contextvars-based context, so enjoy structlog.contextvars.bind_contextvars() without configuring anything!
Another request wish that kept coming up is naming the message key differently than event. We're aware that nowadays keys like msg are more common, but structlog pre-dates the software that introduced and popularized it. To allow for more consistency across your platforms, structlog now ships structlog.processors.EventRenamer that allows you to rename the default event key to something else and additionally also allows you to rename another key to event.
❤️ Huge thanks to my GitHub sponsors, Tidelift subscribers, and Ko-fi buyers! ❤️
None of my projects would exist in their current form without you!
The entire structlog.threadlocal module is deprecated. Please use the primitives from structlog.contextvars instead.
If you're using the modern APIs (bind_threadlocal() / merge_threadlocal()) it's enough to replace them 1:1 with their contextvars counterparts. The old approach around wrap_dict() has been discouraged for a while.
Currently there are no concrete plans to remove the module, but no patches against it will be accepted from now on. #409
structlog.processors.StackInfoRenderer now has an additional_ignores parameter that allows you to filter out your own logging layer. #396
structlog.WriteLogger, a faster – but more low-level – alternative to structlog.PrintLogger. It works the way PrintLogger used to work in previous versions. #403 #404
structlog.make_filtering_bound_logger()-returned loggers now also have a log() method to match the structlog.stdlib.BoundLogger signature closer. #413
structlog.tracebacks module, and most notably the structlog.tracebacks.ExceptionDictTransformer which can be used with the new structlog.processors.ExceptionRenderer to render JSON tracebacks. #407
structlog.stdlib.recreate_defaults(log_level=logging.NOTSET) that recreates structlog's defaults on top of standard library's logging. It optionally also configures logging to log to standard out at the passed log level. #428
structlog.processors.EventRenamer allows you to rename the hitherto hard-coded event dict key event to something else. Optionally, you can rename another key to event at the same time, too. So adding EventRenamer(to="msg", replace_by="_event") to your processor pipeline will rename the standard event key to msg and then rename the _event key to event. This allows you to use the event key in your own log files and to have consistent log message keys across languages.structlog.dev.ConsoleRenderer(event_key="event") now allows to customize the name of the key that is used for the log message.structlog.make_filtering_bound_logger() now returns a method with the same signature for all log levels, whether they are active or not. This ensures that invalid calls to inactive log levels are caught immediately and don't explode once the log level changes. #401
structlog.PrintLogger – that is used by default – now uses print() for printing, making it a better citizen for interactive terminal applications. #399
structlog.testing.capture_logs now works for already initialized bound loggers. #408
structlog.processors.format_exc_info() is no longer a function, but an instance of structlog.processors.ExceptionRenderer. Its behavior has not changed. #407
structlog.contextvars.merge_contextvars processor. That means you can use structlog.contextvars features without configuring structlog.bind, unbind, try_unbind and new methods in the FilteringBoundLogger Protocol. This makes it easier to use objects of type FilteringBoundLogger in a typed context. #392
sys.stdouts are now handled more gracefully by ConsoleRenderer (that's used by default). #404
structlog.stdlib.render_to_log_kwargs() now correctly handles the presence of exc_info, stack_info, and stackLevel in the event dictionary. They are transformed into proper keyword arguments instead of putting them into the extra dictionary. #424, #427
I didn't expect to make this release but @aucampia and @airwoodix contributed features that I'm sure will excite many users, so here's Santa Hynek 🎅 with a surprise release.
structlog.processors.LogfmtRenderer processor to render log lines using the logfmt format. #376
structlog.stdlib.ExtraAdder processor that adds 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. #209 #377
structlog.processor.CallsiteParameterAdder processor that adds parameters of the callsite that an event dictionary orginated 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 orignated from. #380
This release is mostly about a regression when importing using a Python interpreter running with the PYTHONOPTIMIZE=2 environment variable set, or as python -OO. The one new feature is kinda neat too, though!
The main reason for this comparatively timely release is that aiohttp 3.8's new behavior of starting new loops within aiohttp.web.run_app() led to breakage in apps that use structlog.stdlib.AsyncBoundLogger.
The one big new feature though is the support for much more powerful processor chains within structlog.stdlib.ProcessorFormatter. This took me way too long to get right, but I'm excited to share it with you.
This is also the first release without a setup.py. Invoking it was never tested and never supported, so now it's gone. Please use standard packaging tools like PyPA's build or flit directly if you want to package structlog yourself.
structlog switched its packaging to flit. Users shouldn't notice a difference, but (re-)packagers might.none
structlog.dev.ConsoleRenderer now has sort_keys boolean parameter that allows to disable the sorting of keys on output. #358
structlog.processors.TimeStamper now works well with FreezeGun even when it gets applied before the loggers are configured. #364
structlog.stdlib.AsyncBoundLogger now determines the running loop when logging, not on instantiation. That has a minor performance impact, but makes it more robust when loops change (e.g. aiohttp.web.run_app()), or you want to use sync_bl before a loop has started.
structlog.stdlib.ProcessorFormatter now has a processors argument that allows to define a processor chain to run over all log entries.
Before running the chain, two additional keys are added to the event dictionary: _record and _from_structlog. With them it's possible to extract information from logging.LogRecords and differentiate between structlog and logging log entries while processing them.
The old processor (singular) parameter is now deprecated, but no plans exist to remove it. #365