Pegasus Enhancement Proposal (PEP)

PEP #: 206

Title: System Log Indication Handler

Version: 1.3

Created: 27 October 2004

Authors: Yi Zhou

Status: Approved

Version History:

Abstract: This PEP proposes the addition of a new Indication Handler to OpenPegasus release 2.5. The System Log Indication Handler is being proposed to enable CIM indications to be delivered to a system log file.

Definition of the Problem

System Log facility (e.g. syslog) is already widely used in Pegasus. However, Pegasus currently does not support event notification delivery to system log file.

Proposed Solution

This PEP proposes to define a new type of Indication Handler, System Log Indication Handler. The System Log Indication Handler will allow indications to be delivered to a system log file.

The proposed solution will meet following requirements:

• Each system log file entry (e.g. in the syslog file) should have a well-defined tag (e.g. "CIM Indication") to distinguish an entry made by System Log Indication Handler.
• If an indication contains severity information(e.g. An alert indication may have severity value), the severity of the indication should be mapped to system log error severity.
• The format and details of an event in the system log file must follow DMTF specification.

The proposal would require the following changes:

1. Define a new CIM_ListenerDestination subclass, PG_ListenerDestinationSystemLog.

// ====================================================================
// PG_ListenerDestinationSystemLog
// ====================================================================
   [Description (
     "PG_ListenerDestinationSystemLog is used to support event notification "
     "delivery to a system log file")]

class PG_ListenerDestinationSystemLog: CIM_ListenerDestination
{
};

2. Use the following association (CIM v2.9) allows formatting of message.

// ====================================================================
// CIM_FormattedIndicationSubscription
// ====================================================================

      [Association, Version ( "2.8.1000" ), Experimental, Description (
          "A subclass of IndicationSubscription that defines the "
          "text formatting of Indication information. The "
          "TextFormatOwningEntity, TextFormatID, TextFormat, and "
          "TextFormatParameters properties are used to describe "
          "a human-readable representation of the Indication as "
          "defined by the referenced CIM_IndicationFilter. This "
          "representation MAY be used by the CIM_ListenerDestination "
          "when the intended consumer of the Indication is human. "
          "For example, this format could be used when writing the "
          "Indication to a system log or sending an e-mail "
          "notification to a system administrator.")]

class CIM_FormattedIndicationSubscription : CIM_IndicationSubscription 
      [Description (
          "The TextFormatOwningEntity is a string that uniquely "
          "identifies the entity that owns the definition of " 
          "the human-readable format described in this instance. "
          "OwningEntity MUST include a copyrighted, trademarked "
          "or otherwise unique name that is owned by the business "
          "entity or standards body defining the format."),
      ModelCorrespondence {
          "CIM_FormattedIndicationSubscription.TextFormatID",
          "CIM_FormattedIndicationSubscription.TextFormat",
          "CIM_FormattedIndicationSubscription.TextFormatParameters"} ] 
   string TextFormatOwningEntity;

      [Description (
          "An opaque string that uniquely identifies, within the scope "
          "of the TextFormatOwningEntity, a human-readable format "
          "for representing the Indications described by this " 
          "Subscription."),
      ModelCorrespondence {
          "CIM_FormattedIndicationSubscription.TextFormatOwningEntity",
          "CIM_FormattedIndicationSubscription.TextFormat",
          "CIM_FormattedIndicationSubscription.TextFormatParameters"} ] 
   string TextFormatID;

      [Description (
           "A string describing the human-readable format for "
           "representing the Indications described by this "
           "Subscription. The actual text is constructed by applying "
           "the dynamic content, defined in the Indication, to the "
           "string specified in this property. /n /n The dynamic "
           "content is specified by embedding the following syntax in "
           "the appropriate places in the format string: \n"
           "\"{\" <index >["["[<index>]"]"],<type>\"}\" \n"
           "- the first occurrence of <index> defines the element "
           "of TextFormatParameters that contains the name of the "
           "Indication property to be used to populate the text "
           "message.\n"
           "- if the Indication property defined by the first <index> "
           "is an array property, then the first index MUST be followed "
           "by either empty brackets (i.e., []) or an index value "
           "enclosed in brackets (e.g., [1]).  If empty brackets are "
           "specified (e.g., {4[], string}), then the dynamic content "
           "of the text message is populated with a list of the array "
           "elements. If an index is specified (e.g., {4[1], string}, "
           "then only the specified array element is used to populate "
           "the message. If the value of the dynamic content is not "
           "defined in the Indication, then the string \"UNKNOWN\" "
           "is used to populate the text message.\n"
           "-  defines the type of the dynamic content. Valid "
           "values for  are: \'boolean\', \'string\', \'char16\', "
           "\'uint8\', \'sint8\', \'uint16\', \'sint16\', \'uint32\', "
           "\'sint32\', \'uint64\', \'sint64\', \'datetime\', "
           "\'real32\', \'real64\' or \'ref\'. \n"
           "\n"
           "As an example, a format string for a UPS AlertIndication "
           "could be defined as follows: \"A {4,string} UPS Alert of "
           "type {5,uint16} was detected on the device {6,string} on "
           "the system {2,string} at {1,datetime}. The following "
           "actions have been recommended to resolve the alert: "
           "{3[],string}\".")]
      ModelCorrespondence {
          "CIM_FormattedIndicationSubscription.TextFormatOwningEntity",
          "CIM_FormattedIndicationSubscription.TextFormatID",
          "CIM_FormattedIndicationSubscription.TextFormatParameters"} ] 
   string TextFormat;
      [Description (
          "An indexed array containing the names of properties defined "
          "in the select clause of the associated CIM_IndicationFilter "

          "Query.  The values of these Indication properties are used "
          "to populate the dynamic content of the text message."),
      ArrayType ( "Indexed" ),
      ModelCorrespondence {
          "CIM_FormattedIndicationSubscription.TextFormatOwningEntity",
          "CIM_FormattedIndicationSubscription.TextFormatID",
          "CIM_FormattedIndicationSubscription.TextFormat"} ]
    string TextFormatParameters [];
};

3. Severity: CR InterOp215 has proposed promoting the PerceivedSeverity property defined in CIM_AlertIndication to CIM_Indication so that any indication instance (not just Alert indication instance) could contain severity information. If an indication contains severity information (e.g. a subscriber may include the PerceivedSeverity property in the SELECT list of the filter condition), the PerceivedSeverity will be mapped to Pegasus Logger severity. The mapping is:

   PerceivedSeverity                     Pegasus LogLevel 
   ====================                  ========================
   Fatal/NonRecoverable    ===>          Logger::FATAL 
   Critical                ===>          Logger::FATAL 
   Major                   ===>          Logger::SEVERE 
   Minor                   ===>          Logger::WARNING 
   Degraded/Warning        ===>          Logger::WARNING 
   Information             ===>          Logger::INFORMATION 
   Other                   ===>          Logger::INFORMATION 
   Unknown                 ===>          Logger::INFORMATION 
   

   If PEGASUS_USE_SYSLOG is defined, the System Log Handler passes the Pegasus severity to System::syslog and there is a mapping in System::syslog from Pegasus severity to syslog error severity today.

4. Indication Format: A new class IndicationFormatter is created in the directory pegasus/src/Pegasus/Common. The IndicationFormatter will be put in Common because both the SystemLog and Email Handlers will need to use it. A separate library just for IndicationFormatter would affect packaging, and so would not be an ideal solution. Because this is not an external interface, it can later be moved out of Common without affecting binary compatibility, when Common is restructured.
   This class constructs a human readable indication text message from the specified indication TextFormat (a string describing the human-readable format for representing the Indications described by the subscription), indication TextFormatParameters that contains the name of the Indication property to be used to populate the text message, and received indication instance. Any non-string substitutions will be localized by using ICU Format classes (CIMDateTime substitutions may need to convert the CIM format string to an ICU format string) if the Content-Languages in the subscription instance does not have multiple language tags. If the Content-Languages in the subscription instance has multiple language tags, the non-string substitutions will not be localized.

      The class is as follows: 
      class PEGASUS_COMMON_LINKAGE IndicationFormatter
      {
      public:

          String formatIndicationText(
              const String & textFormat,
              const Array& textFormatParams,
              const CIMInstance & indicationInstance,
              const ContentLanguages & contentLangs)

      private:
          ...
          ...
      };
    

The formatting and details of an event are based on both property values of TextFormat and TextFormatParameter in a CIM_FormattedIndicationSubscription instance. If the property TextFormat is not found, or the value of TextFormat is Null, or the value of TextFormat has a syntax error, received indication will be written in the system log entry with default format and with a pretext: "Indication (default format):".
The default format looks like: Indication (default format): Property1_Name " = " Property1_value ", " Property2_name " = " Property2_value ...

For example, if a query is "SELECT IndicationIdentifier, IndicationTime FROM..." The default formatted indication looks like:

Indication (default format): IndicationIdentifier = 1, IndicationTime = 20040920102527.711962-420.
5. Indication Service is updated to support PG_ListenerDestinationSystemLog class and CIM_FormattedIndicationSubscription class. The way of Indication Service supporting CIM_FormattedIndicationSubscription class is same as supporting CIM_IndicationSubscription class. When a CIM_FormattedIndicationSubscription instance is created, or deleted, or modified, Indication Service is doing same thing as a CIM_IndicationSubscription instance is created, or deleted, or modified. Also, Indication Service will reject to create a CIM_FormattedIndicationSubscription instance if the value of TextFormat has a syntax error etc.
6. Modify Indication Handler Service to support the class PG_ListenerDestinationSystemLog.
7. Modify CIMHandleIndicationRequestMessage to include a subscriptionInstance parameter into the message so subscription data can be retrieved.
8. Based on DMTF specification (CR InterOp214) for the format, extend the indication handler interface handleIndication (in the pegasus/src/Pegasus/Handler/CIMHandler.h) to include a subscriptionInstance parameter in order to retrieve subscription data. Note: This interface is not exposed externally.

The new interface is as follows:
     virtual void handleIndication(
        const OperationContext& context,
        const String& nameSpace,
        CIMInstance& indicationInstance,
        CIMInstance& indicationHandlerInstance,
        CIMInstance& indicationSubscriptionInstance,
        ContentLanguages& contentLanguages) = 0;

9. Modify Indication Handler Service, CIMxmlIndicationHandler, and snmpIndicationHandler to use updated handleIndication interface.
10. Create and implement a new class SystemLogListenerDestination in a new directory SystemLogListenerDestination (under the directory pegasus/src/Pegasus/Handler).
The SystemLogListenerDestination will format the received indication based on DMTF specifications for the format. A platform-independent interface is created to give platform maintainer a flexibility to write the formatted indication to a system log file. This interface is not exposed externally.

 The interface is as follows: 
    void _writeToSystemLog(
        const String & identifier,
        Uint32 severity,
        const String & formattedText)

Note: severity parameter in the _writeToSystemLog function is Pegasus logger severity. If PEGASUS_USE_SYSLOG is defined, the function _writeToSystemLog will write the formatted indications into the system log file by calling System::syslog() (System::syslog() is already mapping Pegasus severity to syslog error severity today). Otherwise, the formatted indications will be written into PegasusStandard.log file which is defined in the Logger.cpp. Platform maintainers may add support for other system log mechanisms into this function.

Configurability

Test Plan

Dependency

Schedule

Action	Planned	Actual	Comment
PEP Submitted	10/27/04	10/27/04
PEP Reviewed	11/12/04	11/02/04
PEP Approved	11/19/04	12/03/04
Code Committed	Pegasus 2.5 FC	2/25/05

Copyright (c) 2004 EMC Corporation; Hewlett-Packard Development Company, L.P.; IBM Corp.; The Open Group; VERITAS Software Corporation

Permission is hereby granted, free of charge, to any person obtaining a copy  of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

THE ABOVE COPYRIGHT NOTICE AND THIS PERMISSION NOTICE SHALL BE INCLUDED IN ALL COPIES OR SUBSTANTIAL PORTIONS OF THE SOFTWARE. THE SOFTWARE IS PROVIDED  "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.