Skip to content

Commit 72943b3

Browse files
sirosenhynek
andauthored
Add a recipe for customizing exc dict formatting (#817)
* Add a recipe for customizing exc dict formatting A new recipe titled "Custom Filtering of Dict Tracebacks" shows how to subclass an ExceptionDictTransformer, dig around in the chain of exceptions, sift through "locals", and make in-place modifications. As a good demo of the sort of expensive function you might want to tie to such operations, the example defines "high entropy strings" as anything with a Shannon Entropy > 4.0 (which is arbitrary but somewhat low). In the `exceptions` documentation, a link is provided to this example along with a direct indication that users should start by looking at the parameters for `ExceptionDictTransformer`, which covers most cases. resolves #789, #715 * Remove 'high entropy string' example from recipes Per review, it's too likely that someone will pick this example up and run it without understanding that "entropy" does not measure whether or not a string is a secret. Co-authored-by: Hynek Schlawack <[email protected]> * Add cautionary note to 'custom dict trace' recipe * Apply suggestions from code review Two blank lines before section headers Co-authored-by: Hynek Schlawack <[email protected]> --------- Co-authored-by: Hynek Schlawack <[email protected]> Co-authored-by: Hynek Schlawack <[email protected]>
1 parent fcdca9f commit 72943b3

2 files changed

Lines changed: 49 additions & 0 deletions

File tree

‎docs/exceptions.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,12 @@ The most common use-cases are already covered by the following processors:
2727
: Uses {class}`structlog.tracebacks.ExceptionDictTransformer` to give you a structured and JSON-serializable `exception` key.
2828

2929

30+
### Customizing Dict Tracebacks
31+
32+
{class}`structlog.tracebacks.ExceptionDictTransformer` can be customized with a number of parameters.
33+
If these prove insufficient, see {ref}`Custom Filtering of Dict Tracebacks <custom-dict-tracebacks>`.
34+
35+
3036
## Console rendering
3137

3238
Our {doc}`console-output`'s {class}`structlog.dev.ConsoleRenderer` takes an *exception_formatter* argument that allows for customizing the output of exceptions.

‎docs/recipes.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -141,6 +141,49 @@ These two methods and one attribute are all you need to write own *bound loggers
141141
[dry]: https://en.wikipedia.org/wiki/Don%27t_repeat_yourself
142142

143143

144+
(custom-dict-tracebacks)=
145+
146+
## Custom Filtering of Dict Tracebacks
147+
148+
Dict traceback printing via {class}`structlog.tracebacks.ExceptionDictTransformer` may expose values in logs which you do not want.
149+
For example, tokens and credentials are easily captured in locals and logged.
150+
151+
As a simple control, you can set `show_locals=False`.
152+
For more extensive customization, subclass the transformer.
153+
154+
{class}`ExceptionDictTransformer <structlog.tracebacks.ExceptionDictTransformer>`'s `__call__` is responsible for converting exception info into a list of dicts.
155+
Because this is only called during exception handling, it's an ideal point of control for potentially expensive filtering functionality.
156+
157+
The following example customizes the transformer to redact values in `locals` named `"token"` or `"password"`.
158+
159+
```
160+
from structlog.tracebacks import ExceptionDictTransformer
161+
162+
163+
def redact_locals(frame_locals):
164+
return {
165+
k: (v if k not in ("token", "password") else "<REDACTED>")
166+
for k, v in frame_locals.items()
167+
}
168+
169+
170+
def redact_frames(exc_dict):
171+
for frame in exc_dict["frames"]:
172+
if "locals" in frame:
173+
frame["locals"] = redact_locals(frame["locals"])
174+
return exc_dict
175+
176+
177+
class RedactingExceptionDictTransformer(ExceptionDictTransformer):
178+
def __call__(self, exc_info):
179+
exceptions = super().__call__(exc_info)
180+
return [redact_frames(exc) for exc in exceptions]
181+
```
182+
183+
Please remember that values may appear elsewhere in the dict traceback, for example in an exception string.
184+
If you remove data from `locals`, that does not guarantee that it is removed entirely from the log.
185+
186+
144187
## Passing context to worker threads
145188

146189
Thread-local context data based on [context variables](contextvars.md) is -- as the name says -- local to the thread that binds it.

0 commit comments

Comments
 (0)