Code

Opened 3 years ago

Closed 3 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:

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/

Attachments (0)

Change History (2)

comment:1 Changed 3 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].

[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 3 years ago by aaugustin (previous) (diff)

comment:2 Changed 3 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.

Add Comment

Modify Ticket

Change Properties
<Author field>
Action
as closed
as The resolution will be set. Next status will be 'closed'
The resolution will be deleted. Next status will be 'new'
Author


E-mail address and user name can be saved in the Preferences.

 
Note: See TracTickets for help on using tickets.