While you should use a proper crash reporter like our sponsor Sentry in production, structlog has helpers for formatting exceptions for humans and machines.
All structog's exception features center around passing an exc_info key-value pair in the event dict.
There are three possible behaviors depending on its value:
- If the value is a tuple, render it as if it was returned by {func}
sys.exc_info. - If the value is an Exception, render it.
- If the value is true but no tuple, call {func}
sys.exc_infoand render that.
If there is no exc_info key or false, the event dict is not touched.
This behavior is analog to the one of the stdlib's logging.
structlog comes with {class}structlog.processors.ExceptionRenderer that deduces and removes the exc_info key as outlined above, calls a user-supplied function with the synthesized exc_info, and stores its return value in the exception key.
The most common use-cases are already covered by the following processors:
{func}structlog.processors.format_exc_info
: Formats it to a flat string like the standard library would on the console.
{obj}structlog.processors.dict_tracebacks
: Uses {class}structlog.tracebacks.ExceptionDictTransformer to give you a structured and JSON-serializable exception key.
Our {doc}console-output's {class}structlog.dev.ConsoleRenderer takes an exception_formatter argument that allows for customizing the output of exceptions.
{func}structlog.dev.plain_traceback
: Is the default if neither Rich nor better-exceptions are installed. As the name suggests, it renders a plain traceback.
{func}structlog.dev.better_traceback
: Uses better-exceptions to render a colorful traceback. : It's the default if better-exceptions is installed and Rich is not.
{class}structlog.dev.RichTracebackFormatter
: Uses Rich to render a colorful traceback. It's a class because it allows for customizing the output by passing arguments to Rich. : It's the default if Rich is installed.
:::{seealso}
{doc}console-output for more information on structlog's console features.
:::