Changelog#
All notable changes to this project will be documented in this file.
The format is based on Keep a Changelog and this project adheres to Calendar Versioning.
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 shouldn’t ever be afraid to upgrade structlog
if you’re using its public APIs and pay attention to DeprecationWarning
s.
Whenever there is a need to break compatibility, it is announced here in the changelog and raises a DeprecationWarning
for a year (if possible) before it’s finally really broken.
You cannot rely on the default settings and the structlog.dev
module.
They may be adjusted in the future to provide a better experience when starting to use structlog
.
So please make sure to always properly configure your applications.
22.1.0 - 2022-07-20#
Removed#
Python 3.6 is not supported anymore.
Pickling is now only possible with protocol version 3 and newer.
Deprecated#
The entire
structlog.threadlocal
module is deprecated. Please use the primitives fromstructlog.contextvars
instead.If you’re using the modern APIs (
bind_threadlocal()
/merge_threadlocal()
) it’s enough to replace them 1:1 with theircontextvars
counterparts. The old approach aroundwrap_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
Added#
structlog.processors.StackInfoRenderer
now has an additional_ignores parameter that allows you to filter out your own logging layer. #396Added
structlog.WriteLogger
, a faster – but more low-level – alternative tostructlog.PrintLogger
. It works the wayPrintLogger
used to work in previous versions. #403 #404structlog.make_filtering_bound_logger()
-returned loggers now also have alog()
method to match thestructlog.stdlib.BoundLogger
signature closer. #413Added structured logging of tracebacks via the
structlog.tracebacks
module, and most notably thestructlog.tracebacks.ExceptionDictTransformer
which can be used with the newstructlog.processors.ExceptionRenderer
to render JSON tracebacks. #407structlog.stdlib.recreate_defaults(log_level=logging.NOTSET)
that recreatesstructlog
’s defaults on top of standard library’slogging
. It optionally also configureslogging
to log to standard out at the passed log level. #428structlog.processors.EventRenamer
allows you to rename the hitherto hard-coded event dict keyevent
to something else. Optionally, you can rename another key toevent
at the same time, too. So addingEventRenamer(to="msg", replace_by="_event")
to your processor pipeline will rename the standardevent
key tomsg
and then rename the_event
key toevent
. This allows you to use theevent
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.
Changed#
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. #401structlog.PrintLogger
– that is used by default – now usesprint()
for printing, making it a better citizen for interactive terminal applications. #399structlog.testing.capture_logs
now works for already initialized bound loggers. #408structlog.processors.format_exc_info()
is no longer a function, but an instance ofstructlog.processors.ExceptionRenderer
. Its behavior has not changed. #407The default configuration now includes the
structlog.contextvars.merge_contextvars
processor. That means you can usestructlog.contextvars
features without configuringstructlog
.
Fixed#
Overloaded the
bind
,unbind
,try_unbind
andnew
methods in theFilteringBoundLogger
Protocol. This makes it easier to use objects of typeFilteringBoundLogger
in a typed context. #392Monkeypatched
sys.stdout
s are now handled more gracefully byConsoleRenderer
(that’s used by default). #404structlog.stdlib.render_to_log_kwargs()
now correctly handles the presence ofexc_info
,stack_info
, andstackLevel
in the event dictionary. They are transformed into proper keyword arguments instead of putting them into theextra
dictionary. #424, #427
21.5.0 - 2021-12-16#
Added#
Added the
structlog.processors.LogfmtRenderer
processor to render log lines using the logfmt format. #376Added the
structlog.stdlib.ExtraAdder
processor that adds extra attributes oflogging.LogRecord
objects to the event dictionary. This processor can be used for adding data passed in theextra
parameter of thelogging
module’s log methods to the event dictionary. #209, #377Added the
structlog.processor.CallsiteParameterAdder
processor 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
21.4.0 - 2021-11-25#
Added#
Added the
structlog.threadlocal.bound_threadlocal
andstructlog.contextvars.bound_contextvars
decorator/context managers to temporarily bind key/value pairs to a thread-local and context-local context. #371
Fixed#
Fixed import when running in optimized mode (
PYTHONOPTIMIZE=2
orpython -OO
) . #373
21.3.0 - 2021-11-20#
Added#
structlog.dev.ConsoleRenderer
now hassort_keys
boolean parameter that allows to disable the sorting of keys on output. #358
Changed#
structlog
switched its packaging to flit. Users shouldn’t notice a difference, but (re-)packagers might.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 usesync_bl
before a loop has started.
Fixed#
structlog.processors.TimeStamper
now works well with FreezeGun even when it gets applied before the loggers are configured. #364structlog.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 fromlogging.LogRecord
s and differentiate betweenstructlog
andlogging
log entries while processing them.The old processor (singular) parameter is now deprecated, but no plans exist to remove it. #365
21.2.0 - 2021-10-12#
Added#
structlog.threadlocal.get_threadlocal()
andstructlog.contextvars.get_contextvars()
can now be used to get a copy of the current thread-local/context-local context that has been bound usingstructlog.threadlocal.bind_threadlocal()
andstructlog.contextvars.bind_contextvars()
. #331, #337structlog.threadlocal.get_merged_threadlocal(bl)
andstructlog.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 tocontextvars.Token
s, allowing you to reset values using the newstructlog.contextvars.reset_contextvars()
. #339Exception rendering in
structlog.dev.ConsoleLogger
is now configurable using theexception_formatter
setting. 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.This only works if
format_exc_info
is absent in the processor chain. #330, #349The final processor can now return a
bytearray
(additionally tostr
andbytes
). #344
Changed#
To implement pretty exceptions (see Changes below),
structlog.dev.ConsoleRenderer
now formats exceptions itself.Make sure to remove
format_exc_info
from your processor chain if you configurestructlog
manually. This change is not really breaking, because the old use-case will keep working as before. However if you passpretty_exceptions=True
(which is the default if eitherrich
orbetter-exceptions
is 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.ConsoleRenderer
on non-Windows systems. You can keep using colorama to customize colors, of course. #345
Fixed#
structlog
is now importable ifsys.stdout
isNone
(e.g. when running usingpythonw
). #313
21.1.0 - 2021-02-18#
Changed#
structlog.dev.ConsoleRenderer
will now look for alogger_name
key if nologger
key is set. #295
Fixed#
20.2.0 - 2020-12-31#
Removed#
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
Deprecated#
Accessing the
_context
attribute of a bound logger is now deprecated. Please use the newstructlog.get_context()
.
Added#
structlog
has now type hints for all of its APIs! Sincestructlog
is highly dynamic and configurable, this led to a few concessions like a specializedstructlog.stdlib.get_logger()
whose only difference tostructlog.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
Added
structlog.make_filtering_logger
that can be used likeconfigure(wrapper_class=make_filtering_bound_logger(logging.INFO))
. It creates a highly optimized bound logger whose inactive methods only consist of areturn None
. This is now also the default logger.As a complement,
structlog.stdlib.add_log_level()
can now additionally be imported asstructlog.processors.add_log_level
since it just adds the method name to the event dict.Added
structlog.BytesLogger
to avoid unnecessary encoding round trips. Concretely this is useful with orjson which returns bytes. #271The 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,Added
structlog.testing.CapturingLogger
for more unit testing goodness.Added
structlog.stdlib.AsyncBoundLogger
that executes logging calls in a thread executor and therefore doesn’t block. #245
Changed#
The default bound logger (
wrapper_class
) if you don’t configurestructlog
has changed. It’s mostly compatible with the old one but a few uncommon methods likelog
,failure
, orerr
don’t exist anymore.You can regain the old behavior by using
structlog.configure(wrapper_class=structlog.BoundLogger)
.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.ProcessorFormatter
no longer uses exceptions for control flow, allowingforeign_pre_chain
processors to usesys.exc_info()
to access the real exception.
Fixed#
structlog.PrintLogger
now supportscopy.deepcopy()
. #268
20.1.0 - 2020-01-28#
Deprecated#
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.
Added#
Added a new module
structlog.contextvars
that allows to have a global but context-localstructlog
context the same way as withstructlog.threadlocal
since 19.2.0. #201, #236Added a new module
structlog.testing
for first class testing support. The first entry is the context managercapture_logs()
that allows to make assertions about structured log calls. #14, #234Added
structlog.threadlocal.unbind_threadlocal()
. #239
Fixed#
19.2.0 - 2019-10-16#
Removed#
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.
Added#
Full Python 3.8 support for
structlog.stdlib
.Added more pass-through properties to
structlog.stdlib.BoundLogger
. To makes it easier to use it as a drop-in replacement forlogging.Logger
. #198Added new processor
structlog.dev.set_exc_info()
that will setexc_info=True
if the method’s name isexception
andexc_info
isn’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,structlog.get_logger().exception("hi")
in anexcept
block would not print the exception without passingexc_info=True
to it explicitly. #130, #173, #200, #204Added a new thread-local API that allows binding values to a thread-local context explicitly without affecting the default behavior of
bind()
. #222, #225Added pass_foreign_args argument to
structlog.stdlib.ProcessorFormatter
. It allows to pass a foreign log record’s args attribute to the event dictionary under thepositional_args
key. #228
Changed#
Fixed#
structlog.dev.ConsoleRenderer
now uses no colors by default, if colorama is not available. #215structlog.dev.ConsoleRenderer
now initializes colorama lazily, to prevent accidental side-effects just by importingstructlog
. #210A best effort has been made to make as much of
structlog
pickleable as possible to make it friendlier withmultiprocessing
and 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.processor.TimeStamper
,structlog.BoundLogger
,structlog.PrintLogger
andstructlog.dev.ConsoleRenderer
have been made pickleable. Please report if you need any another class fixed. #126
19.1.0 - 2019-02-02#
Added#
structlog.ReturnLogger
andstructlog.PrintLogger
now have afatal()
log method. #181
Changed#
Fixed#
Under certain (rather unclear) circumstances, the frame extraction could throw an
SystemError: error return without exception set
. A workaround has been added. #174
18.2.0 - 2018-09-05#
Added#
Added
structlog.stdlib.add_log_level_number()
processor that adds the level number to the event dictionary. Can be used to simplify log filtering. #151structlog.processors.JSONRenderer
now allows for overwriting the default argument of its serializer. #77, #163Added
try_unbind()
that works likeunbind()
but doesn’t raise aKeyError
if one of the keys is missing. #171
18.1.0 - 2018-01-27#
Deprecated#
The meaning of the
structlog[dev]
installation target will change from “colorful output” to “dependencies to developstructlog
” 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 astructlog[dev]
for development (pip
will report an error).
Added#
structlog.dev.ConsoleRenderer
now 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.ConsoleRenderer
now accepts a level_styles argument for overriding the colors for individual levels, as well as to add new levels. See the docs forConsoleRenderer.get_default_level_styles()
for usage. #139Added
structlog.is_configured()
to check whether or notstructlog
has been configured.Added
structlog.get_config()
to introspect current configuration.
Changed#
Fixed#
Do not encapsulate Twisted failures twice with newer versions of Twisted. #144
17.2.0 - 2017-05-15#
Added#
structlog.stdlib.ProcessorFormatter
now 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 beFalse
therefore it’s the default. #109
Fixed#
structlog.stdlib.add_logger_name()
now works instructlog.stdlib.ProcessorFormatter
’sforeign_pre_chain
. #112Clear log record args in
structlog.stdlib.ProcessorFormatter
after rendering. This fix is for you if you tried to use it and gotTypeError: not all arguments converted during string formatting
exceptions. #116, #117
17.1.0 - 2017-04-24#
The main features of this release are massive improvements in standard library’s logging
integration.
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.
Added#
Added
structlog.stdlib.render_to_log_kwargs()
. This allows you to uselogging
-based formatters to take care of rendering your entries. #98Added
structlog.stdlib.ProcessorFormatter
which does the opposite: This allows you to runstructlog
processors on arbitrarylogging.LogRecords
. #79, #105Added repr_native_str to
structlog.processors.KeyValueRenderer
andstructlog.dev.ConsoleRenderer
. This allows for human-readable non-ASCII output on Python 2 (repr()
on Python 2 behaves likeascii()
on Python 3 in that regard). As per compatibility policy, it’s on (original behavior) inKeyValueRenderer
and off (human-friendly behavior) inConsoleRenderer
. #94Added colors argument to
structlog.dev.ConsoleRenderer
and made it the default renderer. #78
Changed#
The default renderer now is
structlog.dev.ConsoleRenderer
if you don’t configurestructlog
. 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.TimeStamper
are more precise now.Positional arguments are now removed even if they are empty. #82
Fixed#
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
16.1.0 - 2016-05-24#
Removed#
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.
Added#
Added a
drop_missing
argument toKeyValueRenderer
. Ifkey_order
is used and a key is missing a value, it’s not rendered at all instead of being rendered asNone
. #67
Fixed#
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
16.0.0 - 2016-01-28#
Added#
Added
structlog.dev.ConsoleRenderer
that renders the event dictionary aligned and with colors.Added
structlog.processors.UnicodeDecoder
that will decode all byte string values in an event dictionary to Unicode.Added
serializer
parameter tostructlog.processors.JSONRenderer
which allows for using different (possibly faster) JSON encoders than the standard library.
Changed#
structlog.processors.ExceptionPrettyPrinter
andstructlog.processors.format_exc_info
now support passing of Exceptions on Python 3.six is now used for compatibility.
Fixed#
15.3.0 - 2015-09-25#
Added#
Officially support Python 3.5.
Added
structlog.ReturnLogger.failure
andstructlog.PrintLogger.failure
as preparation for the new Twisted logging system.
Fixed#
Tolerate frames without a
__name__
, better. #58
15.2.0 - 2015-06-10#
Added#
Added option to specify target key in
structlog.processors.TimeStamper
processor. #51
Changed#
Fixed#
Prevent Twisted’s
log.err
from quoting strings rendered bystructlog.twisted.JSONRenderer
.
15.1.0 - 2015-02-24#
Fixed#
Tolerate frames without a
__name__
when guessing callsite names.
15.0.0 - 2015-01-23#
Added#
Changed#
Pass positional arguments to stdlib wrapped loggers that use string formatting. #19
structlog
is now dually licensed under the Apache License, Version 2 and the MIT license. Therefore it is now legal to usestructlog
with GPLv2-licensed projects. #28
0.4.2 - 2014-07-26#
Removed#
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.
Added#
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#
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.PrintLogger
now is thread-safe.from structlog import *
works now (but you still shouldn’t use it).
0.4.1 - 2013-12-19#
Changed#
Don’t cache proxied methods in
structlog.threadlocal._ThreadLocalDictWrapper
. This doesn’t affect regular users.
Fixed#
Various doc fixes.
0.4.0 - 2013-11-10#
Added#
Added
structlog.processors.StackInfoRenderer
for adding stack information to log entries without involving exceptions. Also added it to default processor chain. #6Allow optional positional arguments for
structlog.get_logger
that are passed to logger factories. The standard library factory uses this for explicit logger naming. #12Add
structlog.processors.ExceptionPrettyPrinter
for 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
0.3.2 - 2013-09-27#
Fixed#
Fix stdlib’s name guessing.
0.3.1 - 2013-09-26#
Fixed#
Added forgotten
structlog.processors.TimeStamper
to API documentation.
0.3.0 - 2013-09-23#
Changes:#
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.stdlib.BoundLogger
.structlog.ReturnLogger
now allows arbitrary positional and keyword arguments.Add Twisted-specific BoundLogger that has an explicit API instead of intercepting unknown method calls. See
structlog.twisted.BoundLogger
.Allow logger proxies that are returned by
structlog.get_logger
andstructlog.wrap_logger
to cache the BoundLogger they assemble according to configuration on first use. See the chapter on performance and thecache_logger_on_first_use
argument ofstructlog.configure
andstructlog.wrap_logger
.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.BoundLoggerBase
.
0.2.0 - 2013-09-17#
Added#
Add
key_order
option tostructlog.processors.KeyValueRenderer
for more predictable log entries with anydict
class.Enhance Twisted support by offering JSONification of non-structlog log entries.
Allow for custom serialization in
structlog.twisted.JSONRenderer
without abusing__repr__
.
Changed#
Promote to stable, thus henceforth a strict backwards-compatibility policy is put into effect.
structlog.PrintLogger
now uses proper I/O routines and is thus viable not only for examples but also for production.
0.1.0 - 2013-09-16#
Initial release.