Logging services

WebSphere 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 WebSphere Commerce application. (For information about recording commands and tasks that are executed during a WebSphere 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 WebSphere 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 associated with that message; customers can report the message to support personnel for troubleshooting.

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

cc

The WebSphere 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 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 WebSphere 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.

WebSphere Commerce provides a wrapper for ECMessage and ECTrace that calls the WebSphere JRas extension APIs, however IBM recommends 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

We can find the default output files in the following directory:

• (AIX) (Linux) (IBM i) WC_profiledir/logs/server1

• (Windows) WC_profiledir\logs\server1

In the directory, we 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.

IBM recommends 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 WebSphere Commerce logging system:

• error

• warning

• informational

Note: Although the WebSphere Application Server logging facility also uses the status and debug logging levels, WebSphere 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 WebSphere 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 WebSphere Commerce uses the WebSphere Application Server logging facility, refer to the following table to learn about how the WebSphere Commerce logging levels are mapped to the WebSphere Application Server as follows:

Logging levels in WebSphere 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

We 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:

See

• Configure logging for runtime environments
  
• Configure logging for WebSphere Commerce Developer environments
  
• Application server log files
  
• Trace components
  
• Performance logger
  
• Log REST responses
  
• Enable Management Center client-side logging and tracing