nhairs / nhairs/python-json-logger

Some example outputs for the documentation

Open
#36 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

documentation user support
Dominant language
Python
Stars
270
Forks
21
PR merge metrics
No merged PRs in 30d

Description

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.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Review the landing-page Quick Start, the Default Fields example, and the Cookbook sections, then compare the documented behavior of defaults, static_fields, extra, rename_fields, and add_fields. Done means the requested output examples, corrected argument name, add_fields use case, and any agreed migration guidance are documented, with the open behavior questions resolved first.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.