Opened 5 years ago

Closed 5 years ago

#16140 closed Uncategorized (worksforme)

Logging documentation should describe how to configure logging handlers.

Reported by: ShawnMilo Owned by: nobody
Component: Documentation Version: 1.3
Severity: Normal Keywords:
Cc: Triage Stage: Unreviewed
Has patch: no Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: yes UI/UX:


The logging documentation [1] is incomplete and confusing to users unfamiliar with the logging module's dictionary configs, and Python's own docs are pretty poor on this so they don't take up the slack.

Specifically, I think our docs should explain how to specify the filename used by a handler that writes to a file, by adding the 'filename' key to the dictionary, and elaborate by saying that any kwarg accepted by any handler type's init may be used here.

This tripped me up, and I just saw the same question asked on django-users by someone trying to figure out how to configure a SysLogHandler.


Change History (2)

comment:1 Changed 5 years ago by aaugustin

  • Needs documentation unset
  • Needs tests unset
  • Patch needs improvement unset

Everything is described in [1] which is linked at the very beginning of [2].




All other keys are passed through as keyword arguments to the handler’s constructor.

That sounds clear and straightforward There's even an example with a 'filename' just below. So I don't really understand why you find that the docs are poor or that this information is difficult to find.

The logging documentation may be intimidating, but:

  • I really believe that this information belongs to Python's docs, and that it's not a good idea to start duplicating information in Django's docs,
  • There are already exactly the proper link in Django's docs.
  • Django developers are expected to be able to read 10 lines from the Python docs.

So I'm rather strongly -1.

Version 0, edited 5 years ago by aaugustin (next)

comment:2 Changed 5 years ago by aaugustin

  • Resolution set to worksforme
  • Status changed from new to closed

Since nobody disagreed with my first comment after I asked on IRC, I am going to reject the ticket. Basically I don't see how we could improve the docs with regard to the points you raised.

Note: See TracTickets for help on using tickets.
Back to Top