Changelog¶
Versions are year-based with a strict backward compatibility policy. The third digit is only for regressions.
20.1.0 (2020-01-28)¶
Backward-incompatible changes:¶
none
Deprecations:¶
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.
Changes:¶
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()
. #239The logger created by
structlog.get_logger()
is not detected as an abstract method anymore, when attached to an abstract base class. #229colorama
isn’t initialized lazily on Windows anymore because it breaks rendering. #232, #242
19.2.0 (2019-10-16)¶
Backward-incompatible changes:¶
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.
Deprecations:¶
none
Changes:¶
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
. #198structlog.stdlib.ProcessorFormatter
now takes a logger object as an optional keyword argument. This makesProcessorFormatter
work properly withstuctlog.stdlib.filter_by_level()
. #219structlog.dev.ConsoleRenderer
now uses no colors by default, ifcolorama
is not available. #215structlog.dev.ConsoleRenderer
now initializescolorama
lazily, to prevent accidental side-effects just by importingstructlog
. #210Added 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, #204A 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 pickelable. Please report if you need any another class fixed. #126Added 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 tostructlog.stdlib.ProcessorFormatter
. It allows to pass a foreign log record’sargs
attribute to the event dictionary under thepositional_args
key. #228structlog.dev.ConsoleRenderer
now callsstr()
on the event value. #221
19.1.0 (2019-02-02)¶
Backward-incompatible changes:¶
As announced in 18.1.0,
pip install -e .[dev]
now installs all development dependencies. Sorry for the inconveniences this undoubtedly will cause!
Deprecations:¶
none
Changes:¶
structlog.ReturnLogger
andstructlog.PrintLogger
now have afatal()
log method. #181Under certain (rather unclear) circumstances, the frame extraction could throw an
SystemError: error return without exception set
. A workaround has been added. #174structlog
now tolerates passing throughdict
s to stdlib logging. #187, #188, #189
18.2.0 (2018-09-05)¶
Backward-incompatible changes:¶
none
Deprecations:¶
none
Changes:¶
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)¶
Backward-incompatible changes:¶
none
Deprecations:¶
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 developement (pip
will report an error).
Changes:¶
Empty strings are valid events now. #110
Do not encapsulate Twisted failures twice with newer versions of Twisted. #144
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. #139structlog.stdlib.BoundLogger.exception()
now uses theexc_info
argument if it has been passed instead of setting it unconditionally toTrue
. #149Default configuration now uses plain
dict
s on Python 3.6+ and PyPy since they are ordered by default.Added
structlog.is_configured()
to check whether or notstructlog
has been configured.Added
structlog.get_config()
to introspect current configuration.
17.2.0 (2017-05-15)¶
Backward-incompatible changes:¶
none
Deprecations:¶
none
Changes:¶
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. #109structlog.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.
Backward-incompatible changes:¶
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 backward compatibility policy that explicitly excludes default settings.
Changes:¶
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, #105UNIX epoch timestamps from
structlog.processors.TimeStamper
are more precise now.Added 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 (humand-friendly behavior) inConsoleRenderer
. #94Added colors argument to
structlog.dev.ConsoleRenderer
and made it the default renderer. #78Fixed bug with Python 3 and
structlog.stdlib.BoundLogger.log()
. Error log level was not reproductible and was logged as exception one time out of two. #92Positional arguments are now removed even if they are empty. #82
16.1.0 (2016-05-24)¶
Backward-incompatible changes:¶
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.
Changes:¶
Add 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
. #67Exceptions 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)¶
Changes:¶
structlog.processors.ExceptionPrettyPrinter
andstructlog.processors.format_exc_info
now support passing of Exceptions on Python 3.Clean up the context when exiting
structlog.threadlocal.tmp_bind
in case of exceptions. #64Be more more lenient about missing
__name__
s. #62Add
structlog.dev.ConsoleRenderer
that renders the event dictionary aligned and with colors.Use six for compatibility.
Add
structlog.processors.UnicodeDecoder
that will decode all byte string values in an event dictionary to Unicode.Add
serializer
parameter tostructlog.processors.JSONRenderer
which allows for using different (possibly faster) JSON encoders than the standard library.
15.3.0 (2015-09-25)¶
15.2.0 (2015-06-10)¶
Changes:¶
Allow empty lists of processors. This is a valid use case since #26 has been merged. Before, supplying an empty list resulted in the defaults being used.
Prevent Twisted’s
log.err
from quoting strings rendered bystructlog.twisted.JSONRenderer
.Better support of
logging.Logger.exception
withinstructlog
. #52Add option to specify target key in
structlog.processors.TimeStamper
processor. #51
15.0.0 (2015-01-23)¶
Changes:¶
Add
structlog.stdlib.add_log_level
andstructlog.stdlib.add_logger_name
processors. #44Add
structlog.stdlib.BoundLogger.log
. #42Pass 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 use structlog with GPLv2-licensed projects. #28Add
structlog.stdlib.BoundLogger.exception
. #22
0.4.2 (2014-07-26)¶
Changes:¶
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.Test Twisted-related code on Python 3 (with some caveats).
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
from structlog import *
works now (but you still shouldn’t use it).
0.4.1 (2013-12-19)¶
Changes:¶
Don’t cache proxied methods in
structlog.threadlocal._ThreadLocalDictWrapper
. This doesn’t affect regular users.Various doc fixes.
0.4.0 (2013-11-10)¶
Backward-incompatible changes:¶
Changes:¶
Add
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.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)¶
Changes:¶
Promote to stable, thus henceforth a strict backward compatibility policy is put into effect.
Add
key_order
option tostructlog.processors.KeyValueRenderer
for more predictable log entries with anydict
class.structlog.PrintLogger
now uses proper I/O routines and is thus viable not only for examples but also for production.Enhance Twisted support by offering JSONification of non-structlog log entries.
Allow for custom serialization in
structlog.twisted.JSONRenderer
without abusing__repr__
.
0.1.0 (2013-09-16)¶
Initial release.