All notable changes to this project will be documented in this file.
The first number of the version is the year. The second number is incremented with each release, starting at 1 for each year. The third number is for emergencies when we need to start branches for older releases.
You can find out backwards-compatibility policy here.
structlog.stdlib.BoundLoggernow has, analogously to our native logger, a full set of async log methods prefixed with an
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
ConsoleRenderer now reuses the
_figure_out_exc_infoto process the
ExceptionRendererdoes. This prevents crashes if the actual Exception is passed for the exc_info argument instead of a tuple or
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
String interpolation in
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
String interpolation doesn’t cause crashes in filtered log call anymore. #478
Accessing package metadata as attributes on the structlog module is deprecated (e.g.
structlog.__version__). Please use
importlib.metadatainstead (for Python 3.7: the importlib-metadata PyPI package).
structlog.typesmodule is now deprecated in favor of the
structlog.typingmodule. 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
FilteringBoundLoggernow 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.BoundLoggerwill get those methods too. #457
The timestamps in the default configuration now use the correct separator (
:) for seconds.
Python 3.6 is not supported anymore.
Pickling is now only possible with protocol version 3 and newer.
structlog.threadlocalmodule is deprecated. Please use the primitives from
If you’re using the modern APIs (
merge_threadlocal()) it’s enough to replace them 1:1 with their
contextvarscounterparts. 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.StackInfoRenderernow has an additional_ignores parameter that allows you to filter out your own logging layer. #396
structlog.make_filtering_bound_logger()-returned loggers now also have a
log()method to match the
structlog.stdlib.BoundLoggersignature closer. #413
Added structured logging of tracebacks via the
structlog.tracebacksmodule, and most notably the
structlog.tracebacks.ExceptionDictTransformerwhich can be used with the new
structlog.processors.ExceptionRendererto 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
loggingto log to standard out at the passed log level. #428
structlog.processors.EventRenamerallows you to rename the hitherto hard-coded event dict key
eventto something else. Optionally, you can rename another key to
eventat the same time, too. So adding
EventRenamer(to="msg", replace_by="_event")to your processor pipeline will rename the standard
msgand then rename the
event. This allows you to use the
eventkey 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_logsnow 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
The default configuration now includes the
structlog.contextvars.merge_contextvarsprocessor. That means you can use
structlog.contextvarsfeatures without configuring structlog.
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
stackLevelin the event dictionary. They are transformed into proper keyword arguments instead of putting them into the
extradictionary. #424, #427
structlog.stdlib.ExtraAdderprocessor that adds extra attributes of
logging.LogRecordobjects to the event dictionary. This processor can be used for adding data passed in the
extraparameter of the
loggingmodule’s log methods to the event dictionary. #209, #377
structlog.processor.CallsiteParameterAdderprocessor that 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. #380
structlog.contextvars.bound_contextvarsdecorator/context managers to temporarily bind key-value pairs to a thread-local and context-local context. #371
Fixed import when running in optimized mode (
python -OO) . #373
sort_keysboolean parameter that allows to disable the sorting of keys on output. #358
structlog switched its packaging to flit. Users shouldn’t notice a difference, but (re-)packagers might.
structlog.stdlib.AsyncBoundLoggernow 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_blbefore a loop has started.
structlog.stdlib.ProcessorFormatternow 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:
_from_structlog. With them it’s possible to extract information from
logging.LogRecords and differentiate between structlog and
logginglog entries while processing them.
The old processor (singular) parameter is now deprecated, but no plans exist to remove it. #365
structlog.contextvars.get_contextvars()can now be used to get a copy of the current thread-local/context-local context that has been bound using
structlog.contextvars.bind_contextvars(). #331, #337
structlog.contextvars.get_merged_contextvars(bl)do the same, but also merge the context from a bound logger bl. Same pull requests as previous change.
structlog.contextvars.bind_contextvars()now returns a mapping of keys to
contextvars.Tokens, allowing you to reset values using the new
Exception rendering in
structlog.dev.ConsoleLoggeris now configurable using the
exception_formattersetting. If either the Rich or the better-exceptions package is present, structlog will use them for pretty-printing tracebacks. Rich takes precedence over better-exceptions if both are present.
The final processor can now return a
To implement pretty exceptions (see Changes below),
structlog.dev.ConsoleRenderernow formats exceptions itself.
Make sure to remove
format_exc_infofrom your processor chain if you configure structlog manually. This change is not really breaking, because the old use-case will keep working as before. However if you pass
pretty_exceptions=True(which is the default if either
better-exceptionsis installed), a warning will be raised and the exception will be rendered without prettification.
All use of Colorama on non-Windows systems has been excised. Thus, colors are now enabled by default in
structlog.dev.ConsoleRendereron non-Windows systems. You can keep using Colorama to customize colors, of course. #345
structlog is now importable if
None(e.g. when running using
structlog.dev.ConsoleRendererwill now look for a
logger_namekey if no
loggerkey is set. #295
Python 2.7 and 3.5 aren’t supported anymore. The package meta data should ensure that you keep getting 20.1.0 on those versions. #244
_contextattribute of a bound logger is now deprecated. Please use the new
structlog has now type hints for all of its APIs! Since structlog is highly dynamic and configurable, this led to a few concessions like a specialized
structlog.stdlib.get_logger()whose only difference to
structlog.get_logger()is that it has the correct type hints.
We consider them provisional for the time being – i.e. the backwards-compatibility does not apply to them in its full strength until we feel we got it right. Please feel free to provide feedback! #223, #282
structlog.make_filtering_loggerthat can be used like
configure(wrapper_class=make_filtering_bound_logger(logging.INFO)). It creates a highly optimized bound logger whose inactive methods only consist of a
return None. This is now also the default logger.
As a complement,
structlog.stdlib.add_log_level()can now additionally be imported as
structlog.processors.add_log_levelsince it just adds the method name to the event dict.
structlog.BytesLoggerto avoid unnecessary encoding round trips. Concretely this is useful with orjson which returns bytes. #271
The final processor now also may return bytes that are passed untouched to the wrapped logger.
structlog.get_context()allows you to retrieve the original context of a bound logger. #266,
structlog.testing.CapturingLoggerfor more unit testing goodness.
structlog.stdlib.AsyncBoundLoggerthat executes logging calls in a thread executor and therefore doesn’t block. #245
The default bound logger (
wrapper_class) if you don’t configure structlog has changed. It’s mostly compatible with the old one but a few uncommon methods like
errdon’t exist anymore.
You can regain the old behavior by using
Please note that due to the various interactions between settings, it’s possible that you encounter even more errors. We strongly urge you to always configure all possible settings since the default configuration is not covered by our backwards-compatibility policy.
structlog.processors.add_log_level()is now part of the default configuration.
structlog.stdlib.ProcessorFormatterno longer uses exceptions for control flow, allowing
foreign_pre_chainprocessors to use
sys.exc_info()to access the real exception.
This is the last version to support Python 2.7 (including PyPy) and 3.5. All following versions will only support Python 3.6 or later.
Python 3.4 is not supported anymore. It has been unsupported by the Python core team for a while now and its PyPI downloads are negligible.
It’s very unlikely that structlog will break under 3.4 anytime soon, but we don’t test it anymore.
Full Python 3.8 support for
Added more pass-through properties to
structlog.stdlib.BoundLogger. To makes it easier to use it as a drop-in replacement for
Added new processor
structlog.dev.set_exc_info()that will set
exc_info=Trueif the method’s name is
exc_infoisn’t set at all. This is only necessary when the standard library integration is not used. It fixes the problem that in the default configuration,
exceptblock would not print the exception without passing
exc_info=Trueto it explicitly. #130, #173, #200, #204
Added pass_foreign_args argument to
structlog.stdlib.ProcessorFormatter. It allows to pass a foreign log record’s args attribute to the event dictionary under the
structlog.dev.ConsoleRenderernow uses no colors by default, if Colorama is not available. #215
structlog.dev.ConsoleRenderernow initializes Colorama lazily, to prevent accidental side-effects just by importing structlog. #210
A best effort has been made to make as much of structlog pickleable as possible to make it friendlier with
multiprocessingand similar libraries. Some classes can only be pickled on Python 3 or using the dill library though and that is very unlikely to change.
So far, the configuration proxy,
structlog.dev.ConsoleRendererhave been made pickleable. Please report if you need any another class fixed. #126
structlog.PrintLoggernow have a
fatal()log method. #181
Under certain (rather unclear) circumstances, the frame extraction could throw an
SystemError: error return without exception set. A workaround has been added. #174
structlog.stdlib.add_log_level_number()processor that adds the level number to the event dictionary. Can be used to simplify log filtering. #151
try_unbind()that works like
unbind()but doesn’t raise a
KeyErrorif one of the keys is missing. #171
The meaning of the
structlog[dev]installation target will change from “colorful output” to “dependencies to develop structlog” in 19.1.0.
The main reason behind this decision is that it’s impossible to have a structlog in your normal dependencies and additionally a
structlog[dev]for development (
pipwill report an error).
structlog.dev.ConsoleRenderernow accepts a force_colors argument to output colored logs even if the destination is not a tty. Use this option if your logs are stored in files that are intended to be streamed to the console.
structlog.dev.ConsoleRenderernow accepts a level_styles argument for overriding the colors for individual levels, as well as to add new levels. See the docs for
ConsoleRenderer.get_default_level_styles()for usage. #139
structlog.is_configured()to check whether or not structlog has been configured.
structlog.get_config()to introspect current configuration.
Do not encapsulate Twisted failures twice with newer versions of Twisted. #144
structlog.stdlib.ProcessorFormatternow accepts keep_exc_info and keep_stack_info arguments to control what to do with this information on log records. Most likely you want them both to be
Falsetherefore it’s the default. #109
structlog.stdlib.add_logger_name()now works in
Clear log record args in
structlog.stdlib.ProcessorFormatterafter rendering. This fix is for you if you tried to use it and got
TypeError: not all arguments converted during string formattingexceptions. #116, #117
The main features of this release are massive improvements in standard library’s
Have a look at the updated standard library chapter on how to use them!
Special thanks go to Fabian Büchler, Gilbert Gilb’s, Iva Kaneva, insolite, and sky-code, that made them possible.
structlog.stdlib.render_to_log_kwargs(). This allows you to use
logging-based formatters to take care of rendering your entries. #98
Added repr_native_str to
structlog.dev.ConsoleRenderer. This allows for human-readable non-ASCII output on Python 2 (
repr()on Python 2 behaves like
ascii()on Python 3 in that regard). As per compatibility policy, it’s on (original behavior) in
KeyValueRendererand off (human-friendly behavior) in
Added colors argument to
structlog.dev.ConsoleRendererand made it the default renderer. #78
The default renderer now is
structlog.dev.ConsoleRendererif you don’t configure structlog. Colors are used if available and human-friendly timestamps are prepended. This is in line with our backwards-compatibility policy that explicitly excludes default settings.
UNIX epoch timestamps from
structlog.processors.TimeStamperare more precise now.
Positional arguments are now removed even if they are empty. #82
Fixed bug with Python 3 and
structlog.stdlib.BoundLogger.log(). Error log level was not reproducible and was logged as exception one time out of two. #92
Python 3.3 and 2.6 aren’t supported anymore. They may work by chance but any effort to keep them working has ceased.
The last Python 2.6 release was on October 29, 2013 and isn’t supported by the CPython core team anymore. Major Python packages like Django and Twisted dropped Python 2.6 a while ago already.
Python 3.3 never had a significant user base and wasn’t part of any distribution’s LTS release.
key_orderis used and a key is missing a value, it’s not rendered at all instead of being rendered as
Exceptions without a
__traceback__are now also rendered on Python 3.
Don’t cache loggers in lazy proxies returned from
get_logger(). This lead to in-place mutation of them if used before configuration which in turn lead to the problem that configuration was applied only partially to them later. #72
structlog.dev.ConsoleRendererthat renders the event dictionary aligned and with colors.
structlog.processors.UnicodeDecoderthat will decode all byte string values in an event dictionary to Unicode.
structlog.processors.JSONRendererwhich allows for using different (possibly faster) JSON encoders than the standard library.
structlog.processors.format_exc_infonow support passing of Exceptions on Python 3.
six is now used for compatibility.
Officially support Python 3.5.
structlog.PrintLogger.failureas preparation for the new Twisted logging system.
Tolerate frames without a
__name__, better. #58
Added option to specify target key in
log.errfrom quoting strings rendered by
Tolerate frames without a
__name__when guessing callsite names.
Drop support for Python 3.2. There is no justification to add complexity for a Python version that nobody uses. If you are one of the 0.350% that use Python 3.2, please stick to the 0.4 branch; critical bugs will still be fixed.
Officially support Python 3.4.
Allow final processor to return a dictionary. See the adapting chapter. #26
Test Twisted-related code on Python 3 (with some caveats).
Fixed a memory leak in greenlet code that emulates thread locals. It shouldn’t matter in practice unless you use multiple wrapped dicts within one program that is rather unlikely. #8
structlog.PrintLoggernow is thread-safe.
from structlog import *works now (but you still shouldn’t use it).
Don’t cache proxied methods in
structlog.threadlocal._ThreadLocalDictWrapper. This doesn’t affect regular users.
Various doc fixes.
structlog.processors.StackInfoRendererfor adding stack information to log entries without involving exceptions. Also added it to default processor chain. #6
Allow optional positional arguments for
structlog.get_loggerthat are passed to logger factories. The standard library factory uses this for explicit logger naming. #12
structlog.processors.ExceptionPrettyPrinterfor development and testing when multiline log entries aren’t just acceptable but even helpful.
Allow the standard library name guesser to ignore certain frame names. This is useful together with frameworks.
Add meta data (e.g. function names, line numbers) extraction for wrapped stdlib loggers. #5
Fix stdlib’s name guessing.
structlog.processors.TimeStamperto API documentation.
Greatly enhanced and polished the documentation and added a new theme based on Write The Docs, requests, and Flask.
Add Python Standard Library-specific BoundLogger that has an explicit API instead of intercepting unknown method calls. See
structlog.ReturnLoggernow allows arbitrary positional and keyword arguments.
Add Twisted-specific BoundLogger that has an explicit API instead of intercepting unknown method calls. See
Allow logger proxies that are returned by
structlog.wrap_loggerto cache the BoundLogger they assemble according to configuration on first use. See the chapter on performance and the
Extract a common base class for loggers that does nothing except keeping the context state. This makes writing custom loggers much easier and more straight-forward. See
structlog.processors.KeyValueRendererfor more predictable log entries with any
Enhance Twisted support by offering JSONification of non-structlog log entries.
Allow for custom serialization in
Promote to stable, thus henceforth a strict backwards-compatibility policy is put into effect.
structlog.PrintLoggernow uses proper I/O routines and is thus viable not only for examples but also for production.