Common Base Event logging support for i5/OS WebFacing applications

Purpose

i5/OS WebFacing applications now contain a built-in logging and tracing mechanism to diagnose runtime application problems.

Different logging mechanisms are used for runtime message logging depending on the level of the server your application runs on, as summarized in the following table.

Deployment environment Environment Logging support
WebSphere® Application Server V6.0 or later JRE 1.4.2 or above; WAS has built-in CBE logging support Common Base Event logging
WebSphere Application Server V5.1 JRE 1.4.2 JSR-047 logging

Running in WebSphere Application Server V6.0 or later

When you run a i5/OS® WebFacing application on an application server, logging information is sent by default to the console of the application server. For more information about logging and tracing in WebSphere Application Server V6.0, see http://publib.boulder.ibm.com/infocenter/wsdoc400/index.jsp?topic=/com.ibm.websphere.iseries.doc/info/ae/ae/ttrb_addtrace.html

You can configure the logging level of the WebFacing application logger (com.ibm.etools.iseries.webfacing.context_root_name) using the administrative console in WebSphere Application Server V6.0. For information about configuring the logger, see http://publib.boulder.ibm.com/infocenter/wsdoc400/index.jsp?topic=/com.ibm.websphere.iseries.doc/info/ae/ae/ttrb_configjavalog.html

You can also configure the logger details level as well as other settings for the WebFacing application logger by using the webfacinglogging.properties configuration file.

By default, the log message in WebSphere Application Server V6.0 is written to the console of the application server, and the log record is written to the WebSphere Application Server V6.0 activity.log file. If you turn on tracing through the application server administrative console, the trace information is written to the trace.log file of the application server instance. When tracing is enabled, all log messages are logged to trace.log in simple text format, and all log records with log level CONFIG and above, are also logged to activity.log in Common Base Event format. For information about turning on tracing in WebSphere Application Server V6.0, see http://publib.boulder.ibm.com/infocenter/wsdoc400/index.jsp?topic=/com.ibm.websphere.iseries.doc/info/ae/ae/ttrb_entrss.html

You can also configure your settings for WebFacing applications to separate the runtime logging and tracing information into different files in the system where your application server is running. Log records, where the log level is above or equal to CONFIG, are written to a log file and a trace file, if tracing is enabled for this logger. Trace records, where the log level is below CONFIG, are written to a trace file. See the Configuration settings for a WebFacing application section below for the properties that enable this feature.

The log and trace files are organized by each HTTP session. The name of the log file will be sessionid.log, where sessionid is the session id of the browser accessing the WebFacing application. Similarly, the trace file name is sessionid.trace. The log file related to a WebFacing application is written into a directory with the same name as the context root name of your Web project containing the WebFacing application. See the logFileLocation property in the Configuration settings for a WebFacing application section below for information about configuring the location of your WebFacing log and trace files.

The log records written to a log file will be Common Base Event log records in XML format, and you can view and analyze them using the Log Trace Analyzer included in Rational® Developer for i5/OS. Complete the following steps to import a Common Base Event log file into your Log Trace Analyzer:
  1. In the Profiling and Logging Perspective, in the Log Navigator view, click File > Import to open the Import Wizard
  2. In the Import dialog, select Log File > Next
  3. On the Import Log File page, click Add
  4. On the Add Log File page, select the log type Common Base Event XML Log. Click the Host name tab and type or select the remote host name
  5. Click Test connection to ensure that IBM® Agent Controller for i5/OS is active. You need IBM Agent Controller running in the remote host to import the log file into your local host. You can use Remote System Explorer or FTP to copy your log file into your local driver
  6. Click the Details tab. If your log file is in the localhost, you could use the Browse button to locate the log file. Otherwise, you need to input the full path of your log file.
See the following topics for information about using the Log Trace Analyzer and Agent Controller for i5/OS:

If you do not have the Log Trace Analyzer available, or you just want to look at the message text of your log record, you can configure your settings to format your log record to be written as a simple string. See the useXMLFormatForCBELogging property in the Configuration settings for a WebFacing application section below for information about controlling the format of your Common Base Event log record.

Running in WebSphere Application Server V5.1.x (on top of JRE 1.4)

If your i5/OS WebFacing application runs in WebSphere Application Server V5.1.x, which also runs on top of JRE 1.4, the Java™ Logging mechanism is used for runtime message logging. See the Java documentation for thejava.util.logging class for more information: http://java.sun.com/j2se/1.4.2/docs/api/java/util/logging/package-summary.html

You can configure the logger details level as well as other settings of the WebFacing application logger by modifying the webfacinglogging.properties configuration file. See the level property in the Configuration settings for a WebFacing application section below for information about setting the logging level.

Note: You cannot configure the logger details level for your WebFacing application logger through the WebSphere Application Server V5.1.x administration console.
By default, the log and trace messages for the WebFacing application is written to the console of the application server. You can also configure the logging in the WebFacing application to write runtime logging and tracing information into different files in the system where your application server runs. The configuration of this support, and naming convention of the log and trace files, are the same as described above for WebSphere Application Server V6.0. However, the log record written to the log file is in XML format described by the Java logging document http://java.sun.com/j2se/1.4.2/docs/api/java/util/logging/XMLFormatter.html
Note: The Log Trace Analyzer does not support viewing log records written in this format.
If you do not want the log record to be in XML format, you can change the configuration to format the log record as a simple string. See the useXMLFormatForJSR47Logging property in the Configuration settings for a WebFacing application section below for information about controlling the format of your Java log record. The trace record written to trace file will be in simple string format, which is the same as in WebSphere Application Server V6.0.

Configuration settings for a WebFacing application

You can configure the logging and tracing settings of a WebFacing application through the webfacinglogging.properties file, which is located in the WebContent/WEB-INF/classes for a WebFacing Web project. Here you see the settings inside this file.

# Control the level of runtime logging
# The levels in descending order are:
#   SEVERE (highest value)
#   WARNING
#   INFO
#   CONFIG
#   FINE
#   FINER
#   FINEST (lowest value)
# In addition, there is a level OFF that can be used to turn off logging,
# and a level ALL that can be used to enable logging/tracing of all messages.
# See the Java document for the java.util.logging class for more information.
# The levels above or equal to CONFIG are considered logging.
# The levels below CONFIG are considered tracing.
# Default is SEVERE.
com.ibm.etools.iseries.webfacing.level=SEVERE

# Control if the logging level set in this file will override
# the static configuration settings of log detail levels in WAS6.0
# This setting is only valid when running on WAS6.0 or later.
# Please refer to the following page for setting log detail levels
# in WAS6.0 Administrative Console:
# http://publib.boulder.ibm.com/infocenter/wsdoc400/index.jsp?topic
# =/com.ibm.websphere.iseries.doc/info/ae/ae/ttrb_configjavalog.html
# Valid values are:
#     true  - default
#     false
com.ibm.etools.iseries.webfacing.overrideAdminLevelSetting=true

# Control which directory the log and trace files will be written to.
# A subdirectory with the same name as the web-app
# will be created to store all the log and trace files of a specific web application.
# This value will be used when property "logToFile" is set to true.
# "%WASTraceDir" - trace directory of the WAS server instance.
#                  By default, it is the SERVER_LOG_ROOT variable defined.
#                  in the WAS server. This value will be used as default value
#                  if the web application is running in a WAS environment.
#                  If this value is not available, "%h/iserieslogs" will be used as
#                  default.
# "%h" - the value of the "user.home" system property
#        "%h/iserieslogs" will be used as default value
# "%t" - the value of the system temporary directory
# "."  - the value of web-app/WEB-INFO directory
# "/" the local pathname separator
com.ibm.etools.iseries.webfacing.logFileLocation=%WASTraceDir

# Control if log and trace information will be written to files.
# Valid values are:
#     true
#     false  - default -- In this case the information is written to the console.
com.ibm.etools.iseries.webfacing.logToFile=false

# Control if parent's output handler of this logger will also be used.
# This setting is only valid when running on WAS6.0 or later.
# If this property is set to false, the log or tracing information will
# not be written to the WAS 6.0 activity.log or trace.log
# Valid values are:
#     true  - default
#     false
com.ibm.etools.iseries.webfacing.useParentHandler=true

# Control the format of the Java log records written to a file.
# This property is valid for WAS 5.1.x running on JDK1.4.2, 
# where java.util.logging classes are available.
# If this property is set to true, the log records written to the
# log file will be in XML format.
# See the Java document for the java.util.logging.XMLFormatter class
# for more information.
# If this property is set to false, the log records written to the
# log file will be in simple string format.
# Valid values are:
#     true  - default
#     false
# it is only valid in the environment running on top of JDK1.4,
# but don't have build in CommonBaseEvent support
com.ibm.etools.iseries.webfacing.useXMLFormatForJSR47Logging=true

# Control the format in which Common Base Event log records are written to a file.
# This property is valid for WAS 6.0, which has built-in 
# Common Base Event Java logging support.
# If this property is set to true, the log records written to the
# log file will be in Common Base Event
# XML format.  You can us the Log and Trace Analyzer shipped in WDSC to view them.
# See the help for Log and Trace Analyzer in WDSC for more information.
# If this property is set to false, the log records written to the log
# file will be in simple string format.
# Valid values are:
#     true  - default
#     false
com.ibm.etools.iseries.webfacing.useXMLFormatForCBELogging=true

#Control how many log files will be created for each web application
# before the oldest log file is deleted.
com.ibm.etools.iseries.maxlog=3
Note: If the application server is running on an i5/OS, you may be required to assign permission to this directory so that the log files can be created in the IFS. For IBM WebSphere Application Server, you need to give write authority to the QEJBSVR user profile. Specifically the QEJBSVR profile should have read, write, and execute authority to the trace directory in the table above.

Feedback