Hide navigation sidebar
Hide table of contents sidebar
Skip to content
Back to top
Toggle table of contents sidebar

# Exceptions

While you should use a proper crash reporter like Sentry in production, structlog has helpers for formatting exceptions for humans and machines.

All structlog’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:

1. If the value is a tuple, render it as if it was returned by `sys.exc_info()`.

2. If the value is an Exception, render it.

3. If the value is true but no tuple, call `sys.exc_info()` and 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.

## Transformations

structlog comes with `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:

`structlog.processors.format_exc_info()`

  Formats it to a flat string like the standard library would on the console.

`structlog.processors.dict_tracebacks`

  Uses `structlog.tracebacks.ExceptionDictTransformer` to give you a structured and JSON-serializable `exception` key.

## Console rendering

Our Console Output’s `structlog.dev.ConsoleRenderer` takes an exception_formatter argument that allows for customizing the output of exceptions.

`structlog.dev.plain_traceback()`

  Is the default if neither Rich nor better-exceptions are installed. As the name suggests, it renders a plain traceback.

`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.

`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.

See also

Console Output for more information on structlog’s console features.