Opened 13 years ago

Closed 13 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: no

Description

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.

[1] https://docs.djangoproject.com/en/1.3/topics/logging/

Change History (2)

comment:1 by Aymeric Augustin, 13 years ago

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

[1] http://docs.python.org/library/logging.config.html#configuration-dictionary-schema

[2] https://docs.djangoproject.com/en/1.3/topics/logging/#configuring-logging

Excerpt:

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 links 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.

Last edited 13 years ago by Aymeric Augustin (previous) (diff)

comment:2 by Aymeric Augustin, 13 years ago

Resolution: worksforme
Status: newclosed

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