.. _api:
API Reference
=============
.. note::
The examples here use a very simplified configuration using the minimalist `structlog.processors.KeyValueRenderer` for brevity and to enable doctests.
The output is going to be different (nicer!) with the default configuration.
.. testsetup:: *
import structlog
structlog.configure(
processors=[structlog.processors.KeyValueRenderer()],
)
.. testcleanup:: *
import structlog
structlog.reset_defaults()
.. module:: structlog
`structlog` Package
-------------------
.. autofunction:: get_logger
.. autofunction:: getLogger
.. autofunction:: wrap_logger
.. autofunction:: configure
.. autofunction:: configure_once
.. autofunction:: reset_defaults
.. autofunction:: is_configured
.. autofunction:: get_config
.. autoclass:: BoundLogger
:members: new, bind, unbind
.. autofunction:: make_filtering_bound_logger
.. autofunction:: get_context
.. autoclass:: PrintLogger
:members: msg, err, debug, info, warning, error, critical, log, failure, fatal
.. autoclass:: PrintLoggerFactory
.. autoclass:: WriteLogger
:members: msg, err, debug, info, warning, error, critical, log, failure, fatal
.. autoclass:: WriteLoggerFactory
.. autoclass:: BytesLogger
:members: msg, err, debug, info, warning, error, critical, log, failure, fatal
.. autoclass:: BytesLoggerFactory
.. autoexception:: DropEvent
.. autoclass:: BoundLoggerBase
:members: new, bind, unbind, try_unbind, _logger, _process_event, _proxy_to_logger
`structlog.dev` Module
----------------------
.. automodule:: structlog.dev
.. autoclass:: ConsoleRenderer
:members: get_default_level_styles
.. autoclass:: Column
.. autoclass:: ColumnFormatter(typing.Protocol)
:members: __call__
.. autoclass:: KeyValueColumnFormatter
.. autoclass:: LogLevelColumnFormatter
.. autofunction:: plain_traceback
.. autoclass:: RichTracebackFormatter
.. autofunction:: rich_traceback
.. autofunction:: better_traceback
.. autofunction:: set_exc_info
`structlog.testing` Module
--------------------------
.. automodule:: structlog.testing
.. autofunction:: capture_logs
.. autoclass:: LogCapture
.. autoclass:: CapturingLogger
>>> from pprint import pprint
>>> cl = structlog.testing.CapturingLogger()
>>> cl.info("hello")
>>> cl.info("hello", when="again")
>>> pprint(cl.calls)
[CapturedCall(method_name='info', args=('hello',), kwargs={}),
CapturedCall(method_name='info', args=('hello',), kwargs={'when': 'again'})]
.. autoclass:: CapturingLoggerFactory
.. autoclass:: CapturedCall
.. autoclass:: ReturnLogger
:members: msg, err, debug, info, warning, error, critical, log, failure, fatal
.. autoclass:: ReturnLoggerFactory
`structlog.contextvars` Module
------------------------------
.. automodule:: structlog.contextvars
.. autofunction:: bind_contextvars
.. autofunction:: bound_contextvars
.. autofunction:: get_contextvars
.. autofunction:: get_merged_contextvars
.. autofunction:: merge_contextvars
.. autofunction:: clear_contextvars
.. autofunction:: unbind_contextvars
.. autofunction:: reset_contextvars
`structlog.threadlocal` Module
------------------------------
.. automodule:: structlog.threadlocal
:noindex:
.. _procs:
`structlog.processors` Module
-----------------------------
.. automodule:: structlog.processors
.. autoclass:: JSONRenderer
.. doctest::
>>> from structlog.processors import JSONRenderer
>>> JSONRenderer(sort_keys=True)(None, None, {"a": 42, "b": [1, 2, 3]})
'{"a": 42, "b": [1, 2, 3]}'
Bound objects are attempted to be serialize using a ``__structlog__`` method.
If none is defined, ``repr()`` is used:
.. doctest::
>>> class C1:
... def __structlog__(self):
... return ["C1!"]
... def __repr__(self):
... return "__structlog__ took precedence"
>>> class C2:
... def __repr__(self):
... return "No __structlog__, so this is used."
>>> from structlog.processors import JSONRenderer
>>> JSONRenderer(sort_keys=True)(None, None, {"c1": C1(), "c2": C2()})
'{"c1": ["C1!"], "c2": "No __structlog__, so this is used."}'
Please note that additionally to strings, you can also return any type the standard library JSON module knows about -- like in this example a list.
If you choose to pass a *default* parameter as part of *dumps_kw*, support for ``__structlog__`` is disabled.
That can be useful with more elegant serialization methods like `functools.singledispatch`: `Better Python Object Serialization `_.
It can also be helpful if you are using *orjson* and want to rely on it to serialize `datetime.datetime` and other objects natively.
.. tip::
If you use this processor, you may also wish to add structured tracebacks for exceptions.
You can do this by adding the :class:`~structlog.processors.dict_tracebacks` to your list of processors:
.. doctest::
>>> structlog.configure(
... processors=[
... structlog.processors.dict_tracebacks,
... structlog.processors.JSONRenderer(),
... ],
... )
>>> log = structlog.get_logger()
>>> var = "spam"
>>> try:
... 1 / 0
... except ZeroDivisionError:
... log.exception("Cannot compute!")
{"event": "Cannot compute!", "exception": [{"exc_type": "ZeroDivisionError", "exc_value": "division by zero", "syntax_error": null, "is_cause": false, "frames": [{"filename": "", "lineno": 2, "name": "", "line": "", "locals": {..., "var": "spam"}}]}]}
.. autoclass:: KeyValueRenderer
.. doctest::
>>> from structlog.processors import KeyValueRenderer
>>> KeyValueRenderer(sort_keys=True)(None, None, {"a": 42, "b": [1, 2, 3]})
'a=42 b=[1, 2, 3]'
>>> KeyValueRenderer(key_order=["b", "a"])(None, None,
... {"a": 42, "b": [1, 2, 3]})
'b=[1, 2, 3] a=42'
.. autoclass:: LogfmtRenderer
.. doctest::
>>> from structlog.processors import LogfmtRenderer
>>> event_dict = {"a": 42, "b": [1, 2, 3], "flag": True}
>>> LogfmtRenderer(sort_keys=True)(None, None, event_dict)
'a=42 b="[1, 2, 3]" flag'
>>> LogfmtRenderer(key_order=["b", "a"], bool_as_flag=False)(None, None, event_dict)
'b="[1, 2, 3]" a=42 flag=true'
.. autoclass:: EventRenamer
.. autofunction:: add_log_level
.. autoclass:: UnicodeDecoder
.. autoclass:: UnicodeEncoder
.. autoclass:: ExceptionRenderer
.. autofunction:: format_exc_info
.. doctest::
>>> from structlog.processors import format_exc_info
>>> try:
... raise ValueError
... except ValueError:
... format_exc_info(None, None, {"exc_info": True}) # doctest: +ELLIPSIS
{'exception': 'Traceback (most recent call last):...
.. autofunction:: dict_tracebacks
.. doctest::
>>> from structlog.processors import dict_tracebacks
>>> try:
... raise ValueError("onoes")
... except ValueError:
... dict_tracebacks(None, None, {"exc_info": True}) # doctest: +ELLIPSIS
{'exception': [{'exc_type': 'ValueError', 'exc_value': 'onoes', ..., 'frames': [{'filename': ...
.. autoclass:: StackInfoRenderer
.. autoclass:: ExceptionPrettyPrinter
.. autoclass:: TimeStamper
.. doctest::
>>> from structlog.processors import TimeStamper
>>> TimeStamper()(None, None, {}) # doctest: +SKIP
{'timestamp': 1378994017}
>>> TimeStamper(fmt="iso")(None, None, {}) # doctest: +SKIP
{'timestamp': '2013-09-12T13:54:26.996778Z'}
>>> TimeStamper(fmt="%Y", key="year")(None, None, {}) # doctest: +SKIP
{'year': '2013'}
.. autoclass:: MaybeTimeStamper
.. doctest::
>>> from structlog.processors import MaybeTimeStamper
>>> MaybeTimeStamper()(None, None, {}) # doctest: +SKIP
{'timestamp': 1690036074.494428}
>>> MaybeTimeStamper()(None, None, {"timestamp": 42})
{'timestamp': 42}
.. autoclass:: CallsiteParameter
:members:
.. autoclass:: CallsiteParameterAdder
`structlog.stdlib` Module
-------------------------
.. automodule:: structlog.stdlib
.. autofunction:: recreate_defaults
.. autofunction:: get_logger
.. autoclass:: BoundLogger
:members: bind, unbind, try_unbind, new, debug, info, warning, warn, error, critical, exception, log, adebug, ainfo, awarning, aerror, acritical, aexception, alog
.. autoclass:: AsyncBoundLogger
:members: sync_bl
.. autoclass:: LoggerFactory
:members: __call__
.. autofunction:: render_to_log_kwargs
.. autofunction:: filter_by_level
.. autofunction:: add_log_level
.. autofunction:: add_log_level_number
.. autofunction:: add_logger_name
.. autofunction:: ExtraAdder
.. autoclass:: PositionalArgumentsFormatter
.. autoclass:: ProcessorFormatter
:members: wrap_for_formatter, remove_processors_meta
`structlog.tracebacks` Module
-----------------------------
.. automodule:: structlog.tracebacks
.. autofunction:: extract
.. autoclass:: ExceptionDictTransformer
.. autoclass:: Trace
.. autoclass:: Stack
.. autoclass:: Frame
.. autoclass:: SyntaxError_
`structlog.typing` Module
-------------------------
.. automodule:: structlog.typing
.. autoclass:: BindableLogger
Additionally to the methods listed below, bound loggers **must** have a ``__init__`` method with the following signature:
.. method:: __init__(self, wrapped_logger: WrappedLogger, processors: Iterable[Processor], context: Context) -> None
:noindex:
Unfortunately it's impossible to define initializers using :pep:`544` Protocols.
They currently also have to carry a `Context` as a ``_context`` attribute.
.. note::
Currently Sphinx has no support for Protocols, so please click ``[source]`` for this entry to see the full definition.
.. autoclass:: FilteringBoundLogger
.. note::
Currently Sphinx has no support for Protocols, so please click ``[source]`` for this entry to see the full definition.
.. autoclass:: ExceptionTransformer
.. note::
Currently Sphinx has no support for Protocols, so please click ``[source]`` for this entry to see the full definition.
.. autodata:: EventDict
.. autodata:: WrappedLogger
.. autodata:: Processor
.. autodata:: Context
.. autodata:: ExcInfo
.. autodata:: ExceptionRenderer
`structlog.twisted` Module
--------------------------
.. automodule:: structlog.twisted
.. autoclass:: BoundLogger
:members: bind, unbind, new, msg, err
.. autoclass:: LoggerFactory
:members: __call__
.. autoclass:: EventAdapter
.. autoclass:: JSONRenderer
.. autofunction:: plainJSONStdOutLogger
.. autofunction:: JSONLogObserverWrapper
.. autoclass:: PlainFileLogObserver