This section describes how to use log and trace files for troubleshooting. The following topics are covered:
Overview of log and trace files
Configuring e-mail notification of log messages
Configuring logging and tracing
Working with tracing in Log Viewer
Logging is used to communicate system messages, component state changes, failures, and tracing information. Messages that are generated from InterChange Server Express, collaboration objects, and connectors are sent to the destination you specified when you installed InterChange Server Express, 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.
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, and determine their size. Tracing, which is disabled by default because of its effect on 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:
In addition to using LogViewer 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 Overview of Log Viewer and tracing.
This section covers the following topics:
A collaboration object can generate messages to report run-time information, warnings, and errors. For example, a collaboration might log its decision points and the results of operations.
As InterChange Server Express 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 Express message destination. Depending on your operating system, messages appear in one of the following ways:
For information about connector logging, see Connector Agent logs.
To aid in troubleshooting, a temporary log file is created during the connector agent boot-up 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 Express and connectors use the same format, which is described in Table 17.. When business objects are configured for flow tracing messages, they use these fields and the additional fields, denoted by an asterisk in Table 17.. A message delivered to InterChange Server Express 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 | Type of component (system identifier). It can be Server, Collaboration, Business Object, or ConnectorAgent. |
Thread | Thread name and thread ID |
Name | Name of the component, such as ClarifyConnector. |
MsgType | Severity of the message. See Table 18. |
MsgID | Message number. |
SubSystem* | Subsystem of the current system. It can be Event Management, Messaging, Repository, or Database Connectivity. |
FIID* | Flow initiator ID of the business object. |
BO* | Business object name. |
MsgText | 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 18 describes the types of InterChange Server Express messages.
Type | Description |
---|---|
Info | Informational only. You do not need to take action. |
Warning | A default condition chosen by InterChange Server Express. |
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 Express can log messages to the following destinations:
In addition to managing regular logging, InterChange Server Express can send an e-mail message to a specified user when it generates error or fatal error messages.
By default, trace messages are sent to the system log file. In some cases, this file may become too large, so it is recommended that you specify a separate trace file. See Trace files 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.
Connector Agent logsThe 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 Express messages.
A connector agent logs messages to a local destination and can also send its messages to InterChange Server Express for logging. To specify a log file name, edit the LogFileName property of the connector (using the Connector Configurator Express) and insert the name of the log file you want to use.
If you want to specify a logging and tracing file for the connector agent, you must specify a local configuration file when starting the agent.
The default log file (located at STDOUT), contains text for the error and informational messages raised from the connector. Name is the name of the application.
Table 19 describes the properties you can edit that determine where a connector agent logs messages.
Property name | Description | Type of value |
---|---|---|
LogAtInterchangeEnd | Specifies whether the connector agent sends messages
to InterChange Server Express in addition to logging them locally.
At InterChange Server Express, connector agent messages appear wherever server messages appear, according to the InterchangeSystem.cfg file. |
Either true (sends messages to InterChange Server Express 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 instructions on configuring these properties, see Steps for configuring the connector agent logging destination.
When the InterChange system is started, a log file is created if one does not exist, or is appended 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.
InterChange Server Express system log files can be configured to a specified size and then automatically archived after 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 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 51 shows the progression of files using this configuration.
See the configuration tasks Configuring logging and tracing for details.
If the system log file is configured for unlimited size, InterChange Server Express writes to the log until the disk that the log file is located on gradually fills; if the disk is not managed, the system returns an error message when the disk is full.
The data in the following files should be deleted periodically:
In addition to the log files above, other log files exist that are specific to each application. Most files are created during run time if they do not already exist. New information is appended to any existing file. Each component that supplies log information to the files must be stopped before proceeding with a backup.
Any file management procedure can be used, but the following periodic log file management is recommended:
To troubleshoot a problem, you can turn on tracing. Trace messages help you monitor actions taken in components of the InterChange Server Express 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 when InterChange Server Express is running.
Tracing services of InterChange Server ExpressTracing services for InterChange Server Express are initially set in parameters of the configuration file for InterChange Server Express (by default, this file is called InterchangeSystem.cfg and resides in the product's top level directory. For details about these parameters, refer to the WebSphere Business Integration Server Express installation guide for Windows, for Linux, or for OS/400 and i5/OS. Settings for these parameters can be updated in the Edit Configuration tool of System Manager, as described in Steps for configuring tracing levels for InterChange Server Express, business objects, and collaborations.
Collaboration object tracingYou 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 run-time 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:
Trace level | Description |
---|---|
1 | Traces the receipt of business objects from connectors and the start 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 instructions, see Steps for configuring tracing levels for InterChange Server Express, business objects, and collaborations.
Connector tracingA 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.
You can set connector agent and controller tracing to one of the following levels:
Trace level | Description |
---|---|
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.
If you want to specify a logging and tracing file for the connector agent, you must specify a local configuration file when starting the agent.
For configuration instructions, see Steps for configuring connector tracing.
Map tracingYou can use System Manager to set up tracing for maps. Tracing maps is useful for debugging and keeping track of information and error messages created by the map. Tracing of maps is turned off by default.
For more information about tracing maps, see the Map Development Guide. For configuration instructions, see Steps for configuring map tracing.
Business object tracing (flow 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 22 describes the configurable levels associated with business object tracing:
Trace 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, and maps these traces to level 3 event tracing. This level of tracing affects system performance. |
For configuration instructions, see Steps for configuring tracing levels for InterChange Server Express, business objects, and collaborations.
Web gateway tracingWeb gateway tracing is provided at two levels, minimum 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 23 describes the configurable levels associated with gateway tracing:
Trace Level | Description |
---|---|
0 | No tracing. |
1 | Minimum tracing (such as bind requests, socket openings, and so forth). |
5 | Maximum tracing (such as HTTP/HTTPS requests, including all headers). |
Error and fatal messages that are logged to the InterChange Server Express log can also be sent to the InterChange Server Express system administrator, or any other recipient, by e-mail. By default, InterChange Server Express 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 Steps for 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.
E-mail notification in the InterChange Server Express 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 commas. 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.
Perform the following steps to configure e-mail notification at the system level:
The editing tool opens, in which you can edit the InterchangeSystem.cfg file.
A dialog box appears whichallows you to enter the parameters necessary for configuring e-mail notification at the system level (see Figure 52).
Do the following:
Do the following:
Perform the following steps to set an e-mail address to receive messages for a collaboration:
The Properties dialog box appears.
You can configure e-mail notification for a specific connector, however, configuration parameters set at the collaboration object level supersede those set at the system level.
Perform the following steps to configure e-mail notification for a specific connector:
The Connector Configurator Express window appears.
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:
Steps for opening the Edit Configuration tool
Steps for configuring InterChange Server Express logging and tracing destinations
Steps for configuring other InterChange Server Express logging and tracing parameters
Steps for configuring the connector agent logging destination
Steps for configuring the collaboration object trace level
Steps for configuring connector tracing
Steps for configuring map tracing
InterChange Server Express must be running and in the Connected state to use the Edit Configuration tool. The Edit Configuration tool can manage only one InterChange Server Express per session.
Perform the following steps to open the Edit Configuration tool:
When configuring these settings, keep the following information about STDOUT in mind:
If you set the logging and tracing to STDOUT, messages are automatically rerouted to $PRODUCTDIR/logs/ics_manager.log.
If you set the logging and tracing to STDOUT, the messages will be written to a spooled file associated with the Server job.
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.
Perform the following steps to configure the destination for InterChange Server Express message logging and tracing:
The logging and tracing configuration window appears (see Figure 53).
If you choose to log messages to STDOUT, the messages appear in one of the following ways:
If you set the logging and tracing to STDOUT, messages are automatically rerouted to $PRODUCTDIR/logs/ics_manager.log.
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 InterChange Server Express stack tracing is enabled, the stack trace information is printed to the InterChange Server Express log file. This can be useful for troubleshooting a newly installed system.
Perform the following steps to configure the stack tracing feature:
Perform the following steps to set file size and number of archived files for log and trace files:
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:
Perform the following steps to configure the destination for connector agent logging using Connector Configurator Express:
For example, change the LogAtInterchangeEnd value to true to send messages to the InterChange Server Express log. If InterChange Server Express 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 path name of the file in the Value field.
Perform the following steps 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 the WebSphere Business Integration Server Express installation guide for Windows, for Linux, or for OS/400 and OS/400 and i5/OS.
For a description of the trace levels for collaborations, see Collaboration object tracing.
The trace levels for the subsystems, business objects and collaborations are immediately in effect.
This section describes one of two methods that can be used to configure collaboration object trace levels. For the alternative method, see Steps for configuring tracing levels for InterChange Server Express, business objects, and collaborations.
Perform the following steps to configure the collaboration object trace level:
A collaboration object starts tracing as soon as its tracing level changes.
Perform the following steps to configure connector tracing:
Any changes to these properties take effect immediately. Trace messages for connector controllers appear wherever InterChange Server Express sends its trace messages, and trace messages for connector agents appear wherever the connector agent logs messages.
Perform the following steps 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 InterChange Server Express 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 when InterChange Server Express is running.
For background information about tracing, see Trace files. For configuration information about tracing, see Configuring logging and tracing.
Use LogViewer to display trace information for InterChange Server Express. 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 Business object tracing (flow tracing).
When using Log Viewer to view logs, you must either copy the log file from OS/400 to a Windows system or map a network drive to the OS/400 system, and then navigate to the log file.
InterChange Server Express 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 and print, save, and e-mail of the file.
A sample log file is shown displayed in Log Viewer in Figure 56..
Perform one of these steps to start Log Viewer:
Perform the following steps to set Log Viewer preferences:
The User configuration options dialog box appears, with the General tab selected (see Figure 57).
The Format tab appears (see Figure 58).
The Columns tab opens (see Figure 59).
This window allows you to determine which columns display in Log Viewer:
The View menu contains additional options to change how Log Viewer appears:
Click the down arrow in each sort field to select Date/Time, an EventID, or a business object. Further sort by ascending or descending order.
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 headers and footers are:
Perform the following steps to filter messages in Log Viewer:
You can use the buttons below the list box to select all the displayed items, to clear all the displayed items, or to invert your current selected 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, click Message under Set up Filters, type the specific text for which you want to show messages, and select the check 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 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.
Perform the following steps 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.