This section describes how to use log and trace files for troubleshooting. The following topics are covered:
Configuring e-mail notification of log messages
"Configuring logging and tracing"
Logging is used to communicate system messages, component state changes, failures, and tracing information. Messages that are generated from InterChange Server, collaboration objects, and connectors are sent to the destination you specified when you installed IBM WebSphere ICS, by default, STDOUT (standard output). Messages that are generated from the connector agents are sent to STDOUT, but can be configured to be sent to a separate log file at the agent's location. The messaging system is always active and provides an accurate monitor of the system.
Bidirectional (BiDi) characters recorded in log and trace files might be encoded in different code pages which may cause display problems with standard Windows editors. ICS components are configured to dump the trace to STDOUT and if the data is redirected into a file, the encoding of trace messages might be corrupted. If ICS components are run from the DOS prompt, the change codepage command chcp is required for encoding the traces. For more information on configuring your system for BiDi languages see System Installation Guide for Windows.
You can configure the messaging system to send messages to a log file or an e-mail recipient in addition to the standard output. You can configure backup files (archives) for the log file, as well as determine their size. Tracing, which is disabled by default because of its drain upon system resources, can be configured when problems arise and detailed information is needed for troubleshooting.
Two tools provide a graphical user interface for configuring and viewing message logging and tracing. Use the:
In addition to using Log Viewer to view logs, you can open the log with a text editor or create your own tools to filter the log file.
For information about viewing logging and tracing messages using Log Viewer, see "Viewing log messages".
For background information about tracing, see "About tracing".
A collaboration object can generate messages to report runtime information, warnings, and errors. For example, a collaboration might log its decision points and the results of operations.
As InterChange Server executes collaboration objects, it writes their messages to its log. For information about configuring system logging, see "Configuring logging and tracing".
In addition, you can send a collaboration object's messages by e-mail to one or more recipients. You can specify a separate set of e-mail recipients for each collaboration object. For information on the rules for using e-mail notification, refer to "Configuring e-mail notification of log messages".
Connector messages are sent to the InterChange Server message destination. Depending on your operating system, messages appear in one of the following ways:
UNIX |
---|
A connector logs messages to STDOUT by default, then those messages are rerouted to connector_manager_<name_of_connector>.log. |
Windows |
---|
A connector logs messages to STDOUT by default, but can be configured to send to a local destination log file or the InterChange Server logging destination. |
For information about connector logging, see "Connector Agent logs".
To aid in troubleshooting, a temporary log file is created during the connector agent bootup that contains metadata obtained from the connector controller. The metadata consists of business object specifications, properties, and delta-supported properties. The file is named connectornametmp.log and is found in the ProductDir\Connectors directory.
All messages are formatted so they can easily be filtered. Logged messages for InterChange Server and connectors use the same format, which is described in Table 1. When business objects are configured for flow tracing messages, they use these fields and the additional fields, denoted by an asterisk in Table 1. A message delivered to InterChange Server has the following format, using some or all of the following parameters:
Time: System Name: Thread: MsgType MsgID:
SubSystem: FIID: BO: MsgText: BOD:
Variable | Description |
---|---|
Time | Timestamp: the date of logging in the format year/month/date time. |
System | The type of component (system identifier). It can be Server, Collaboration, Business Object, or ConnectorAgent. |
Thread | Thread name and thread ID |
Name | The name of the component, such as ClarifyConnector. |
MsgType | Indicates the severity of the message. See Table 2. |
MsgID | The message number. |
SubSystem* | The subsystem of the current system. It can be Event Management, Messaging, Repository, or Database Connectivity. |
FIID* | The flow initiator ID of the business object. |
BO* | Business object name. |
MsgText | The associated text for the message number. |
BOD* | Business object dump. The data contained in the business object. |
Following is an example of a message for the server: [Time: 2001/06/07 11:01:29.487] [System: Server] [SS: REPOSITORY] [Thread: VBJ ThreadPool Worker (#-1767149274)] [Type: Trace ] [Mesg: Released session REPOSITORY0]
Table 2 describes the types of IBM WebSphere ICS messages.
Type | Description |
---|---|
Info | Informational only. You do not need to take action. |
Warning | A default condition chosen by InterChange Server. |
Error | A serious problem that you should investigate. |
Fatal Error | An error that stops operation and should be reported. |
Trace | Tracing information for the trace level specified. |
Flow Trace | Flow tracing information for business objects. |
Internal Error | A serious internal problem that should be investigated. |
Internal Fatal Error | An internal error that stops operation. It should be reported. |
InterChange Server can log messages to the following destinations:
UNIX |
---|
STDOUT messages are redirected to the log file to $PRODUCTDIR/logs/ics_manager.log. |
Windows |
---|
STDOUT messages appear in the Command Prompt window in which InterChange Server starts. |
By default, trace messages are sent to the log file. In some cases, this file may become too large, so it is recommended that you specify a separate trace file. See "About tracing" for instructions on setting up a separate file for trace messages.
Configuring logging and tracing describes how to set the destination for logging.
To specify the recipient for e-mail notification, see Configuring e-mail notification of log messages.
Log/Trace file management describes how to keep log files from becoming too large.
The connector agent and connector controller have separate mechanisms for logging. This section describes connector agent logging. Connector controller messages are sent to the log that contains the InterChange Server messages.
A connector agent logs messages to a local destination and can also send its messages to InterChange Server for logging. To specify a log file name, edit the LogFileName property and insert the name of the log file you want to use. The default log file (located at ProductDir/logs/connector_manager_ConnectoName.log directory for UNIX and STDOUT for Windows), contains text for the error and informational messages raised from the connector. Name is the name of the application. For example, the default message file for the Oracle connector is OracleConnector.txt.
Table 3 describes the properties you can edit that determine where a
connector agent logs messages.
Table 3. Connector agent log message properties
Property Name | Description | Type of Value |
---|---|---|
LogAtInterchangeEnd | Specifies whether the connector agent sends messages to InterChange
Server in addition to logging them locally.
At InterChange Server, connector agent messages appear wherever server messages appear, according to the InterchangeSystem.cfg file. | Either true (sends messages to InterChange Server and enables e-mailing) or false (logs messages only locally). The default value is false. |
LogFileName | Specifies where to write connector agent messages on the local system. | A file path or standard output (STDOUT). The default value is STDOUT. |
For task instructions on configuring these properties, see Configuring the connector agent logging destination.
The InterChange Server system log for High Availability (HA) is configured to reside on the cluster shared drive (for example, Z:). This log is viewable only from the active system. For information about setting up the log to reside on the shared drive, see the System Installation Guide for UNIX or for Windows.
The HA system also uses the Application log to provide information about the cluster and its events and failures. Be sure to check the Microsoft MSCS online help for information about this tool.
When the InterChange system is started, a log file is created if one does not exist, or is appended to if it does. If the size of the log file is unlimited, it grows and its size depends on the amount of time since it was last managed and the volume of transactions passing through the system. If a log file grows too large, you may not be able to open it or an application may require additional system resources to write to the files.
IBM WebSphere ICS system log files can be configured to a specified size and then automatically archived once they reach that size. As an added precaution, you can specify a number of archive files to use as a system backup. Each time the log file reaches its maximum size, the file is renamed as a new archive file. The archive file's name is derived from the original log or trace file name, with the following inserted into the name:
_Arc_ number
For example, using 5 archive files, if the log file has the name InterchangeSystem.log, the first archive created is named InterchangeSystem_Arc_01.log. When the new log file fills up, InterchangeSystem_Arc_01.log is renamed as InterchangeSystem_Arc_02.log, and the log file is again saved to InterchangeSystem_Arc_01.log and so on in a circular fashion, until there are five archive files. If there are five archive files, when a new log file is created, existing archive files are renamed and their numbers incremented so the number of archives matches the number you configured, then the oldest file, whose archive number is 05, is deleted. Figure 1 shows the progression of files using this configuration.
Figure 1. Circular archival logging
See the configuration tasks Configuring logging and tracing for details.
If the system log file is configured for unlimited size, InterChange Server writes to the log until the disk that the log file is located on gradually fills, and if not administered to, finally produces an error message when the disk is full.
The data in these files should be deleted periodically:
In addition to the above log files, other log files exist that are specific to each application. Most files are created during runtime if they don't already exist. New information is appended to any existing file. Each component that supplies log information to the files must be taken down before proceeding with a backup.
Any file management procedure can be used, but the following periodic log file management is recommended:
Error and fatal messages that are logged to the InterChange Server log can also be sent to the IBM WebSphere ICS system administrator, or any other recipient, by e-mail. By default, InterChange Server is configured to send e-mail notifications using JavaMail, but you can configure the server to send e-mail notifications using the e-Mail connector. For instructions on configuring e-mail notification using the e-Mail connector, refer to Configuring e-mail notification at the system level.
The following components can be configured for sending error and fatal messages to an e-mail recipient:
You can configure e-mail notification at the system level (set in the InterchangeSystem.cfg file), at the collaboration object level (set as a collaboration object property), or at the connector level (set as a connector property). If you configure e-mail notification at the system level, the configuration applies to all of the collaboration objects or connectors in the system. If you configure e-mail notification at the collaboration object or connector level, the configuration applies only to that specific component and supersedes the system configuration.
Configuring e-mail notification at the system level allows you to configure the server to send e-mail notifications for the following subsystems:
To configure e-mail notification at the system level, do the following:
The instructions in this section are required only if you are using the e-Mail connector. Configure the EmailNotification business object to hold the e-mail address of the person who receives e-mail if the intended e-mail recipient is unreachable. As a fail-safe, this should probably be the mail administrator, not the ICS system administrator, to ensure the mail is delivered if the ICS system administrator is unreachable.
The instructions in this section are required only if you are using the e-Mail connector. To configure the e-Mail connector for sending e-mail:
This section describes how to configure e-mail notification for a specific collaboration object. Configuring e-mail notification for collaborations requires that you use the e-Mail connector. Be sure to select "Connector mail" when configuring e-mail notification at the system level, and be sure to follow the instructions in the following sections to configure the e-Mail connector: Configuring the e-Mail business object and Configuring the e-Mail connector.
To set an e-mail address to receive messages for a collaboration, do the following:
This section describes how to configure e-mail notification for a specific connector.
E-mail notification in the WebSphere ICS system supports Simple Mail Transport Protocol (SMTP) mail messages, therefore, the e-mail recipient value in the InterchangeSystem.cfg file and the collaboration e-mail addresses must be standard Internet addresses.
A valid e-mail address entry can be one or more fully qualified Internet addresses, separated by a comma. For example, a valid entry for two recipients is:
JohnDoe@company.com, FredSmith@company.com
You cannot use personal address aliases, such as an alias defined in a personal address book. However, a valid address can be an alias defined in a mail server, such as Eng@company.com. In this case, the mail server decodes the alias and sends e-mail to all members of the alias. For example, a decoded alias might be person1@some_company.com, person2@another_company.com, and so forth.
To troubleshoot a problem, you can turn on tracing. Trace messages help you monitor actions taken in components of the IBM WebSphere ICS system. Trace levels define the amount of detail written to the trace file. The higher the trace level, the more detail you receive. Tracing differs from logging in the following ways:
Tracing is off by default because it produces messages that are more detailed than you normally need. You can turn tracing on and off as necessary while InterChange Server is running.
Tracing services for InterChange Server are initially set in parameters of the configuration file for InterChange Server (by default, this file is called InterchangeSystem.cfg and resides in the product's top level directory. For details about these parameters, refer to "InterChange Server Configuration Parameters" in the System Installation Guide for UNIX or for Windows. Settings for these parameters can be updated in the Edit Configuration tool of System Manager, as described in Configuring tracing levels for InterChange Server, business objects, and collaborations.
You can trace the execution of a collaboration object. Tracing writes detailed messages about execution of the collaboration object to the log destination, which is specified in the InterchangeSystem.cfg file. Tracing collaborations is persistent. There are two trace level settings for collaborations, system level and collaboration level.
System level tracing returns runtime information for the collaboration. For example, if you want to trace the state changes of the collaboration, set the system trace level to 3.
You can set collaboration object tracing to one of the following
levels:
1 | Traces the receipt of business objects from connectors and the starting of the appropriate scenarios. |
2 | Prints messages for level 1. In addition, traces the start and completion of each scenario, reporting both forward execution and rollback. |
3 | Prints messages for levels 1 and 2. In addition, traces the execution of each scenario decision block or action. |
4 | Prints messages for levels 1 through 3. In addition, traces the sending and receipt of each business object by each scenario. |
5 | Prints messages for levels 1 through 4. In addition, traces the sending and receipt of each business object by each scenario, printing the value of each attribute in the business object. |
For configuration task instructions, see "Configuring tracing levels for InterChange Server, business objects, and collaborations".
A connector contains two components, the connector controller and the connector agent. The two components can be in different locations on the network and are traced differently. For more information about tracing connectors, see the Connector Development Guide for C++ and the Connector Development Guide for Java.
You can set connector agent and controller tracing to one of the following
levels:
1 | Traces initialization and the sending and receipt of business objects. |
2 | Prints messages for level 1. In addition, provides more details than Level 1 for the same types of events. |
3 | Prints messages for levels 1 and 2. In addition, traces the exchange of messages between the connector agent and the messaging driver. |
4 | Prints messages for levels 1 through 3. In addition, traces the passing of business objects between internal levels of the connector. |
5 | Prints messages for levels 1 through 4. In addition, traces the passing of administrative messages between internal levels of the connector. |
A new or changed tracing level takes effect immediately.
For configuration task instructions, see "Configuring connector tracing".
Tracing for IBM WebSphere ICS maps can be done through System Manager. Tracing maps is useful for debugging and keeping track of information as well as error messages created by the map. Tracing of IBM WebSphere ICS maps is turned off by default.
For more information about tracing maps, see the Map Development Guide. For configuration task instructions, see "Configuring map tracing".
Business object trace logging provides a way to trace the progression of business objects from one processing point to another, based on notification messages that are generated at each point. For example, with level 2 tracing, when a business object arrives at a collaboration for processing, a trace message is logged.
Table 4 describes the configurable levels associated with business
object tracing:
Table 4. Business object tracing levels
Level | Description |
---|---|
0 | No tracing. |
1 | Event status (such as Successful or Failed) and event identity information. |
2 | Minimal event tracing. Information about when a business object enters/exits systems, such as connectors, maps, relationships, and collaborations. Includes level 1 information. |
3 | Provides event tracing from level 2 and a business object dump at entry/exit of systems. System performance impact. |
4 | Detailed tracing. Provides tracing for system components such as connectors, maps, relationships, and collaborations, as well as mapping these traces to level 3 event tracing. System performance impact. |
For configuration task instructions, see Configuring tracing levels for InterChange Server, business objects, and collaborations.
Web gateway tracing is provided at two levels, minimal and maximum. This tracing allows you to view information pertaining to whether communication processing is being performed correctly on the gateway. The gateway trace level is set from the Gateway Configuration Tool. For instructions, see the System Implementation Guide.
Table 5 describes the configurable levels associated with gateway
tracing:
Table 5. Gateway tracing levels
Level | Description |
---|---|
0 | No tracing. |
1 | Minimal tracing (such as bind requests, socket opens, and so forth). |
5 | Maximum tracing (such as HTTP/HTTPS requests, including all headers). |
SNMP agent tracing provides trace information for checking the operation of the SNMP agent. The higher the level, the more verbose the output.
Table 6 describes the configurable levels associated with SNMP agent
tracing:
Table 6. SNMP agent tracing levels
Level | Description |
---|---|
0 | No tracing. |
1 | Message trace (displays Info, Warning, and Error type messages). |
2 | Low. Displays all incoming requests and outgoing messages. |
3 | Medium. Displays information such as Object ID, variable bindings and values. |
4 | High. Displays commands that access data on ICS and the values that are passed. |
5 | Method tracing. Errors resulting from ICS interface methods. |
This section describes how to set up message logging and tracing. These settings can be made by using The Edit Configuration option in System Manager and by manually editing the InterchangeSystem.cfg file. The following tasks are described:
"Opening the Edit Configuration tool"
"Configuring InterChange Server logging and tracing destinations"
Configuring other InterChange Server logging and tracing parameters
Configuring the connector agent logging destination
Configuring tracing levels for InterChange Server, business objects, and collaborations
Configuring the collaboration object trace level
InterChange Server must be running and in the Connected state to use the Edit Configuration tool. The Edit Configuration tool can manage only one InterChange Server per session.
To open the Edit Configuration tool:
Use the Edit Configuration tool to configure the destination for InterChange Server message logging and tracing.
When configuring these settings, keep the following information about STDOUT in mind:
UNIX |
---|
If you set the logging and tracing to STDOUT, messages are automatically rerouted to $PRODUCTDIR/logs/ics_manager.log. |
Windows |
---|
If you plan to run InterChange Server as a service, you must set logging and tracing to file destinations. Setting logging and tracing to STDOUT prevents InterChange Server from being configured as a Windows service. |
The logging and tracing configuration window appears (see Figure 3).
If you choose to log messages to STDOUT, the messages appear in one of the following ways:
UNIX |
---|
If you set the logging and tracing to STDOUT, messages are automatically rerouted to $PRODUCTDIR/logs/ics_manager.log. |
Windows |
---|
STDOUT appears in the Command Prompt window in which InterChange Server starts. |
Your changes take effect immediately, and if you already had a log file configured, it is saved and dated, and a new file created using the newly entered configuration.
When ICS stack tracing is enabled, the stack trace information is printed to the ICS log file. This can be useful for troubleshooting a newly installed system.
The following instructions describe how to configure the stack tracing feature.
The upper-right quadrant of the System Manager becomes a tool in which you can edit the InterchangeSystem.cfg file (see Figure 4).
You can set other logging and tracing parameters, such as file size and number of archived files. The following instructions describe how to perform these tasks.
To set the maximum size of the log and trace files:
The upper-right quadrant of the System Manager becomes a tool in which you can edit the InterchangeSystem.cfg file (see Figure 4).
To configure the number of archive files:
The upper-right quadrant of the System Manager becomes a tool in which you can edit the InterchangeSystem.cfg file (see Figure 4).
The two connector components have separate mechanisms for logging. Connector controller logging is sent to the InterchangeServer.log file. This section describes configuring the connector agent log file name and location.
For background information on connector agent logging, see "Connector Agent logs".
You can set the destination for connector agent logging using one of the following methods:
To configure the destination for connector agent logging using Connector Configurator, connect to a server, then follow these steps:
For example, change the LogAtInterchangeEnd value to true to send messages to the InterChange Server log. If InterChange Server is configured to send e-mail when error and fatal messages are logged, e-mail is sent for the connector agent messages as well.
For example, to send connector agent messages to a message file instead of the default STDOUT, enter the full pathname of the file in the Value field.
This section describes how to configure tracing levels for business objects, collaborations, and the IBM WebSphere ICS subsystems using the Edit Configuration tool in System Manager. For details on viewing the trace messages, see Log Viewer and tracing.
To open the Edit Configuration tool, right-click the server from the Server Instances section of System Manager, then select Edit Configuration. The upper-right section of the System Manager window becomes a tool from which you can edit the InterchangeServer.cfg file.
To configure tracing:
Setting these trace levels updates parameters in the InterchangeSystem.cfg file. For details about what information is produced at the various tracing levels, see "InterChange Server Configuration Parameters" in the System Installation Guide for UNIX or for Windows.
The collaboration names that are configured for the system display in the list box.
Click the down arrow in the Level area to select the trace level for that collaboration.
For a description of the trace levels for collaborations, see Tracing collaboration objects.
The business object names that are configured for the system display in the list box.
The trace levels for the subsystems, business objects and collaborations are immediately in effect.
This section describes one of two method that can be used to configure collaboration object trace levels. For the alternative method, see Configuring tracing levels for InterChange Server, business objects, and collaborations.
To configure the runtime system trace level for a collaboration object:
Collaboration object tracing returns messages from inside the collaboration. For a description of collaboration object trace levels, see Tracing collaboration objects.
To configure collaboration object tracing:
A collaboration object starts tracing as soon as its tracing level changes.
For background information, see Tracing connectors.
To trace a connector controller, set the ControllerTraceLevel property value to the trace level. Any changes to this property take effect immediately. Trace messages for connector controllers appear wherever InterChange Server sends its trace messages.
To set a connector controller's tracing level, do the following:
To trace a connector agent, set the AgentTraceLevel property value to the trace level. Any changes to this property take effect immediately. Trace messages for connector agents appear wherever the connector agent logs messages. To set a connector agent's tracing level, do the following:
For background information, see Tracing maps. To set the trace level for a map:
To troubleshoot a problem, you can turn on tracing. Trace messages help you monitor actions taken in components of the WebSphere ICS system. Trace levels define the amount of detail written to the trace file. The higher the trace level, the more detail you receive.
Tracing is off by default because it produces messages that are more detailed than you normally need. You can turn tracing on and off as necessary while InterChange Server is running.
For background information about tracing, see About tracing. For configuration information about tracing, see Configuring logging and tracing.
Use Log Viewer to display trace information for InterChange Server. In addition to displaying the debugging trace information for collaborations, it allows you to view the progression of a business object as it passes from one processing point to another, for example as the business object exits the collaboration processing point and is sent on to other collaborations or connectors for processing or is forwarded to the mapping stage for data transformation. For information about flow tracing, see Tracing business objects (flow tracing).
InterChange Server system message logging is used to communicate messages, component state changes, and failures.
You can view log files containing messages and explanations of system messages either of these ways:
Log Viewer allows you to see all messages contained in a log file. You can sort and filter the output display as well as print, save, and e-mail of the file.
To start Log Viewer, you can either:
Using the Log Viewer menu options, you can perform the following tasks:
Log Viewer, displaying a sample log file is shown in Figure 7.
The User Configuration Options, General properties window appears (see Figure 8).
Figure 8. Log Viewer User configuration options dialog box, General Properties tab
This window allows you to determine how to display the log file when you open a log file. The available choices are:
The User Configuration Options, Format properties window displays (see Figure 9).
Figure 9. Log Viewer User configuration options, Format tab
This window allows you to determine how to display the log messages. The available choices are:
The User Configuration Options, Columns properties window displays (see Figure 10).
Figure 10. Log Viewer User configuration options, Columns tab
This window allows you to determine which columns display in Log Viewer. To change the columns that display:
The View menu contains additional options to change Log Viewer displays. In that menu, you'll find the following options:
Click the down arrow in each sort field to select Date/Time, EventID, or business object. Further sort by ascending or descending ordering.
Several options are available for manipulating Log Viewer output. In the File menu, there are options for print previewing, printing, saving, refreshing the display, sending to an e-mail recipient, and determining the style for page setup, headers and footers. The variables for header and footers are:
To filter the messages that will be displayed in Log Viewer, choose View->Filter->Use Filter in the Log Viewer menu. The Filter Settings dialog will display.
The Filter Settings dialog displays categories that correspond to the parameters of the logging message format (see Table 2 for a descriptive list of the parameters).
In the Filter Settings dialog, you first choose the filtering categories that you want to use, then select the specific items that you want to display from each category, and then choose which filters you want to activate for your current Log Viewer display.
Follow these steps:
You can use the buttons below the list box to select all the displayed items, or to deselect all the displayed items, or to invert your current selection choices.
Note that in addition to filtering according to the categories, you can also display only those messages that contain a specific text string. To do so, choose Message under Set up Filters, enter the specific text for which you want to show messages, and check the box for Message under Activate Filters.
Flow tracing a business object or access flow allows you to track its progress throughout each of the processing points in its life cycle. Using Log Viewer, you can follow the progress by checking the trace messages that display. Each business object has an flow initiator ID associated with it for just this purpose. If you sort the Log Viewer display by flow initiator ID and date/time, the trace messages for the business object are grouped together so you can easily follow its status. Sort by ascending or descending order to see a historical perspective or the latest event displayed first.
To trace a business object flow:
This action uses the Business Object Viewer, which allows you to save the data to a separate file. The file can then be read by either the Mapping tool or the Test Connector.