Versions follow Calendar Versioning with a strict backwards-compatibility policy.
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 when we need to start branches for older releases (only for emergencies).
You shouldn't ever be afraid to upgrade structlog if you're using its public APIs and pay attention to DeprecationWarnings.
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.
Warning
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.
- Python 3.6 is not supported anymore.
- Pickling is now only possible with protocol version 3 and newer.
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
none
- Overloaded the
bind,unbind,try_unbindandnewmethods in theFilteringBoundLoggerProtocol. This makes it easier to use objects of typeFilteringBoundLoggerin a typed context. #392 structlog.processors.StackInfoRenderernow has an additional_ignores parameter that allows you to filter out your own logging layer. #396structlog.PrintLogger-- that is used by default -- now usesprint()for printing, making it a better citizen for interactive terminal applications. #399- Added
structlog.WriteLogger, a faster -- but more low-level -- alternative tostructlog.PrintLogger. It works the wayPrintLoggerused to work in previous versions. #403 - Better color support detection in environments with monkey-patched sys.stdout #404
none
none
- Added the
structlog.processors.LogfmtRendererprocessor to render log lines using the logfmt format. #376 - Added the
structlog.stdlib.ExtraAdderprocessor that adds extra attributes oflogging.LogRecordobjects to the event dictionary. This processor can be used for adding data passed in theextraparameter of theloggingmodule's log methods to the event dictionary. #209 #377 - Added the
structlog.processor.CallsiteParameterAdderprocessor 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
none
none
- Fixed import when running in optimized mode (
PYTHONOPTIMIZE=2orpython -OO). #373 - Added the
structlog.threadlocal.bound_threadlocalandstructlog.contextvars.bound_contextvarsdecorator/context managers to temporarily bind key/value pairs to a thread-local and context-local context. #371
structlogswitched its packaging to flit. Users shouldn't notice a difference, but (re-)packagers might.
none
structlog.dev.ConsoleRenderernow hassort_keysboolean parameter that allows to disable the sorting of keys on output. #358structlog.processors.TimeStampernow works well with FreezeGun even when it gets applied before the loggers are configured. #364structlog.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 usesync_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:
_recordand_from_structlog. With them it's possible to extract information fromlogging.LogRecords and differentiate betweenstructlogandlogginglog entries while processing them.The old processor (singular) parameter is now deprecated, but no plans exist to remove it. #365
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 configurestructlogmanually. 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 eitherrichorbetter-exceptionsis installed), a warning will be raised and the exception will be renderered without prettyfication.
none
structlogis now importable ifsys.stdoutisNone(e.g. when running usingpythonw). #313structlog.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.Tokens, allowing you to reset values using the newstructlog.contextvars.reset_contextvars(). #339Exception rendering in
structlog.dev.ConsoleLoggeris now configurable using theexception_formattersetting. If either the rich or the better-exceptions package is present,structlogwill use them for pretty-printing tracebacks.richtakes precedence overbetter-exceptionsif both are present.This only works if
format_exc_infois absent in the processor chain. #330 #349All use of
coloramaon non-Windows systems has been excised. Thus, colors are now enabled by default instructlog.dev.ConsoleRendereron non-Windows systems. You can keep usingcoloramato customize colors, of course. #345The final processor can now return a
bytearray(additionally tostrandbytes). #344
none
none
structlog.threadlocal.wrap_dict()now has a correct type annotation. #290- Fix isolation in
structlog.contextvars. #302 - The default configuration and loggers are pickleable again. #301
structlog.dev.ConsoleRendererwill now look for alogger_namekey if nologgerkey 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
structlogis now fully type-annotated. This won't break your applications, but if you use Mypy, it will most likely break your CI.Check out the new chapter on typing for details.
The default bound logger (
wrapper_class) if you don't configurestructloghas changed. It's mostly compatible with the old one but a few uncommon methods likelog,failure, orerrdon'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.
- Accessing the
_contextattribute of a bound logger is now deprecated. Please use the newstructlog.get_context().
structloghas now type hints for all of its APIs! Sincestructlogis 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_loggerthat 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_levelsince it just adds the method name to the event dict.structlog.processors.add_log_level()is now part of the default configuration.structlog.stdlib.ProcessorFormatterno longer uses exceptions for control flow, allowingforeign_pre_chainprocessors to usesys.exc_info()to access the real exception.Added
structlog.BytesLoggerto 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,structlog.PrintLoggernow supportscopy.deepcopy(). #268Added
structlog.testing.CapturingLoggerfor more unit testing goodness.Added
structlog.stdlib.AsyncBoundLoggerthat executes logging calls in a thread executor and therefore doesn't block. #245
none
- 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 a new module
structlog.contextvarsthat allows to have a global but context-localstructlogcontext the same way as withstructlog.threadlocalsince 19.2.0. #201, #236 - Added a new module
structlog.testingfor first class testing support. The first entry is the context managercapture_logs()that allows to make assertions about structured log calls. #14, #234 - Added
structlog.threadlocal.unbind_threadlocal(). #239 - The logger created by
structlog.get_logger()is not detected as an abstract method anymore, when attached to an abstract base class. #229 coloramaisn't initialized lazily on Windows anymore because it breaks rendering. #232, #242
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
structlogwill break under 3.4 anytime soon, but we don't test it anymore.
none
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.ProcessorFormatternow takes a logger object as an optional keyword argument. This makesProcessorFormatterwork properly withstuctlog.stdlib.filter_by_level(). #219structlog.dev.ConsoleRenderernow uses no colors by default, ifcoloramais not available. #215structlog.dev.ConsoleRenderernow initializescoloramalazily, to prevent accidental side-effects just by importingstructlog. #210Added new processor
structlog.dev.set_exc_info()that will setexc_info=Trueif the method's name isexceptionandexc_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,structlog.get_logger().exception("hi")in anexceptblock would not print the exception without passingexc_info=Trueto it explicitly. #130, #173, #200, #204A best effort has been made to make as much of
structlogpickleable as possible to make it friendlier withmultiprocessingand 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.PrintLoggerandstructlog.dev.ConsoleRendererhave 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_argsargument tostructlog.stdlib.ProcessorFormatter. It allows to pass a foreign log record'sargsattribute to the event dictionary under thepositional_argskey. #228structlog.dev.ConsoleRenderernow callsstr()on the event value. #221
- As announced in 18.1.0,
pip install -e .[dev]now installs all development dependencies. Sorry for the inconveniences this undoubtedly will cause!
none
structlog.ReturnLoggerandstructlog.PrintLoggernow have afatal()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 structlognow tolerates passing throughdicts to stdlib logging. #187, #188, #189
none
none
- Added
structlog.stdlib.add_log_level_number()processor that adds the level number to the event dictionary. Can be used to simplify log filtering. #151 structlog.processors.JSONRenderernow allows for overwriting the default argument of its serializer. #77, #163- Added
try_unbind()that works likeunbind()but doesn't raise aKeyErrorif one of the keys is missing. #171
none
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
structlogin your normal dependencies and additionally astructlog[dev]for development (pipwill report an error).
- Empty strings are valid events now. #110
- Do not encapsulate Twisted failures twice with newer versions of Twisted. #144
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 forConsoleRenderer.get_default_level_styles()for usage. #139structlog.stdlib.BoundLogger.exception()now uses theexc_infoargument if it has been passed instead of setting it unconditionally toTrue. #149- Default configuration now uses plain
dicts on Python 3.6+ and PyPy since they are ordered by default. - Added
structlog.is_configured()to check whether or notstructloghas been configured. - Added
structlog.get_config()to introspect current configuration.
none
none
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 beFalsetherefore it's the default. #109structlog.stdlib.add_logger_name()now works instructlog.stdlib.ProcessorFormatter'sforeign_pre_chain. #112- Clear log record args in
structlog.stdlib.ProcessorFormatterafter rendering. This fix is for you if you tried to use it and gotTypeError: not all arguments converted during string formattingexceptions. #116, #117
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.
- The default renderer now is
structlog.dev.ConsoleRendererif 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.
- Added
structlog.stdlib.render_to_log_kwargs(). This allows you to uselogging-based formatters to take care of rendering your entries. #98 - Added
structlog.stdlib.ProcessorFormatterwhich does the opposite: This allows you to runstructlogprocessors on arbitrarylogging.LogRecords. #79, #105 - UNIX epoch timestamps from
structlog.processors.TimeStamperare more precise now. - Added repr_native_str to
structlog.processors.KeyValueRendererandstructlog.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) inKeyValueRendererand off (humand-friendly behavior) inConsoleRenderer. #94 - Added colors argument to
structlog.dev.ConsoleRendererand made it the default renderer. #78 - Fixed 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. #92 - Positional arguments are now removed even if they are empty. #82
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.
- Add a
drop_missingargument toKeyValueRenderer. Ifkey_orderis used and a key is missing a value, it's not rendered at all instead of being rendered asNone. #67 - 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.processors.ExceptionPrettyPrinterandstructlog.processors.format_exc_infonow support passing of Exceptions on Python 3.- Clean up the context when exiting
structlog.threadlocal.tmp_bindin case of exceptions. #64 - Be more more lenient about missing
__name__s. #62 - Add
structlog.dev.ConsoleRendererthat renders the event dictionary aligned and with colors. - Use six for compatibility.
- Add
structlog.processors.UnicodeDecoderthat will decode all byte string values in an event dictionary to Unicode. - Add
serializerparameter tostructlog.processors.JSONRendererwhich allows for using different (possibly faster) JSON encoders than the standard library.
- Tolerate frames without a
__name__, better. #58 - Officially support Python 3.5.
- Add
structlog.ReturnLogger.failureandstructlog.PrintLogger.failureas preparation for the new Twisted logging system.
- 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.errfrom quoting strings rendered bystructlog.twisted.JSONRenderer. - Better support of
logging.Logger.exceptionwithinstructlog. #52 - Add option to specify target key in
structlog.processors.TimeStamperprocessor. #51
- Tolerate frames without a
__name__.
- Add
structlog.stdlib.add_log_levelandstructlog.stdlib.add_logger_nameprocessors. #44 - Add
structlog.stdlib.BoundLogger.log. #42 - Pass positional arguments to stdlib wrapped loggers that use string formatting. #19
structlogis 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. #28- Add
structlog.stdlib.BoundLogger.exception. #22
- 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.- 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).
- Don't cache proxied methods in
structlog.threadlocal._ThreadLocalDictWrapper. This doesn't affect regular users. - Various doc fixes.
- Add
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 - Add
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.
- Add forgotten
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.stdlib.BoundLogger. structlog.ReturnLoggernow 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_loggerandstructlog.wrap_loggerto cache the BoundLogger they assemble according to configuration on first use. See the chapter on performance and thecache_logger_on_first_useargument ofstructlog.configureandstructlog.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.
- Promote to stable, thus henceforth a strict backwards-compatibility policy is put into effect.
- Add
key_orderoption tostructlog.processors.KeyValueRendererfor more predictable log entries with anydictclass. structlog.PrintLoggernow 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.JSONRendererwithout abusing__repr__.
Initial release.