Enhanced WEM Logging


Enhanced WEM Logging
 
 
 
The WEM application is equipped with enhanced logging functionality that provides the following:
 
This chapter includes the following topics:
 
Supported Components
 
Enhanced logging functionality is supported for the following WEM components:
WEM Server: Logging for the server component of the WEM is facilitated by the emslogger.xml file located in the /<ems_dir>/server/etc directory by default. This component consists of a number of categories (called loggers) as described in the following table.
EMS Server Component Logger Categories
Bulk Statistics Parser: Logging for the Bulk Statistic Parser component of the WEM is facilitated by the bsparserlogger.xml file located in the /<ems_dir>/server/etc directory by default. This component is responsible for analyzing information collected by the Bulk Statistic Server.
Bulk Statistics Server: Logging for the Bulk Statistic Server component of the WEM is facilitated by the bsserverlogger.xml file located in the /<ems_dir>/server/etc directory by default. This component is responsible for collecting bulk statistic information from the system.
Script Server: Logging for the Script Server component of the WEM is facilitated by the scriptlogger.xml file located in the /<ems_dir>/server/etc directory by default. This component supports the ability to execute specific scripts upon the receipt of SNMP alarms.
NorthBound Server: Logging for the NorthBound Server component of the WEM is facilitated by the nbserverlogger.xml file located in the /<ems_dir>/server/etc directory by default. This component is responsible for collecting NB server information from the system.
Important: The NorthBound (NB) Server process is customer-specific and is not operational without the appropriate license. Please contact your local sales representative for additional information.
The XML configuration file for each of the above components consists of the following configurable elements:
Appender settings: Control log file parameters such as naming, output location, format, and sizing specifications.
Logger settings: Control logging parameters for the specified category such as whether or not to use appender settings and the log level. As described previously, the WEM Server component consists of multiple loggers. There is a single logger for the other components.
Root element: Contains references to other appenders that should be added to loggers contained in the XML configuration file. In addition, this element contains a parameter that dictates how often the system is to scan and incorporate changes made to the logger configuration. (Additional information on configuring the scan frequency is provided in the Configuring Support for Dynamic Logging Updates section of this chapter.)
 
Configuring Appender Settings
Appender settings control log file parameters such as naming, output location, format, and sizing specifications.
 
Appenders are defined by their class. Each class has related parameters that are configurable. The following appender classes are supported:
Detailed information for each of the above classes is provided in the sections that follow.
By default, each logging configuration file has a single Rolling File Appender configured called Main. Each logger within the file is configured to use this appender by default. (It is referenced in the root element in the configuration file.) Additional appenders can be added to the configuration file using a text editor (such as Vi Editor) if desired.
 
Asynchronous Appender Settings
Asynchronous appenders are used to log events asynchronously. It uses a bounded buffer to store logging events. A separate thread is used to serve the events in its bounded buffer.
 
Multiple appenders can be attached to an Asynchronous appender. In this scenario, this appender collects the events sent to it and then, dispatches them to all the appenders that are attached to it.
Asynchronous appenders have the following format:
<appender name="appender_name" class="AsyncAppender">
  <param name="BufferSize" value="size"/>
  <appender-ref ref="attached_appender"/>
</appender>
The variables identified in the format above are described in the following table.
Asynchronous Appender Variable Descriptions
 
Console Appender Settings
Console appenders display log events to the console display.
 
Console appenders have the following format:
<appender name="appender_name" class="ConsoleAppender">
  <param name="Target" value="output"/>
  <layout class="layout_class">
<param name="ConversionPattern" value="conv_pattern"/>
  </layout>
</appender>
The variables identified in the format above are described in the following table.
Console Appender Variable Descriptions
Specifies the format of the log file output. Refer to the Log File Output Formats section of this chapter for information on supported output formats.
Specifies the conversion pattern used to format event related information. Refer to the Pattern Layout Supported Conversion Characters table for a list of supported conversion characters.
 
File Appender Settings
This appender adds log events to a file.
 
File appenders have the following format:
<appender name="appender_name" class="FileAppender">
  <param name="File" value="file_name"/>
  <param name="Append" value="append_option"/>
  <layout class="layout_class"> <param name="ConversionPattern" value="conv_pattern"/>
  </layout>
</appender>
The variables identified in the format above are described in the following table.
File Appender Variable Descriptions
true : Append the information; this is the default setting.
false : Do not append the information.
Specifies the format of the log file output. Refer to Log File Output Formats section of this chapter for information on supported output formats.
Specifies the conversion pattern used to format event related information. Refer to the Pattern Layout Supported Conversion Characters table for a list of supported conversion characters.
 
Rolling File Appender Settings
This appender type extends the File Appender capability to backup the log files when they reach a certain size. This is the default appender type.
 
Rolling File appenders have the following format:
<appender name="appender_name" class="RollingFileAppender">
  <param name="File" value="file_name"/>
  <param name="Append" value="append_option"/>
  <param name="MaxFileSize" value="size"/>
  <param name="MaxBackupIndex" value="max_backups"/>
  <layout class="layout_class">
  <param name="ConversionPattern" value="conv_pattern"/>
  </layout>
</appender>
The variables identified in the format above are described in the following table.
Rolling File Appender Variable Descriptions
true : Append the information; this is the default setting.
false : Do not append the information.
Specifies the format of the log file output. Refer to the Log File Output Formats section of this chapter for information on supported output formats.
Specifies the conversion pattern used to format event related information. Refer to the Pattern Layout Supported Conversion Characters table for a list of supported conversion characters.
 
Daily Rolling File Appender Settings
This appender extends the File Appender capability so that the underlying file is rolled over at a user chosen frequency. The rolling schedule is specified by the DatePattern option. A formatted version of the date pattern is used as the suffix for the rolled file name.
 
Daily Rolling File appenders have the following format:
<appender name="appender_name" class="DailyRollingFileAppender">
  <param name="File" value="file_name"/>
  <param name="Append" value="append_option"/>
  <param name="DatePattern" value="date_format"/>
  <layout class="layout_class">      <param name="ConversionPattern" value="conv_pattern"/>
  </layout>
</appender>
The variables identified in the format above are described in the following table.
Daily Rolling File Appender Variable Descriptions
true : Append the information; this is the default setting.
false : Do not append the information.
Specifies the format of the log file output. Refer to the Log File Output Formats section of this chapter for information on supported output formats.
Specifies the conversion pattern used to format event related information. Refer to the Pattern Layout Supported Conversion Characters table for a list of supported conversion characters.
For example, if the File parameter is set to abc.log and the DatePattern parameter is set to .%Y-%m-%d, on 2001-02-16 at midnight, the logging file abc.log is copied to abc.log.2001-02-16 and logging for 2001-02-17 will continue in abc.log until it rolls over the next day.
 
Socket Appender Settings
This appender has the following properties:
 
Socket appenders have the following format:
<appender name="appender_name" class="SocketAppender">
  <param name="RemoteHost" value="host"/>
  <param name="Port" value="port_no"/>
</appender>
The variables identified in the format above are described in the following table.
Socket Appender Variable Descriptions
 
Telnet Appender Settings
This appender specializes in writing to a read-only socket. The output is provided in a telnet-friendly way so that a log can be monitored over TCP/IP. Clients using telnet connect to the socket and receive log data. This is handy for remote monitoring, especially when monitoring a servlet.
 
Telnet appenders have the following format:
<appender name="appender_name" class="TelnetAppender">
  <param name="RemoteHost" value="host"/>
  <param name="Port" value="port_no"/>
</appender>
The variables identified in the format above are described in the following table.
Telnet Appender Variable Descriptions
 
SMTP Appender Settings
This appender supports the sending of an e-mail when a specific logging event occurs, typically on errors or fatal errors.
 
The number of logging events delivered in this e-mail depend on the value of BufferSize option. The SMTP Appender keeps only the last BufferSize logging events in its cyclic buffer. This keeps memory requirements at a reasonable level while still delivering useful application context.
SMTP appenders have the following format:
<appender name="appender_name" class="SMTPAppender">
  <param name="BufferSize" value="size" />
  <param name="SMTPHost" value="smtp_host"/>
  <param name="From" value="sender"/>
  <param name="To" value="recipient"/>
  <param name="Subject" value="subject"/>
  <layout class="layout_class">
     <param name="ConversionPattern" value="conv_pattern"/>
  </layout>
</appender>
The variables identified in the format above are described in the following table.
SMTP Appender Variable Descriptions
Specifies the format of the log file output. Refer to the Log File Output Formats section of this chapter for information on supported output formats.
Specifies the conversion pattern used to format event related information. Refer to the Pattern Layout Supported Conversion Characters table for a list of supported conversion characters.
 
Log File Output Formats
The WEM enhanced logging function provides the ability to specify the log file output format. Layout configuration is performed using the layout class parameter. The following formats are supported:
Detailed information for each of the above classes is provided in the sections that follow.
 
HTML Layout
This layout displays events in HTML tables. For each event, the following fields are provided:
Time: Event time
Thread: Event thread
Level: Event severity Level
Category (Module): The enhanced logging function category that generated the event
Message: Event description
Use the following parameter configuration to use the HTML Layout:
<layout class="HTMLLayout"/>
An example of this layout’s output is shown below.
HTML Layout Output Example
 
TTCC Layout
This layout consists of Time, Thread, Category, and nested diagnostic Context information. Each of these items can be individually enabled or disabled. The time format depends on the DatePattern used.
Caution: Do not use the same TTCC Layout instance from within different appenders. The TTCC Layout may not handle event threads properly when used in this way.
Use the following parameter configuration to use the TTCC Layout:
<layout class="TTCCLayout"/>
  <param name="DatePattern" value="date_format"/>
</layout>
The variables identified in the format above are described in the following table.
TTCC Layout Variable Descriptions
An example of this layout’s output is shown below.
176 [main] INFO examples.Sort - Populating an array of 2 elements in reverse order.225 [main] INFO examples.SortAlgo - Entered the sort method.
 
Simple Layout
This layout displays the event severity level and the event description.
Use the following parameter configuration to use the Simple Layout:
<layout class="SimpleLayout"/>
An example of this layout’s output is shown below.
INFO - Populating an array of 2 elements in reverse order.
INFO - Entered the sort method.
 
Pattern Layout
This layout allows the specification of an output format through the configuration of a pattern string. It formats the log event and returns it as a string.
Use the following parameter configurations to use the Pattern Layout:
<layout class="org.apache.log4j.PatternLayout"/>
  <param name="ConversionPattern" value="pattern"/>
</layout>
pattern specifies the conversion characters used to format the output. The following table provides information on supported conversion characters.
Pattern Layout Supported Conversion Characters
ABSOLUTE : AbsoluteTimeDateFormat
DATE : DateTimeDateFormat
ISO8601 : ISO8601DateFormat
An example of this layout’s output when the following conversion pattern was specified is shown below:
%d{%d:%b:%Y %H:%M:%S:%Q}%6p %3t [%-16x] %8m%n
25:Aug:2005 13:14:27:494 INFO 1 [main DBData::initialize] DB info initialized
 
Configuring Logger Settings
Loggers are configured for each of the WEM components described previously in this document. Additionally, for the WEM Server component which consists of multiple categories, loggers are configured for each of the categories.
 
Loggers are configured using the following format:
<logger name="name" additivity="add_option">
  <level value="severity"/>
  <appender-ref ref="appender_name"/>
</logger>
Logger Variable Descriptions
true : Use appender defined within root (default)
false : Do not use appender defined within root
 
Configuring Log Message Filters
Log messages can be filtered based on the following criteria:
 
Detailed information for each of the above classes is provided in the sections that follow.
 
Level Match Filters
This filter displays or rejects logs for events that match the specified severity level.
 
Level Match filters are configured using the following format:
<filter class="LevelMatchFilter">
  <param name="LevelToMatch" value="severity" />
  <param name="AcceptOnMatch" value="accept_option"/>
</filter>
Level Match Filter Variable Descriptions
true : Logs matching the severity are accepted
false : Logs matching the severity are not accepted
 
Level Range Filters
This filter displays or rejects logs for events that fall within the specified minimum and maximum severity levels.
 
Level Range filters are configured using the following format:
<filter class="LevelRangeFilter">
  <param name="LevelMax" value="max_sev"/>
  <param name="LevelMin" value="min_sev"/>
  <param name="AcceptOnMatch" value="accept_option"/>
</filter>
Level Range Filter Variable Descriptions
true : Logs matching the criteria are accepted
false : Logs not matching the criteria are not accepted
 
String Match Filters
This filter displays or rejects logs for events based on whether or not any part of the event message matches the specified string.
 
String Match filters are configured using the following format:
<filter class="StringMatchFilter">
  <param name="StringToMatch" value="string" />
  <param name="AcceptOnMatch" value="accept_option"/>
</filter>
String Match Filter Variable Descriptions
true : Logs matching the criteria are accepted
false : Logs not matching the criteria are not accepted
 
Deny Filters
This filter denies all log messages regardless of severity.
 
Deny filters are configured using the following format:
<filter class="DenyAllFilter">
This can be used in conjunction with other log message filters that display logs based on the specified criteria. For example, the following configuration displays Warning-level logs and denies all others:
<filter class="LevelMatchFilter">
  <param name="LevelToMatch" value="WARN" />
  <param name="AcceptOnMatch" value="true"/>
</filter>
<filter class="DenyAllFilter">
 
Configuring Support for Dynamic Logging Updates
A key benefit of the WEM’s logging functionality is the ability to dynamically incorporate changes made to the logging configuration without restarting server processes.
The WEM periodically checks the XML configuration files for changes. If the changes are found, they are automatically applied.
Each XML configuration file contains a parameter called delay value that is used to specify the frequency with which the server looks for changes. This parameter is defined under the root element as shown below:
<root>
<priority value="WARN"/>
<!-- A delay used by the Watchdog thread to continuously read/check
the modified configuration applies to EMS Logger-->
<delay value="3000"/>
<appender-ref ref="Main"/>
</root>
The delay is measured in milliseconds. The default value is 3000 milliseconds.
 

Cisco Systems Inc.
Tel: 408-526-4000
Fax: 408-527-0883