Logging services

HCL Commerce provides facilities for logging. For existing customers, ECTrace and ECMessage are still supported. For new implementations, use the WebSphere Application Server recommendation for logging and tracing.

The purpose of logging messages in the Transaction server is to record unexpected errors or abnormal conditions within the HCL Commerce application. (For information about recording commands and tasks that are executed during an HCL Commerce operation, refer to business auditing.) Message logs and traces are important diagnostic tools that aid the Site Administrator in determining the source of problems. Tracing is a problem-determination mechanism. Tracing assists developers in debugging the code during the development stage and assists the technical support team in solving customer problems. The Log and Trace Analyzer tool for Eclipse in the WebSphere Application Server Toolkit can be used. The Log and Trace Analyzer tool for Eclipse is installable from the WebSphere Application Server Toolkit launchpad console. It provides interactive viewing and analysis capability that is helpful in identifying problems.

Review the following HCL Commerce Log APIs:

ECTrace
Traces the data flow. The trace entries are captured in a file for debugging purposes. Tracing is used for problem determination. Tracing assists developers in debugging code during the development stage and assists the technical support team in solving customer problems.

Tracing data is persisted for future reference in a trace file. A data structure consists of context information, such as a class name, a method name, and a text message. Multiple data structures describe the data flow within a software application. By analyzing the data structure sequence, a developer can understand the path that was executed, which can help determine the cause of malfunctions.

ECMessage
Logs diagnostic messages. Messages are locale-sensitive, and are stored in log files in the file system. If error notification is enabled, technical support receives alert notifications. Diagnostic logs are used for problem determination. By default, the log file name is SystemOut.log.

Diagnostic logs are used for problem determination. ECMessageLog logs diagnostic messages, and ECMessages are localized. ECMessages are divided into the following categories:

System messages
System messages display in the logs and are for recording problems or potential problems (that is, warnings). System messages provide diagnostic information for Site Administrators. These messages might follow a system malfunction, or indicate some other significant event.

System messages are assigned a product-specific message ID. Site Administrators can use the message ID to look up more details that are associated with that message; customers can report the message to support personnel for troubleshooting.

Messages from previous versions of HCL Commerce use the CMN nnnns format, and messages new for HCL Commerce 5.6 use the format CWX ccnnnns. In both cases, be familiar with the following format:

cc
The HCL Commerce component that is reporting the system message. For example, CC indicates a message about the catalog component, as in CWXCC1234E.
nnnn
The key number that is used to identify what is affected. For example, 1234, as in CWXCC1234E.
s
The severity of the message. A severity of E indicates an error message, I indicates informational messages, and W indicates warnings.
User messages
Are frequently shown on the browser, and are for the benefit of a customer that is visiting the site. User messages provide details about the problem. For example, messages can indicate whether a parameter specified is invalid, which indicates to the customer what value to fix when they resubmit the request.
Consists of multiple java packages that form a logging toolkit that provides message logging and diagnostic trace primitives. These primitives are not tied to any particular product or platform. JRas is composed of several components:
Loggers
A logger is the primary object with which the user code interacts. There are two types of loggers:
  • message loggers
    • Create only message records.
  • trace loggers
    • Create trace records.
A logger contains one or more Handlers to which it forwards events for further processing.
Handlers
A handler receives events from a logger, and provides an abstraction over an output device or event consumer. An example is a file handler, which knows how to write an event to a file.
Formatters
Handlers are configured with Formatters, which know how to format events of certain types.
Event Types
Messages and traces have their own pre-defined event types.
Event Classes
The JRas logging toolkit defines both message and trace event classes.
WebSphere JRas extensions
In order to integrate into the WebSphere Application Server run time or for usage in a J2EE environment, WebSphere provides a set of extension classes. Logging from HCL Commerce uses the WebSphere Application Server logging facility, and these extension classes provide a better correlation of messages and traces that are generated from different WebSphere products. This collection of extension classes are referred to as WebSphere JRas extensions. WebSphere JRas extensions provide appropriate logger implementation classes. Instances of the message and trace logger classes are obtained directly and exclusively from the WebSphere Manager class, which is in the com.ibm.websphere.ras package. Other components such as Payments and the JCA messaging framework also use WebSphere JRas extensions.

HCL Commerce provides a wrapper for ECMessage and ECTrace that calls the WebSphere JRas extension APIs, however it is recommended that Site Administrators call the JRas APIs directly.

Note: For more information about the JRas logging toolkit, see the Understanding the JRas facility topic.

Logging file location

You can find the default output files in the following directory:
  • LinuxAIXFor IBM i OS operating systemWC_profiledir/logs/server1
  • WindowsWC_profiledir\logs\server1

In the directory, you can find the following default output files:

native_stderr.log
A process log that contains text that is written to the stderr stream.
native_stdout.log
A process log that contains text that is written to the stdout stream.
startServer.log
A log written when the server is started.
stopServer.log
A log written when the server is stopped.
SystemErr.log
Logs any system error while the server is running.
SystemOut.log
Logs the system output file while the server is running.
activity.log
Logs continuous activity. This log is in the WAS_installdir/logs directory.
trace.log
If trace is enabled, logs the components trace messages while the service is running.
Note:

When you work with IBM to debug request processing problems, there might be occasions where low-level tracing components must be enabled to capture details for how the request is processed. These low-level Application server trace components do not know the request intent or the potential data within. Therefore, when enabled, it is possible that these tracing components might potentially include sensitive information, in plain text, in the trace file.

It is recommended that you do not enable these types of tracing components on a production system and attempt to simulate the problem on a quality assurance environment to capture the appropriate information. However, if the tracing components must be enabled on a production system, handle the trace files with caution. Before you send the trace, remove sensitive data that might be in the trace before you allow a third party to use the trace for diagnosis. Further, when the trace is no longer required, remove the files with a military-grade data wiping process. When the problem is found and the tracing component is no longer required, immediately disable the low-level tracing components.

Logging levels

There are three logging levels, or severities, in the HCL Commerce logging system:

  • error
  • warning
  • informational
Note: Although the WebSphere Application Server logging facility also uses the status and debug logging levels, HCL Commerce uses and maps to the error, warning, and informational logging levels.
Error messages
Always logged by default. Error messages expose an error condition that can lead to system malfunction. An error message can be sent as an email, IBM MQ message, or by another form of notification to a Site Administrator registered with messaging.
Warning messages
Reveal a potential problem.
Information messages
Follow events that occur within the HCL Commerce system. Information messages are related to events that trigger changes in the system state. For example, an information message is persisted when an order is submitted.

Since HCL Commerce uses the WebSphere Application Server logging facility, refer to the following table to learn about how the HCL Commerce logging levels are mapped to the WebSphere Application Server as follows:

Logging levels in HCL Commerce Logging levels in WebSphere Application Server
DEBUG TYPE_INFORMATION/TYPE_INFO
ERROR/ERR TYPE_ERROR/TYPE_ERR
INFORMATION/INFO TYPE_INFORMATION/TYPE_INFO
STATUS TYPE_INFORMATION/TYPE_INFO
WARNING/WARN TYPE_WARNING/TYPE_WARN

The WebSphere Application Server user interface is used to control the enablement of the logging level or severity type. Site Administrators can specify which logging severities to record in the WebSphere Application Server Administration Console.

Viewing log files

You can view log files in various ways. Typically, depending on the type of log file, there are suggested methods to view as follows:

  • Use the Rational Application Developer (RAD) or AST activity log viewer to view activity log files and WebSphere Application Server trace files.
  • Use the Log and Trace Analyzer tool for Eclipse to view activity log files andWebSphere Application Server trace files.
  • Use any text editor to view WebSphere Application Server trace files, system out log files, or system error log files.

The following diagram illustrates these suggested view methods:

Diagram to illustrate different view methods for reading log files.