PEP #: 44

 TITLE: Logging Enhancements

 Version :  1.1

 Authors: Mike Day, Dave Rosckes, Chuck Carmack

 State: APPROVED

 Approvals Required: Architecture Board or Steering Committee

 Type:  design

 Created: 28/02/03

 Version History:

  version        date                authors            Reason
  1.0             28/02/03        (above)             Initial version
  1.1             04/03/03        (above)             Initial version

  Summary

This proposal is to upgrade the Pegasus logging component and logging points to the standard expected for commercial daemon services.   The first goal is to support a "flight recorder" logging feature in Pegasus, and the necessary logging points to use it.  The second goal is to change the logging component to allow Pegasus logging messages to be written to native platform logging systems such as the syslog daemon on Unix.

  This PEP will not be fully implemented in Pegasus 2.2.  Items that will be deferred as labeled as future below.  What will be implemented is support for the "flight recorder" through the use of the logLevel configuration property (formally named severity).  Additional logging points will be added to the code as needed for flight recording and general error logs.  Finally, platform maintainers will be asked to consider adding code to Logger to log to the platform logs.

  Problem Solved/Feature Added

The logging component in Pegasus 2.1 is minimally implemented and rarely used. There are too few logging points in the source code and no mechansim to control the level of logging.  There must be sufficient logging points throughout the Pegasus source code to enable all relevent events to be logged, and to provide sufficient information about each event to solve problems, handle events, and generally manage the lifetime and utility of Pegasus.

  The current trace facility in Pegasus is useful for programmers to do low-level debug in the field.  However, the tracing in Pegasus has some short-comings for use as a service tool:

This PEP proposes support for a "flight recorder".  A "flight recorder" is a limited set of log entries that can be used to determine the states of Pegasus at key codepoints that lead up to the log recording the failure.  An example might be connection log entries that indicate the state of simultaneous client requests at the time of failure.

  In the typical service scenario the service engineer will first analyze the log entry recording the failure, then turn on flight recording if needed, and finally turn on debug trace if needed.  Customers may want to leave flight recording on, but with the understanding that these log entries will clutter the system log.

 Overview of new features:

 Proposal 1:  Analyze the code and add logging points as needed for flight recording and error logging.

 Proposal 2:  Remove severity as valid cimconfig property and add logLevel as valid cimconfig property.  Implement the logLevel property to control the types of logs created, with the TRACE classification acting as the "flight recorder".  This allows customers to control the logging with the cimconfig command.  The "flight recorder" logs will be disabled by default. All other log types will be enabled by default.

 Proposal 3: Enable platforms to send all log entries, including TRACE, to the system logs where the customers would expect them.  (Platform maintainers have the final say of where log entries are sent) Platforms that will support using system logs will define PEGASUS_USE_SYSLOGS.  They will need to support the System class abtraction for the syslog calls in Logger, this will remove most of the platform specific code from the Logger.  Those platforms not supporting syslogs will continue to use the log file method.

 Future: NLS enabling. Log messages must be separated from the source code to allow for translation and internationalization.

  More details on these proposals are given below.

  Definition of Pegasus Log Entry Classifications

Currently the logger has the following log classifications:

  TRACE
              Information that enables problem solving in the field
  INFORMATION
              General low-priority nominal events
  WARNING
              Events that may be a problem or may indication a future problem
  SEVERE
             Error, serious.
  FATAL
             Fatal error or event that requires immediate response

  This set of classifications is sufficient for Pegasus 2.2.  The TRACE classification will be used for the "flight recorder".

  In a future release we may expand on these classifications to be more consistent with the Unix syslog classes which are defined below in priority order:

 
  Debug
  Information that enables problem solving in the field
  Info
  General low-priority nominal events
  Notice
  Events that signal a change in state or execution path
  Warning
  Events that may be a problem or may indication a future problem
  Err
  Error, nominal
  Crit
  Error, serious.
  Alert
            Event (not necesarily an error) that requires notification to other components, services, or programs.
  Emerg
            Fatal error or event that requires immediate response

  Support for configuration property : logLevel

The logLevel property is new, it will be replacing the severity property not currently implemented.  This PEP proposes to implement this new property.

  The logLevel property will be used to allow the logging level to be specified.  The log levels are ordered in priority so all logs with the same or higher priority as the logLevel property will be logged.   For  Example:
  logLevel=FATAL                    -- Log only FATAL errors
  logLevel=INFORMATION    -- Log INFORMATION,WARNING,SEVERE,FATAL errors
  logLevel=TRACE                    -- Log TRACE,INFORMATION,WARNING,SEVERE,FATAL errors

  When classifications are added in future releases the user will not be required to change the logLevel to pick up higher priority logs.  For Example:

  logLevel=SEVERE                   -- If a classification is added with a higher priority than SEVERE the user will automatically log the new classification.

  The default setting for this property will be to enable all log classifications except TRACE.

  This will allow the user to indicate what level of logging they need.

  Additional logging points

Analysis of the code will be required to determine where logging points are needed.  While this work will be done under this PEP, this will be an ongoing effort, release to release, as we become more experienced with debugging customer problems.
 

  Integration with platform's native logging service

Basic support for logging to text files should be retained in Pegasus 2.2. However, the Logger class needs to be modified to defer to system logging services such as Unix syslog daemon, the Windows event log, and OS/400 job log.  Abstract log APIs will be added to System class and will be called from the logger for platforms that support system logs.

  Definition of Pegasus Logging Components (Future release)

Pegasus logging components need to be defined and supported in the Logger class. Logging needs to be configurable on a per-component basis.

 The design of log components is TBD at this time.  The design is likely to follow the Unix pattern, where the "component" name sent to openlog (ie. the "ident" parm ) is the top-level name of each serviceable part of  Pegasus.  That is, the main server will be logged as component "CIMServer" to the system logs (ie. ident = "CIMServer").  Providers (serviced separately) will have "ident" component names of their choosing (TBD).

 The Logger::put method already has a systemId parameter that maps directly to the "ident" parm on openlog.  For this reason, there is no reason to change Logger::put.  Current calls to Logger::put will be changed to pass in "CIMServer" on the systemID parm.  There will be a const String("CIMServer") declared for internal Pegasus code to use for the systemId.

 However, it would be useful for TRACE logs to indicate which internal Pegasus component (Security, Repository, etc) is doing the trace.  For this reason, a new Logger::trace( ) method will be added for TRACE logs.  This method will have a parameter for the internal Pegasus component id.  Calls will be added to Pegasus for TRACE logs, with component id's defined as needed.  The component id's will be similiar to the traceComponent id's.  However, since this design is not finalized, the log component id will be ignored by the trace method.  For the same reason, a logComponent config property will not be exposed in cimconfig.

  A tentative list of Pegasus logging components includes the following:

  Security
  Authentication and authorization events
  Connection
  Connection and termination of clients
  Repository
  Repository write events
  Provider
  Provider load/unload and operation execution events
  Exceptions
  Errors and Exceptions
  Lifetime

          Start, stop, install, remove.

 External Logger APIs:

 // Existing Logger put API is unchanged , except that the severity parm is renamed to logLevel.
 void Logger::put(
     LogFileType logFileType,
     const    String& systemId,
     Uint32 logLevel,
     const     String& formatString,
     const     Formatter::Arg& arg0,
     const     Formatter::Arg& arg1,
     const     Formatter::Arg& arg2,
     const     Formatter::Arg& arg3,
     const     Formatter::Arg& arg4,
     const     Formatter::Arg& arg5,
     const     Formatter::Arg& arg6,
     const     Formatter::Arg& arg7,
     const     Formatter::Arg& arg8,
     const     Formatter::Arg& arg9);
 

 // New Logger trace API.  The logLevel is forced to TRACE (ie. no parm for this)
 void Logger::trace(
     LogFileType logFileType,
     const    String& systemId,
     const    Uint32 logComponent,
     const     String& formatString,
     const     Formatter::Arg& arg0,
     const     Formatter::Arg& arg1,
     const     Formatter::Arg& arg2,
     const     Formatter::Arg& arg3,
     const     Formatter::Arg& arg4,
     const     Formatter::Arg& arg5,
     const     Formatter::Arg& arg6,
     const     Formatter::Arg& arg7,
     const     Formatter::Arg& arg8,
     const     Formatter::Arg& arg9);
 
 

 Schedule and Risks

The goal is to add the logging calls to Pegasus 2.2 .  While it may not be possible to cover every error case in Pegasus 2.2, enough logging calls should be added for minimal serviceability.  This means that all main components in Pegasus have logs for major errors.

 We are working toward this timeline:
 March 14, 2003 - PEP is approved and base code (ie. changes to Logger) is committed
 March 21, 2003 - Finish analysis of code for additional logging points in Pegasus 2.2.
 March 28, 2003 - New logging calls added to the code, tested, and committed.


  -----------------------------15905617825425 Content-Disposition: form-data; name="_grd_fn2"; filename=""