more logging goodness

Author: Richard Jones

TODO.txt

@@ -3,6 +3,8 @@ This file contains items that need doing before the next release:
 Required:
 - documentation of i18n: TAL tags for translation
 - translation databases in trackers
+- implementing of logging for roundup-server, including command-line
+  switches
 
 
 Optionally:

doc/admin_guide.txt

@@ -2,7 +2,7 @@
 Administration Guide
 ====================
 
-:Version: $Revision: 1.11 $
+:Version: $Revision: 1.12 $
 
 .. contents::
 
@@ -40,6 +40,34 @@ There's two "installations" that we talk about when using Roundup:
    config.py.
 
 
+Configuring Roundup's Logging of Messages For Sysadmins
+=======================================================
+
+You may configure where Roundup logs messages in your tracker's config.py
+file. Roundup will use the standard Python logging implementation when
+available. If not, then a very basic logging implementation will be used
+(see BasicLogging in the roundup.rlog module for details).
+
+Configuration for "logging" module:
+ - tracker configuration file specifies the location of a logging
+   configration file as ``LOGGING_CONFIG``
+ - ``roundup-server`` specifies 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`` specifies the location of a log file on the command
+   line
+ - ``roundup-server`` specifies the level to log to on the command line
+
+(``roundup-mailgw`` always logs to the tracker's log file)
+
+In both cases, if no logfile is specified then logging will simply be sent
+to sys.stderr with only logging of ERROR messages.
+
+
 Users and Security
 ==================
 
@@ -76,6 +104,7 @@ Email Registration
 More information about how to customise your tracker's security settings
 may be found in the `customisation documentation`_.
 
+
 Tasks
 =====
 

doc/customizing.txt

@@ -2,7 +2,7 @@
 Customising Roundup
 ===================
 
-:Version: $Revision: 1.141 $
+:Version: $Revision: 1.142 $
 
 .. This document borrows from the ZopeBook section on ZPT. The original is at:
    http://www.zope.org/Documentation/Books/ZopeBook/current/ZPT.stx
@@ -159,18 +159,18 @@ The configuration variables available are:
 **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.
+  indicated configuration file. See the `admin guide`_ for more detail.
 
 **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.
+  file. See the `admin guide`_ for more detail.
 
 **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.
+  variable is set. See the `admin guide`_ for more detail.
 
 **MESSAGES_TO_AUTHOR** - ``'new'``, ``'yes'`` or``'no'``
  Send nosy messages to the author of the message?
@@ -267,7 +267,7 @@ tracker is attempted.::
     # 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.
+    # they will go to stderr. See the Admin Guide for more detail.
     # LOGGGING_CONFIG = os.path.join(TRACKER_HOME, 'logging.ini')
     # or,
     # LOGGING_FILENAME = '/path/to/log file'
@@ -4057,4 +4057,5 @@ Back to `Table of Contents`_
 
 .. _`Table of Contents`: index.html
 .. _`design documentation`: design.html
+.. _`admin guide`: admin_guide.html
 

doc/upgrading.txt

@@ -44,6 +44,9 @@ Lines ``meta http-equiv`` added to the tracker templates in version 0.6.0
 are misleading and should be removed.  Actual charset is sent in the
 true http header.
 
+0.8.0 Logging Configuration
+---------------------------
+
 
 Migrating from 0.7.2 to 0.7.3
 =============================