added basic logging support

Author: Richard Jones

CHANGES.txt

@@ -8,6 +8,7 @@ Feature:
 - implement __nonzero__ for HTMLProperty
 - remove "manual" locking of sqlite database
 - create a new RDBMS cursor after committing
+- added basic logging, and configuration of it and python's logging module
 
 
 2004-??-?? 0.7.4

doc/customizing.txt

@@ -2,7 +2,7 @@
 Customising Roundup
 ===================
 
-:Version: $Revision: 1.136 $
+:Version: $Revision: 1.137 $
 
 .. This document borrows from the ZopeBook section on ZPT. The original is at:
    http://www.zope.org/Documentation/Books/ZopeBook/current/ZPT.stx
@@ -156,6 +156,22 @@ The configuration variables available are:
   also useful if you want to switch your 'new message' notification to
   a central user. 
 
+**LOGGGING_CONFIG** - ``os.path.join(TRACKER_HOME, 'logging.ini')``
+  This variable activates logging of Roundup's internal messages using the
+  standard python ``logging`` module. The module is configured using the
+  indicated configuration file.
+
+**LOGGING_FILENAME** - ``'/path/to/log file'``
+  This variable activates logging of Roundup's internal messages using a
+  built-in minimal logging service which appends messages to the indicated
+  file.
+
+**LOGGING_LEVEL** - ``'DEBUG'``, ``'INFO'``, ``'WARNING'`` or ``'ERROR'``
+  This variable determines the level of messages logged by the built-in
+  logging service - messages of the level named and higher will be sent to
+  the ``LOGGING_FILENAME`` file. Not used when the ``LOGGGING_CONFIG``
+  variable is set.
+
 **MESSAGES_TO_AUTHOR** - ``'new'``, ``'yes'`` or``'no'``
  Send nosy messages to the author of the message?
  If 'new' is used, then the author will only be sent the message when the
@@ -244,6 +260,19 @@ tracker is attempted.::
     # trouble
     ADMIN_EMAIL = 'roundup-admin@%s'%MAIL_DOMAIN
 
+    # These variables define where to log Roundup's internal messages to.
+    # You have two choices - either using the standard Python logging module
+    # or a minimal logging facility built into Roundup. The former is activated
+    # when you provide a LOGGING_CONFIG variable below which contains the
+    # configuration of the logging module. The latter is activated when you
+    # provide the LOGGING_FILENAME and optionally LOGGING_LEVEL variables. If
+    # none of these variables are defined then only errors will be logged, and
+    # they will go to stderr.
+    # LOGGGING_CONFIG = os.path.join(TRACKER_HOME, 'logging.ini')
+    # or,
+    # LOGGING_FILENAME = '/path/to/log file'
+    # LOGGING_LEVEL = 'INFO'   # one of 'DEBUG', 'INFO', 'WARNING', 'ERROR'
+
     # Additional text to include in the "name" part of the From: address
     # used in nosy messages. If the sending user is "Foo Bar", the From:
     # line is usually: "Foo Bar" <[email protected]>

doc/whatsnew-0.8.txt

@@ -0,0 +1,18 @@
+=========================
+What's New in Roundup 0.8
+=========================
+
+For those completely new to Roundup, you might want to look over the very
+terse features__ page.
+
+__ features.html
+
+.. contents::
+
+Logging of internal messages
+============================
+
+TODO
+
+
+.. _`customisation documentation`: customizing.html

roundup/instance.py

@@ -15,7 +15,7 @@
 # BASIS, AND THERE IS NO OBLIGATION WHATSOEVER TO PROVIDE MAINTENANCE,
 # SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
 # 
-# $Id: instance.py,v 1.13 2004-05-10 00:34:48 richard Exp $
+# $Id: instance.py,v 1.14 2004-06-08 05:29:18 richard Exp $
 
 '''Tracker handling (open tracker).
 
@@ -24,6 +24,7 @@
 __docformat__ = 'restructuredtext'
 
 import os
+from roundup import rlog
 
 class Vars:
     ''' I'm just a container '''
@@ -91,6 +92,24 @@ def open(self, tracker_home):
                 raise TrackerError, \
                     'Required tracker attribute "%s" missing'%required
 
+        # init the logging
+        config = tracker.config
+        if hasattr(config, 'LOGGING_CONFIG'):
+            try:
+                import logging
+                config.logging = logging
+            except ImportError, msg:
+                raise TrackerError, 'Python logging module unavailable: %s'%msg
+            config.logging.fileConfig(config.LOGGING_CONFIG)
+        elif hasattr(config, 'LOGGING_FILENAME'):
+            config.logging = rlog.BasicLogging()
+            config.logging.setFile(config.LOGGING_FILENAME)
+            if hasattr(config, 'LOGGING_LEVEL'):
+                config.logging.setLevel(config.LOGGING_LEVEL)
+        else:
+            config.logging = rlog.BasicLogging()
+            config.logging.setLevel('ERROR')
+
         return tracker
 
 OldStyleTrackers = OldStyleTrackers()

roundup/rlog.py

@@ -0,0 +1,123 @@
+'''Roundup basic logging support.
+
+This module will use the standard Python logging implementation when
+available. If not, then a basic logging implementation, BasicLogging and
+BasicLoggingChannel will be used.
+
+Configuration for "logging" module:
+ - tracker configuration file specifies the location of a logging
+   configration file as LOGGING_CONFIG
+ - roundup-server and roundup-mailgw specify the location of a logging
+   configuration file on the command line
+Configuration for "BasicLogging" implementation:
+ - tracker configuration file specifies the location of a log file
+   LOGGING_FILENAME
+ - tracker configuration file specifies the level to log to as
+   LOGGING_LEVEL
+ - roundup-server and roundup-mailgw specify the location of a log
+   file on the command line
+ - roundup-server and roundup-mailgw specify the level to log to on
+   the command line
+
+In both cases, if no logfile is specified then logging will simply be sent
+to sys.stderr with only logging of ERROR messages.
+
+In terms of the Roundup code using the logging implementation:
+ - a "logging" object will be available on the "config" object for each
+   tracker
+ - the roundup-server and roundup-mailgw code will have a global "logging"
+   object.
+
+It is intended that the logger API implementation here be the same as (or
+close enough to) that of the standard Python library "logging" module.
+'''
+import sys, time, traceback
+
+class BasicLogging:
+    LVL_DEBUG = 4
+    LVL_INFO = 3
+    LVL_WARNING= 2
+    LVL_ERROR= 1
+    LVL_NONE = 0
+    NAMES = {
+        LVL_DEBUG: 'DEBUG',
+        LVL_INFO: 'INFO',
+        LVL_WARNING: 'WARNING',
+        LVL_ERROR: 'ERROR',
+    }
+    level = LVL_INFO
+    loggers = {}
+    file = None
+    def getLogger(self, name):
+        return self.loggers.setdefault(name, BasicLogger(self.file, self.level))
+    def fileConfig(self, filename):
+        '''User is attempting to use a config file, but the basic logger
+        doesn't support that.'''
+        raise RuntimeError, "File-based logging configuration requires "\
+            "the logging package."
+    def setFile(self, file):
+        '''Set the file to log to. "file" is either an open file object or
+        a string filename to append entries to.
+        '''
+        if isinstance(file, type('')):
+            file = open(file, 'a')
+        self.file = file
+    def setLevel(self, level):
+        '''Set the maximum logging level. "level" is either a level number
+        (one of the LVL_ values) or a string level name.
+        '''
+        if isinstance(level, type('')):
+            for num, name in self.NAMES:
+                if name == level:
+                    level = num
+        self.level = level
+
+class BasicLogger:
+    '''Used when the standard Python library logging module isn't available.
+    
+    Supports basic configuration through the tracker config file vars
+    LOGGING_LEVEL and LOGGING_FILENAME.'''
+    def __init__(self, file, level):
+        self.file = file
+        self.level = level
+
+    def setFile(self, file):
+        '''Set the file to log to. "file" is either an open file object or
+        a string filename to append entries to.
+        '''
+        if isinstance(file, type('')):
+            file = open(file, 'a')
+        self.file = file
+    def setLevel(self, level):
+        '''Set the maximum logging level. "level" is either a level number
+        (one of the LVL_ values) or a string level name.
+        '''
+        if isinstance(level, type('')):
+            for num, name in BasicLogging.NAMES:
+                if name == level:
+                    level = num
+        self.level = level
+    def write(self, level, message):
+        message = '%s %s %s'%(time.strftime('%Y-%m-%d %H:%M:%D'),
+            BasicLogging.NAMES[level], message)
+        self._write(message)
+    def _write(self, text):
+        file = self.file or sys.stderr
+        file.write(text)
+    def debug(self, message):
+        if self.level < BasicLogging.LVL_DEBUG: return
+        self.write(BasicLogging.LVL_DEBUG, message)
+    def info(self, message):
+        if self.level < BasicLogging.LVL_INFO: return
+        self.write(BasicLogging.LVL_INFO, message)
+    def warning(self, message):
+        if self.level < BasicLogging.LVL_WARNING: return
+        self.write(BasicLogging.LVL_WARNING, message)
+    def error(self, message):
+        if self.level < BasicLogging.LVL_ERROR: return
+        self.write(BasicLogging.LVL_ERROR, message)
+    def exception(self, message):
+        if self.level < BasicLogging.LVL_ERROR: return
+        self.write(BasicLogging.LVL_ERROR, message)
+        self._write(traceback.format_exception(*(sys.exc_info())))
+

templates/classic/config.py

@@ -15,7 +15,7 @@
 # BASIS, AND THERE IS NO OBLIGATION WHATSOEVER TO PROVIDE MAINTENANCE,
 # SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
 # 
-# $Id: config.py,v 1.8 2004-03-26 23:45:34 richard Exp $
+# $Id: config.py,v 1.9 2004-06-08 05:29:18 richard Exp $
 
 import os
 
@@ -63,6 +63,19 @@
 # The email address that roundup will complain to if it runs into trouble
 ADMIN_EMAIL = 'roundup-admin@%s'%MAIL_DOMAIN
 
+# These variables define where to log Roundup's internal messages to.
+# You have two choices - either using the standard Python logging module
+# or a minimal logging facility built into Roundup. The former is activated
+# when you provide a LOGGING_CONFIG variable below which contains the
+# configuration of the logging module. The latter is activated when you
+# provide the LOGGING_FILENAME and optionally LOGGING_LEVEL variables. If
+# none of these variables are defined then only errors will be logged, and
+# they will go to stderr.
+# LOGGGING_CONFIG = os.path.join(TRACKER_HOME, 'logging.ini')
+# or,
+# LOGGING_FILENAME = '/path/to/log file'
+# LOGGING_LEVEL = 'INFO'   # one of 'DEBUG', 'INFO', 'WARNING', 'ERROR'
+
 # The 'dispatcher' is a role that can get notified of new items to the
 # database. It is used by the ERROR_MESSAGES_TO config setting.
 DISPATCHER_EMAIL = ADMIN_EMAIL

templates/minimal/config.py

@@ -15,7 +15,7 @@
 # BASIS, AND THERE IS NO OBLIGATION WHATSOEVER TO PROVIDE MAINTENANCE,
 # SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
 # 
-# $Id: config.py,v 1.6 2004-03-26 23:45:34 richard Exp $
+# $Id: config.py,v 1.7 2004-06-08 05:29:18 richard Exp $
 
 import os
 
@@ -63,6 +63,19 @@
 # The email address that roundup will complain to if it runs into trouble
 ADMIN_EMAIL = 'roundup-admin@%s'%MAIL_DOMAIN
 
+# These variables define where to log Roundup's internal messages to.
+# You have two choices - either using the standard Python logging module
+# or a minimal logging facility built into Roundup. The former is activated
+# when you provide a LOGGING_CONFIG variable below which contains the
+# configuration of the logging module. The latter is activated when you
+# provide the LOGGING_FILENAME and optionally LOGGING_LEVEL variables. If
+# none of these variables are defined then only errors will be logged, and
+# they will go to stderr.
+# LOGGGING_CONFIG = os.path.join(TRACKER_HOME, 'logging.ini')
+# or,
+# LOGGING_FILENAME = '/path/to/log file'
+# LOGGING_LEVEL = 'INFO'   # one of 'DEBUG', 'INFO', 'WARNING', 'ERROR'
+
 # The 'dispatcher' is a role that can get notified of new items to the database.
 DISPATCHER_EMAIL = ADMIN_EMAIL
 

test/test_rlog.py

@@ -0,0 +1,48 @@
+import unittest, StringIO
+
+from roundup import rlog
+
+class LoggingTestCase(unittest.TestCase):
+    def setUp(self):
+        self.logging = rlog.BasicLogging()
+        self.file = StringIO.StringIO()
+        self.logging.setFile(self.file)
+    def testLevels(self):
+        logger = self.logging.getLogger('test')
+        v1 = self.file.getvalue()
+        logger.debug('test')
+        v2 = self.file.getvalue()
+        self.assertEqual(v1, v2, 'Logged when should not have')
+
+        v1 = self.file.getvalue()
+        logger.info('test')
+        v2 = self.file.getvalue()
+        self.assertNotEqual(v1, v2, 'Nothing logged')
+
+        v1 = self.file.getvalue()
+        logger.warning('test')
+        v2 = self.file.getvalue()
+        self.assertNotEqual(v1, v2, 'Nothing logged')
+
+        v1 = self.file.getvalue()
+        logger.error('test')
+        v2 = self.file.getvalue()
+        self.assertNotEqual(v1, v2, 'Nothing logged')
+
+        v1 = self.file.getvalue()
+        try:
+            1/0
+        except:
+            logger.exception('test')
+        v2 = self.file.getvalue()
+        self.assertNotEqual(v1, v2, 'Nothing logged')
+
+def test_suite():
+    suite = unittest.TestSuite()
+    suite.addTest(unittest.makeSuite(LoggingTestCase))
+    return suite
+
+if __name__ == '__main__':
+    runner = unittest.TextTestRunner()
+    unittest.main(testRunner=runner)
+