README.txt

Zope Event Log Manager 1.0

Chris McDonough ([email protected]) 8/13/2000

Overview

The Event Log Manager is a replacement for Zope's current event logging tool (zLOG). It has the following features:

A user interface for logging configuration.
Configurable "targets" for logging. Any number of targets may be established, and messages may be passed to the targets as defined through rules processing. Targets may be remote syslog daemons, local syslog daemons, local files, or the system console. Targets are established via a configuration file on the Zope client hard disk, and are intialized at system startup.
Complex rules processing. All messages provided to the Event Log Manager are passed through a rules processing engine. The rules processing engine decides if the message should be logged and to which targets it should be logged. Rules are established via the Zope management interface. Rules may be altered during the logger's operation.

Installation

Un-gzip and un-tar the EventLogManager1.x.tar.gz file within your Zope installation:
```
  cd /path/to/your/Zope
  tar xvzf /path/to/EventLogManager1.x.tar.gz
```
Restart your Zope installation.
Instantiate an Event Log Manager object by selecting it from the Zope "add" list.
Configure targets other than those provided by default (optional). See the section on Target Configuration.
Configure rules. See the section in this document about Rules Configuration.

General Configuration

The logging engine can be prevented from logging anything by using the "Turn Off Logging" button on the management interface. The logging engine can be reactivated by pressing the "Turn On Logging" button.

Target Configuration

The Event Log Manager target configuration file is named "eventlog.conf", and resides in the /path/to/your/Zope/lib/Python/Products/EventLogManager directory. It has a default configuration something like:

  [FileTarget0]
  Name: EventsFile
  Path: events.log  [SyslogTarget0]
  Name: LocalSyslog
  Port:
  Addr:

To add additional file targets, append a section to the configuration file in the format:

  [FileTargetX]
  Name: AnotherFile
  Path: anotherevents.log

The bracketed [FileTargetX] line refers to the section name. No two section names may be identical. File Target sections must begin with FileTarget and must end with a unique combination of digits or letters on a per-target basis. The Name: parameter provides the indentifier for the target which shows up in the Zope management interface. The Path: parameter provides the filepath. A relative file path is considered to begin in the Zope var directory.

To add additional syslog targets, append a section to the configuration file in the format:

  [SyslogTargetX]
  Name: AnotherSyslogTarget
  Port: {optional port number e.g. '514'}
  Addr: {optional host address e.g. '127.0.0.1'}

An example:

  [SyslogTarget2]
  Name: MySyslogTarget
  Port: 514
  Addr: another.server.somewhere.com

If a port and addr are provided, the syslog target is assumed to be remote. If a port or addr is not provided, the syslog target is assumed to be local, and attempts to communicate with the local syslogd via the device /dev/log (this will not work on Windows).

Rules Configuration

Rules are established via the Zope management interface for the Event Log Manager. Rules are composed of:

A rule number
A rule "on/off" button.
A rule name
A rule subject (one of subsystem, severity, summary, detail, error).
A rule predicate. Predicates may be one of either a simple Python expression e.g. (=="ZODB") or a regular expression (e.g. ^ZODB$). Predicates may also be callable objects, but this functionality is not exposed in the current implementation of the management interface.
Rule targets (selectable from those established in the target configuration file).

Five rule types exist:

Unconditional log
Conditional log
Unconditional suppress
Conditional suppress
Stop (conditional stop)

"Conditional" rules allow you to manipulate the subject and predicate of a rule. "Unconditional" rules do not. A "stop" rule is always conditional.

Rules are processed in the order in which they appear in the management interface (this might be familiar to folks who have configured firewall rules). When a message is sent to the event log, all rules are processed linearly. If the message passes all rules, it is logged according to the targets it gathers along its traversal through the rules processing engine. Thus, a ruleset consisting of the following (assume simple expression predicates):

On Rule#  Name       Type               Subject   Predicate Targets
Y  0      log all    Unconditional log  N/A       N/A       syslog1

Will log all messages to the syslog1 target. However, a rule set consisting of the following:

On Rule#  Name       Type               Subject   Predicate Targets
Y  0      log all    Unconditional log  N/A       N/A       syslog1    
Y  1      lt 100     Conditional suppr. severity  <100      syslog1

...will log only messages with severity 100 to the syslog1 target. And a ruleset consisting of:

On Rule#  Name       Type               Subject   Predicate Targets
Y  0      log all    Unconditional log  N/A       N/A       syslog1    
Y  1      lt 100     Conditional suppr. severity  <100      syslog1
Y  2      ZODB       Conditional log    subsystem =="ZODB"  eventlog1

..will log only messages with a severity less than 100 to the syslog1 target and only messages which have "ZODB" as their subsystem to the eventlog1 target.

Rules processing can be as simple or as complex as you wish it to be. It's recommended that you simplify your rules processing much as you would with firewall rule definitions so as not to unduly slow the logging process.

"Stop" rules are always conditional. If they match on an incoming message, the rules processing engine stops at that point and the targets which have been gathered during the rules processing traversal are sent the message.

"Deactivated" rules are skipped over during processing.

Predicate expressions always match against the value of the subject provided by the message as it passes through the rules processing engine. Thus, if a message comes in as (subsystem="ZODB", severity=100, summary="fubared on pack()"), a rule with a subject of subsystem, and a simple-expression predicate of =="ZODB" will match on the message. Likewise, a rule with a subject of summary and a regex expression of fubared will match on the message.

Rules with "bad" predicates (an improperly configured expression) send error output to the console and do not add their targets to the rules target result list.

It is recommended that you use regex expressions as predicates for conditional rules. For more information on regexes, see the Python.org site (search for "regular expression" or "regex", Andrew M. Kuchling has a HOWTO). Regexes comparisons in the Event Log Manager are implemented using Python's re.search() method which means they operate much like Perl regular expressions in default match mode.

Logging Usage

Call the LOG method of the Event Log Manager instance you've created with messages in the format:

ELM.LOG(subsystem:string, severity:int, summary:string, detail:string, error:3-tuple)

Only the subsystem, the severity, and the summary are required arguments, the rest are optional.

A Python code example:

def foo(self):
   self.ELM.LOG("ZODB", 100, "big problem")

A DTML code example:

<dtml-call "ELM.LOG("ZODB", 100, "big problem")">

A description of the fields is as follows:

subsystem: The subsystem generating the message (e.g. ZODB)
severity: The "severity" of the event. This may be an integer or a floating point number. Logging back ends may consider the int() of this valua to be significant. For example, a backend may consider any severity whos integer value is WARNING to be a warning.
summary: A short summary of the event
detail: A detailed description
error: A three-element tuple consisting of an error type, value, and traceback. If provided, then a summary of the error is added to the detail.

Conventional severity codes are as follows:

TRACE=-300: Trace messages
DEBUG=-200: Debugging messages
BLATHER=-100: Somebody shut this app up.
INFO=0: For things like startup and shutdown.
PROBLEM=100: This isn't causing any immediate problems, but deserves attention.
WARNING=100: A wishy-washy alias for PROBLEM.
ERROR=200: This is going to have adverse effects.
PANIC=300: We're dead!