[Python-Dev] Guidelines for Logging Usage

[Michael P. Dubner]

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: