1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
|
# Exceptions
While you should use a proper crash reporter like [Sentry](https://sentry.io) 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 {func}`sys.exc_info`.
2. If the value is an Exception, render it.
3. If the value is true but no tuple, call {func}`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 {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.
## Console rendering
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.
:::
[*better-exceptions*]: https://github.com/qix-/better-exceptions
[Rich]: https://github.com/Textualize/rich
|
