[Python-Dev] Guidelines for Logging Usage
Michael P. Dubner
dubnerm-news at mail.ru
Mon Oct 4 23:44:58 CEST 2004
Hello,
I beg your pardon in advance for my English, which isn't my native language.
I'm posting PEProposal for discussion. Last part is reasoning for
posting it in this hot time.
I'm ready to implement it all by myself... :-)
--
Best regards,
Michael Dubner (dubnerm at mindless.com)
Brainbench MVP/HTML+JavaScript (http://www.brainbench.com)
PS: Sorry for my English
-------------- next part --------------
PEP: XXX
Title: Guidelines for Logging Usage
Version: $Revision: $
Last-Modified: $Date: $
Author: Michael P. Dubner <dubnerm at mindless.com>
Status: Draft
Type: Standards Track
Content-Type: text/plain
Created: 02-Oct-2004
Python-Version: 2.5
Post-History:
Abstract
This PEP defines guidelines for using logging system (PEP 282 [1])
in standard library.
Implementing this PEP will simplify development of daemon
applications. As a downside this PEP requires to slightly modify
(however in backportable way) large number of standard modules.
After implementing this PEP one can use following filtering
scheme::
logging.getLogger('stdlib.BaseHTTPServer').setLevel(logging.FATAL)
Rationale
There are couple of situations when output to stdout or stderr is
very incomfortable.
- Daemon application where framework doesn't allows to redirect
standard output to some file, but assumes use of some other way
of logging. Examples are syslog under *nix'es and EventLog
under WinNT+.
- GUI application which want to output every new log entry in
separate popup window (i.e. fading OSD).
Also sometimes application want to filter output enties based on
it's source or severity. This requirement can't be implemented
using simple redirection.
At last sometimes output need to be marked with time of event,
which can be acqured with logging system with ease.
Proposal
Every module usable for daemon and GUI applications should be
rewritten to use logging system instead of 'print' or
'sys.stdout.write'.
There should be code like this included in the beginning of every
modified module::
import logging
_log = logging.getLogger('stdlib.<module-name>')
Prefix of 'stdlib.' must be used by all modules
included in standard library distributed along with Python, and
only by such modules (unverifiable). Using of "_log" is
intentional as we don't want to auto-export it. For modules
that using log only in one class logger can be created inside
class definition as following::
class XXX:
__log = logging.getLogger('stdlib.<module-name>')
Then this class can create access methods to log to this private
logger.
So print's and "sys.std{out|err}.write" should be replaced with
"_log.{debug|info}" and "traceback.print_exception" with
"_log.exception" or sometimes "_log.debug('...',exc_info=1)".
Module List
Here is (possibly incomplete) list of modules to be reworked:
- asyncore (dispatcher.log, dispatcher.log_info)
- BaseHTTPServer (BaseHTTPRequestHandler.log_request,
BaseHTTPRequestHandler.log_error, BaseHTTPRequestHandler.log_message)
- cgi (possibly - is cgi.log used by somebody?)
- ftplib (if FTP.debugging)
- gopherlib (get_directory)
- httplib (HTTPResponse, HTTPConnection)
- ihooks (_Verbose)
- imaplib (IMAP4._mesg)
- mhlib (MH.error)
- nntplib (NNTP)
- pipes (Template.makepipeline)
- pkgutil (extend_path)
- platform (_syscmd_ver)
- poplib (if POP3._debugging)
- profile (if Profile.verbose)
- robotparser (_debug)
- smtplib (if SGMLParser.verbose)
- shlex (if shlex.debug)
- smtpd (SMTPChannel/PureProxy where print >> DEBUGSTREAM)
- smtplib (if SMTP.debuglevel)
- SocketServer (BaseServer.handle_error)
- telnetlib (if Telnet.debuglevel)
- threading? (_Verbose._note, Thread.__bootstrap)
- timeit (Timer.print_exc)
- trace
- uu (decode)
Additionaly there are couple of modules with commented debug
output or modules where debug output should be added. For example:
- urllib
At last possibly some modules should be extended to provide more
debug information.
Doubtful Modules
Here should be placed modules that community will propose for
addition to module list and modules that community say should be
removed from module list.
- tabnanny (check)
Guidelines for Logging Usage
Also we can provide some recommendation to authors of library
modules so they all follow same format of naming loggers.
I propose that non-standard library modules should use logger
named after their full names, so module "spam" in sub-package
"junk" of package "dummy" will be named "dummy.junk.spam" and,
of cause, "__init__" module of same package will have logger
"dummy.junk".
Implementation Schedule Proposal
As one can see whole bunch of changes required to fullfil this
proposal is rather large. I propose to delay these changes until
after 2.4 release, and change only modules critical for server
applications:
- BaseHTTPServer
- ftplib
- httplib
- poplib
- smtpd
- smtplib
- SocketServer
This can be done rather fast and reliable.
References
[1] PEP 282, A Logging System, Vinay Sajip, Trent Mick
http://www.python.org/peps/pep-0282.html
Copyright
This document has been placed in the public domain.
Local Variables:
mode: indented-text
indent-tabs-mode: nil
sentence-end-double-space: t
fill-column: 70
End:
More information about the Python-Dev
mailing list