Skip to content

Commit 39fb96d

Browse files
committed
docs: add gotchas section
1 parent 7f13b3b commit 39fb96d

File tree

1 file changed

+20
-0
lines changed

1 file changed

+20
-0
lines changed

README.md

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -233,6 +233,26 @@ logging.setLogRecordFactory(record_factory)
233233
This will cause all logs to have the `trace_id=123` pair regardless of including
234234
`trace_id` in keys or manually adding `trace_id` to the `extra` parameter or the `msg` object.
235235

236+
## Gotchas
237+
238+
**Reserved Keys**
239+
240+
The standard library logging system restricts the ability to pass internal [log record attributes](https://docs.python.org/3/library/logging.html#logrecord-attributes) via the log call's `extra` parameter.
241+
242+
```py
243+
> logging.error("invalid", extra={"filename": "alpha.txt"})
244+
Traceback (most recent call last):
245+
...
246+
```
247+
248+
This can be circumvented by utilizing logfmter's ability to pass extras
249+
via the log call's `msg` argument.
250+
251+
```py
252+
> logging.error({"msg": "valid", "filename": "alpha.txt"})
253+
at=ERROR msg=valid filename=alpha.txt
254+
```
255+
236256
# Development
237257

238258
## Required Software

0 commit comments

Comments
 (0)