Posted Jun 05 by Karen Rudnitski.

This article provides details and best practices in leveraging the logging framework with Process Platform (AppWorks Platform).

88 views. 0 comments.

Introduction

The logging framework records certain critical activities during run-time. It is based on Log4j and is used for debugging by Development and Support.

The information gathered from the log files is used to analyze the error state and fix support calls. AppWorks Platform supports different kinds of logs such as file, event service, and so on. This framework provides a web-based log viewer for viewing the messages. Apache's Chainsaw is an open source GUI-based tool that can also be used for viewing the log messages.

The following sections provides additional information on the following:

  • Logging Framework Process: Provides information on the overall workings of Logging Framework
  • Categories and Severity Levels: Defines the categories and associated severity levels used by the framework
  • Log Configuration: Describes how to provide log configuration details
  • Viewing Log Messages: Explains how to use the log viewer
  • Log Message Formats: Provides sample log message formats
  • Log Consumers: Provides information on various AppWorks log consumers and how they can be used

Logging framework process

The logging framework process is as follows:

  1. The administrator enables the log option for a particularCategory(com.eibus.transport) with a predefined severity (Warn), from the Explorer. The administrator can also select the log consumers (such as the File, Event Service, etc.) to which the log messages should be written.
  2. The source code instrumented with log messages is executed
  3. The framework logs instrumented messages to the selected consumers
  4. Log viewer tools can be used to view the messages logged


Severity Levels

The logging framework supports the following severity levels:

  • Debug - Log messages for developers and support personnel for debugging the application and detecting error causes, if any
  • Info - Log messages for the operators. For each application connector, try to log requests and responses with severity information
  • Warn - Log messages for errors caused by incorrect user inputs and errors that can be ignored Error - Log messages for exceptions and errors
  • Fatal - Log messages for critical errors, SOAP Processor being stopped, application crashing and so on

Categories and severity levels

AppWorks provides a classification of error messages that enables the developer to categorize the error messages and also assign an appropriate severity level to the same. Some log categories are provided to the user as default categories. The developers may register and use custom categories.

Default categories, including their package and logger details, include:

  • ACL - com.eibus.security.acl: this package is used for ACL evaluation
  • License - com.eibus.license: this package is used for License check
  • LDAP - com.eibus.directory: this package is used for LDAP Operations
  • SOAP Framework - com.eibus.transport.SOAPMessage (Class Name): this package is used for monitoring request / response
  • SOAP Message - com.eibus.soap: this package is used to track request / response transaction
  • Transport - com.eibus.transport: this package is used for monitoring request / response on bus
  • Tools - com.eibus.tools
  • Util - com.eibus.util: basic utitlies used during the running of SOAP processor

Severity levels can be assigned to the categories during SOAP Processor configuration. Each log category falls into a defined severity level. Severity levels allow filtering on each category. For example, the severity level for category com.eibus.security.acl could be 'Fatal', while that for com.eibus.license could be 'Warn'.

The following severity levels are defined for each category:

  • Debug - Log messages for developers and support personnel for debugging the application and detecting the cause for the error
  • Info - Log messages for the operators. For each application connector, try to log requests and responses with severity information
  • Warn - Log messages for errors caused by incorrect user inputs and errors that can be ignored
  • Error - Log messages for exceptions and errors
  • Fatal - Log messages for critical errors, SOAP processor being stopped, application crashing, etc

Note the following:

  • The framework supports severity levels higher than that configured. For example, if the severity level is configured to Warn, the logger logs all the severity levels that are higher than Warn.
  • If the severity of type Info is enabled for each application connector, the request and response is logged in that context.

Providing log configuration details

Once the log categories have been registered, they must be configured further for the severity levels. Also, you can specify the log consumers to which the log messages can be published.

Follow these steps to configure the severity levels and select log consumers for publishing the log message:

  1. Create a New SOAP Processor.

  2. In the Provide Log Configuration Details screen, the severity levels for the registered log categories are displayed. Choose from either of the following:
    • Enable Logging - This option allows you to enable the log categories and severities
    • Enable System Policy - This option disables all the log categories and severities, since the system-level configuration is applied. On enabling the System Policy option, the Log4jConfiguration.xml gets applied to a particular SOAP Processor. Do the following after selecting the option to Enable Logging:
      • Select Root Severity to turn the log option on for all the severity levels, including those that are not listed on the screen. The severity levels selected here would apply to all the categories. Note that enabling the lowest severity level automatically enables the remaining severity levels. Similarly, enabling or selecting the highest severity level enables only that severity. For example, selecting the Debug option enables all the options (Debug, Info, Warn, Error and Fatal). Next, disabling (clearing the checkbox for Fatal) Fatal disables the remaining severity levels. Selecting the severity Fatal does not enable other severity levels.
      • In the Category severity levels, select the severity for a specific category.
        • Selecting the Root Severity automatically turns the category-wise severity option on for all the categories
        • After enabling the Root Severity, you can clear the severity levels for any category. This would take precedence over the root-level severity.
        • Enabling the Root Severity and clearing the options for all category-wise severity levels shown in the screen, enables the severity levels for custom categories that are not listed. Note: If a 'severity' option is selected under both Root Severities as well as Category-wise Severities , the option selected under Category-wise Severities takes precedence

  3. Select the log consumer in the Logger Consumers pane

Enabling logging for gateway

Modify the logger configuration file as shown in the example, for enabling logging for gateway. If the log configuration details are provided during SOAP Processor configuration (as described in this section), then those would automatically get implemented. Logging at the Gateway level is also taken care of by the logger configuration file. Modifying the configuration details in the configuration file automatically takes care of the changes to the logger at the Gateway level. The default code looks like this:

Add the following lines:

This enables the logging for gateway and gateway applications. However, depending on the specific gateway application for which logging must be enabled, you must provide the precise package or category details for that gateway application. For example, to enable logging for WSDL gateway, the category name should becom.eibus.web.tools.wsdl.Note that the priority value can be set to debug , info , warn , error and fatal .The modified sample code look would like the one shown below

Customizing Logging

Custom categories can be added to the logger configuration:

  • Enabling logging for a package: The package name must be specified in the category name for which the logging is to be enabled.


  • Enabling logging for a class: The class name must be specified in the category name for which the logging is to be enabled.

Viewing log messages

There are two types of log viewers: AppWorks Log Viewer and Apache's Chain Saw.

AppWorks Platform Log Viewer

The event details are published to the file specified during log configuration. In the absence of log configuration, the log viewer reads the log messages from the file called
ProcessNamedDailyRollingFileAppender and is found in 'Installation Directory'\Logs . The naming convention for this depends on the process to which the log messages are written.

  1. For SOAP Processor, it is 'Organization Name'#'SOAP Node DN'#'SOAP Processor DN'.xml. For example, system#xml_store_service#xml_store_processor.xml (spaces are replaced with an underscore)
  2. For OS processes, it is the .xml (for example, MyOSProcess.xml is created for an OS Process named MyOSProcess). These log files can be viewed by selecting the View Log option in the context menu available for OS process.
  3. For monitor, it is Monitor.xml and by default, this is available in 'Cordys Installation Directory'\Logs directory.
  4. For gateway, it is Gateway.xml and this is available in 'Cordys Installation Directory'\Logs directory.
  5. If log messages to be published do not fall in any of the four categories mentioned above, they will be published to General.xml in 'Cordys Installation Directory'\Logs directory. Follow these steps to use the log viewer:
    1. Navigate to User > System > System Administrator > Admin Tools > SOAP Nodes > 'SOAP Node' > SOAP Processor
    2. Right-click 'SOAP Processor' and click View Log option. Message details can be viewed by selecting a message id. Rejected Messages- Displays messages in the Rejected queue. If a message is received through a transactional transport and its SOAP transaction is aborted, it will be logged in the reject queue. This is to support the fire and forget messaging pattern. As no reply is sent, the sender does not know if the action has failed. The reject queue messages that gave errors (because of optimistic locking) can be edited and retried using Retry Rejected Messages option.

Apache's Chainsaw

Apache's Chainsaw is an open source GUI-based tool used for viewing the log messages. Follow the steps described below to use Apache's Chain Saw log viewer:

  1. In the Provide Log Configuration Details screen, in the Logger Consumers frame, do the following:
    • Select the Publish to Remote Host option
    • Type the machine number in the Host Name text box
    • Type the port number as 4445. This is the default port for Chainsaw. For further information on changing the configuration, see the Chainsaw documentation.
  2. Run the following command from the command prompt:
    
    java org.apache.log4j.chainsaw.Main
     

Note that Apache Chainsaw cannot open files which have the hash (#) character in the filename. AppWorks log files have this character. Rename it to some other character to view the files in Chainsaw.

Log message format

The output log messages are in the following format:

Log message format for exceptions

For exceptions, the log message format is:

Log consumers

Log Consumer is any application which consumes log messages. AppWorks supports various kinds of log consumers, including those from Log4j, for consuming log messages. One or more consumers can be selected for publishing messages. The appropriate log consumer must be selected during the SOAP processor configuration. The following types of log consumers are used to publish log messages:

  • File - The File consumer writes log messages to the file and location specified during log configuration. If you do not specify any directory or folder path, the default path for this file is 'Installation Directory'\Logs\ If the file name is not specified, the log messages are published to the console. Notes:
    • For installation on Linux, after installing the patch, the user must have the 'read' and 'write' permissions on the Installation Directory to publish alerts and log statements to the file. If the file name contains folders, requisite permissions must be assigned to the folders.
    • In the Publish to File field of the Logger Consumers pane on the SOAP Processor - Parser Processor window, use a double-slash while specifying the folder path. For example, 'Drive':\\folder1 testlog.txt instead of 'Drive':\folder1\testlog.txt.
  • Rolling File - This is similar to writing to file except that when the log file crosses a specified file size, it is rolled over. The messages are then published to the file with a new name. If such a name already exists, it writes to a file with a new name. The maximum file size must be specified, during the SOAP Processor configuration.
  • Daily Rolling File - In this option, the messages are published to the file specified and files are rolled over based on user-defined time intervals, which can be monthly, weekly, daily and so on. You must specify the file name and the time at which the file should be rolled over. You can use the following formats: Roll over monthly - .yyyy-MM Roll over weekly - .yyyy-ww Roll over daily - .yyyy-MM-dd Roll over every hour - yyy-MM-dd-HH Roll over each minute - .yyyy-MM-dd-HH-mm
  • Socket - This option publishes the log messages to the socket specified. You must specify the machine name and port number while configuring the logger.
  • OS-based Event Log - Log messages are published to either the Windows Event Log for Windows operating system or Syslog with facility LOCAL7 for Linux operating system.

To log messages to Syslog Consumer:

  • Start the syslogd Daemon with remote logging as 'enabled'.
  • To stop the syslogd service, type 'service syslog stop' in the Linux prompt.
  • To start with remote logging as 'enabled', type 'syslogd -r -l host name -f /etc/syslog.conf' in the Linux prompt.

Note that he default consumer to which log messages are written is called ProcessNamedDailyRollingFileAppender . The file location for this consumer is 'Installation Directory'\Logs . The naming convention for this depends on the process to which the log messages are written. For each process, a log file is created.

  1. For SOAP Processor, it is 'Organization Name'#'SOAP Node DN'#'SOAP Processor DN'.xml. For example, system#xml_store_service#xml_store_processor.xml (spaces are replaced with an underscore)
  2. For OS process, it is the 'OS Process Name'.xml (for example, MyOSProcess.xml is created for an OS Process named MyOSProcess). These log files can be viewed by selecting the View Log option in the context menu available for OS process.
  3. For monitor, it is Monitor.xml and by default, this is available in 'Installation Directory'\Logs directory.
  4. For gateway, it is Gateway.xml and this is available in 'Installation Directory'\Logs directory.
  5. If log messages to be published do not fall in any of the four categories mentioned above, they will be published to General.xml in 'Installation Directory'\Logs directory.

AppWorks Logger supports all the Log4j Appenders. In such a case, one can directly use the log4J configuration for logging purposes, though with some customizations.

Additional information

As a best practice for developers, the following guidelines can aid a developer to use the logging framework better:

  • Once the logging instance is obtained, it should be made as a static object. The same instance must be used subsequently.


  • Before using the logger, check whether the selected category is enabled with specified severity. Note: The error and fatal severities are configured for logging by default. therefore, Application Developers should avoid checking for these severities using isErrorEnabled () and isFatalEnabled () methods.


  • If the logger is used to log any exception based messages, it must return the exception to the logger directly.


  • Diagnostic context or Transaction context information must be added to the log message using the following API CordysLogger._pushDiagnosticContext('key','value'); . This has to be removed once the transaction is complete, else it may lead to performance issues.

Table of Contents

Your comment

To leave a comment, please sign in.