Some example outputs for the documentation

[FichteFoll]

Context: I am looking to migrate our internal logging utility that was based on <2.0.7 to 3.x. I initially wanted to request some example outputs, but as I continued to read the docs, I wrote down more questions that I couldn't (immediately) answer by reading them.

---

First of all, thanks for continuing development & maintenance of this library.

In the entire documentation, there is only a single example currently where the output of python-json-logger is mentioned: On the landing page. It would be nice to see the outcomes of some of the examples directly in the docs to get a better understanding of what the various options and usage patterns result in. Especially the examples for defaults and static_fields on the Quick Start page could use some expected result examples to better explain their behavior on the emitted log message.

On that topic, I'd also be interested in the exact interactions of static_fields with defaults and per-record extras, because unless extra is forbidden from overriding static_fields, I don't see a difference between defaults and static_fields currently. rename_fields might make a difference here, but I don't see the use case for that either if all parameters can be fully controlled by the user.

Furthermore, the docs example for "Default Fields" uses extras for the log record argument where I believe it should be extra, but I have not verified that.

We use add_fields to override the emitted log fields for each record, e.g. to add a severity level and a timestamp. I suspect this to be a quite common use case for the JSON formatter, so it should be added to the Cookbok page imo.

Finally, a migration guide when coming from version <3.0.0 would be neat, though since the old API was basically maintained, probably not necessary.

[nhairs]

Hi @FichteFoll,

In order: (also on mobile so poor formatting)

That's a good point about the examples. It would be good for them to be programmatically generated to avoid becoming stale which is probably why I didn't add them in when I took over.

Agreed that it should be more clearly explained the interactions between default and static fields.

Defaults are added before any other field so can be overridden by any later step. Static fields are added after required fields so can only be overridden by the record. This probably should be changed to be the very last step so that they truly are static, however that would break backwards compatibility - we should change this in v4 to better match the name.

Rename fields is applied to every possible input: defaults, required, static, and message fields.

You're right extras is probably a bug here.

I thought add fields would be covered by the request id cookbook example but I'm happy to add more.

Yes that is why I did not add a migration guide for 3.0.0.

Overall I'm happy to take PRs to improve the docs.

[FichteFoll]

I thought add fields would be covered by the request id cookbook example but I'm happy to add more.

You're right, a new method named process_log_record is mentioned there. I was Ctrl+F-ing for add_fields and assumed this topic was not covered when I couldn't find it.

On that topic, while I took a brief look at the code: … moved to #38.

[nhairs]

Yeah it feels like there are too many functions being called and that potentially it should all be wrapped in the one add_fields method. e.g. there's also merge_record_extra.