Using log and trace files for troubleshooting

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

Overview of log and trace files

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.

Note:
STDOUT on OS/400 and i5/OS results in the information being written to a spool file associated with the InterChange Server Express job. Therefore, on OS/400 and i5/OS, logging is configured by default to be sent to a file in the /QIBM/UserData/WBIServer44/serverName/log directory where serverName is the name of the InterChange Server Express instance (the default server name is QWBIDFT44).

The messaging system is always active and provides an accurate monitor of the system.

Note:
If you configure the messages generated from the connector agent to be sent to a separate log file, you must specify a log file or location that is separate from the InterChange Server Express log file.

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:

Note:
Log Viewer runs only on Windows 2000 or Windows XP operating systems. To configure or view a Linux or OS/400 and i5/OS log file or message using Log Viewer, copy the file to a Windows machine that has the IBM WebSphere InterChange Sever Express product installed, or map a network drive from the PC to the OS/400 and i5/OS system and access the log file directly from the mapped drive.
Note:
On OS/400 and i5/OS, the timestamps in the log and trace files are determined from the settings of 2 system values, QTIME and QUTCOFFSET, and the setting of the user.timezone property in the SystemDefault.properties file located in the /QIBM/UserData/Java400/ directory. When user.timezone is set to a value, for example, user.timezone=EDT, Java on OS/400 and i5/OS generates the timestamps in Eastern Daylight Time. If user.timezone is not set, Java on OS/400 and i5/OS generates timestamps in Greenwich Mean Time (GMT) by taking the QTIME and subtracting the value of QUTCOFFSET from it. So, for example, if QUTCOFFSET is -04:00 (which is Eastern time zone), Java will subtracts a -4 from the current value of QTIME to get GMT. On OS/400 and i5/OS version 5R3, instead of setting QUTCOFFSET, you set system value QTIMZON. Refer to the help text for the system values on OS/400 and i5/OS for more information.

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:

Collaboration object messages

Connector messages

Message formats

System logs

Log/trace file management

Collaboration object messages

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

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.

Message formats

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:

Table 17. Message format
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.

Table 18. Message types
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.

Note:
If a message with the Internal Error or Internal Fatal Error severity appears, record the circumstances surrounding the problem, and then contact InterChange Server Express Technical Support.

System logs

InterChange Server Express logs

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 logs

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

Table 19. Connector agent log message properties
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.

Log/trace file management

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.

Figure 51. 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 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:

Trace files

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 Express

Tracing 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 tracing

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

Table 20. Collaboration object tracing 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 tracing

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.

You can set connector agent and controller tracing to one of the following levels:

Table 21. Connector agent and controller tracing 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 tracing

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

Table 22. Business object tracing levels
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 tracing

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

Table 23. Gateway tracing levels
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).

Configuring e-mail notification of log messages

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.

Note:
If you want to configure collaborations for e-mail notification, you must use the e-Mail connector.

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.

Steps for configuring e-mail notification at the system level

Perform the following steps to configure e-mail notification at the system level:

  1. Open System Manager
  2. In the InterChange Server Component Management view, right-click the server and click Edit Configuration.

    The editing tool opens, in which you can edit the InterchangeSystem.cfg file.

  3. Click the E-mail tab.

    A dialog box appears whichallows you to enter the parameters necessary for configuring e-mail notification at the system level (see Figure 52).

    Figure 52. Edit Configuration, E-mail tab
  4. Select an e-mail type from the E-mail send type list:
  5. Type one or more valid e-mail addresses in each subsystem field. The address must be SMTP-compliant.
  6. In System Manager, click File > Save ServerName. The system-level e-mail notification information you entered is saved in the InterchangeSystem.cfg file.
  7. Additional step if you configured Connector mail: 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 InterChange Server Express system administrator, to ensure the mail is delivered if the InterChange Server Express system administrator is unreachable.

    Do the following:

  8. Additional step if you configured Connector mail: Configure the e-Mail connector.

    Do the following:

Steps for configuring e-mail notification at the collaboration object level

Perform the following steps to set an e-mail address to receive messages for a collaboration:

  1. In System Manager, go to the InterChange Server Component Management view, right-click the collaboration object for which you want to configure e-mail notification, and click Properties.

    The Properties dialog box appears.

  2. In the Collaboration General Properties tab, type a valid e-mail address in the Email notification address field. The address must be SMTP-compliant.
  3. Click OK to save your changes and close the window.
  4. Restart the collaboration for changes to take effect.

Steps for configuring e-mail notification at the connector level

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:

  1. In System Manager, right-click the connector for which you want to configure e-mail notification, and click Edit Definition.

    The Connector Configurator Express window appears.

  2. In the Standard Properties tab, select true in the Value field of the LogAtInterchangeEnd property. This enables connector messages to be mailed to the InterChange Server Express log.
  3. Click File > Save > To Project.
  4. Close the Connector Configurator Express window.
  5. Restart the connector for the change to take effect.

Configuring logging and tracing

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 tracing levels for InterChange Server Express, business objects, and collaborations

Steps for configuring the collaboration object trace level

Steps for configuring connector tracing

Steps for configuring map tracing

Steps for opening the Edit Configuration tool

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:

  1. Open System Manager.
  2. Right-click a server instance in the InterChange Server Component Management view and click Edit Configuration. The Edit Configuration tool opens in which you can edit the InterchangeServer.cfg file.

Steps for configuring InterChange Server Express logging and tracing destinations

When configuring these settings, keep the following information about STDOUT in mind:

Linux

If you set the logging and tracing to STDOUT, messages are automatically rerouted to $PRODUCTDIR/logs/ics_manager.log.

i5/OS

If you set the logging and tracing to STDOUT, the messages will be written to a spooled file associated with the Server job.

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.

Perform the following steps to configure the destination for InterChange Server Express message logging and tracing:

  1. In the Edit Configuration tool, click the Trace/Log Files tab.

    The logging and tracing configuration window appears (see Figure 53).

    Figure 53. Edit Configuration tool, Trace/Log Files tab
  2. Under Logging, select the destination for system logging. You can log to both system console and a log file, but use this option only for debugging and only on development systems. Do the following:
  3. Under Tracing, select the destination for system tracing. Do the following:
  4. To configure IBM WebSphere MQ tracing, accept the default path name of the file or click the browse button to navigate to the log file.
  5. Select File > Save or click Ctrl+S to save changes and exit.

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.

Steps for configuring stack trace

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:

  1. Open the Edit Configuration tool (see Steps for opening the Edit Configuration tool).
  2. Click the Trace/Log Files tab.
  3. Select the Enable Stack Tracing check box. When you enable stack tracing, the Tracing Severity Level list is available.
  4. In the Tracing Severity Level list, select the severity level for which you want to print the stack tracing. The choices are: INFO, WARNING, ERROR, and FATAL. When stack tracing is printed to the log file, it prints the level you select and all levels above it. For example, if you select ERROR, both ERROR and FATAL messages are printed to the log file.

Steps for configuring other InterChange Server Express logging and tracing parameters

Perform the following steps to set file size and number of archived files for log and trace files:

  1. Open the Edit Configuration tool (see Steps for opening the Edit Configuration tool).
  2. Click the Trace/Log Files tab.
  3. To limit the log file, select the To File and the Unlimited check boxes, and select a number to represent the maximum log file size from the Log file list, and then select Byte, KB (kilobyte), MB (megabyte), or GB (gigabyte).
  4. To limit the trace file, select the To File and the Unlimited check boxes, select a number to represent the maximum trace file size from the Trace file list, then select Byte, KB (kilobyte), MB (megabyte), or GB (gigabyte).
  5. To set the number of log or trace file archives, select a number from the Number of archives list under either Logging or Tracing section.
  6. Stop and restart InterChange Server Express.

Steps for configuring the connector agent logging destination

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:

  1. Connect to a server.
  2. In System Manager, right-click a connector object, then select Edit definition. The Connector Configurator Express widow appears.
  3. Click the Standard Properties tab.
  4. Select one of the logging property values (see Table 19 for an explanation of these values), and click Edit.
  5. Type the new value in Value field and click OK.

    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.

  6. Repeat Steps 3 and 4 to edit the other logging property value if necessary.

    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.

  7. Restart the connector for changes to take effect.
Note:
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.

Steps for configuring tracing levels for InterChange Server Express, business objects, and collaborations

Perform the following steps to configure tracing:

  1. Open the Edit Configuration tool (see Steps for opening the Edit Configuration tool).
  2. Click the Tracing Levels tab (see Figure 54).
    Figure 54. Edit Configuration tool, Tracing Levels tab
  3. To configure subsystem tracing, under IBM WebSphere Business Integration Trace Levels, select a Trace level for the subsystems you want to configure.

    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.

  4. To configure tracing for collaborations, do the following:
  5. To configure tracing for business objects, do the following:
  6. Select File > Save or click Ctrl+S to save changes and exit.

    The trace levels for the subsystems, business objects and collaborations are immediately in effect.

Steps for configuring the collaboration object trace level

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:

  1. In System Manager, go to the InterChange Server Component Management view, right-click the collaboration object, and click Properties. The Properties dialog box appears.
  2. Do one of the following on the Collaboration General Properties tab:

Steps for configuring connector tracing

Perform the following steps to configure connector tracing:

  1. From System Manager, right-click the connector object, then click Edit definition. The Connector Configurator Express window appears.
  2. Do one of the following:
  3. Click File > Save > To Project.
  4. Close Connector Configurator Express.

    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.

    Note:
    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.

Steps for configuring map tracing

Perform the following steps to set the trace level for a map:

  1. In System Manager, go to the InterChange Server Component Management view, right-click the map object, and click Properties. The Maps Property Page appears (see Figure 55).
    Figure 55. Maps Property Page
  2. In the Trace Level field, type the appropriate value.
  3. Select File > Save or click Ctrl+S.

Working with tracing in Log Viewer

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.

Overview of Log Viewer 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).

OS/400

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.

Note:
Log Viewer views log files and therefore does not need InterChange Server Express to be running. The InterChange Server Express system administrator must have the appropriate file system permissions set to view log files.

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

Figure 56. Log Viewer

Steps for starting Log Viewer

Perform one of these steps to start Log Viewer:

Steps for setting Log Viewer preferences

Perform the following steps to set Log Viewer preferences:

  1. Click Edit > Preferences.

    The User configuration options dialog box appears, with the General tab selected (see Figure 57).

    Figure 57. Log Viewer User configuration options dialog box, General Properties tab
  2. Under Open action, select how to display the log file when you open a log file:
  3. To change the background color and font of the Log Viewer messages, click the Format tab.

    The Format tab appears (see Figure 58).

    Figure 58. Log Viewer User configuration options, Format tab
  4. Select options to display the various types of log messages:
  5. To change which Log Viewer columns are displayed, click the Columns tab.

    The Columns tab opens (see Figure 59).

    Figure 59. Log Viewer User configuration options, Columns tab

    This window allows you to determine which columns display in Log Viewer:

Overview of Log Viewer display options

The View menu contains additional options to change how Log Viewer appears:

Overview of Log Viewer display output

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:

$F
Name of file
$A
Application name
$P
Page number
$N
Total number of pages
$D
Date (can be followed by additional parameters (for example $D{%y:%h:%m})

Steps for filtering messages

Perform the following steps to filter messages in Log Viewer:

  1. Click View > Filter >Use Filter. The Filter Settings dialog box appears. The Filter Settings dialog box displays categories that correspond to the parameters of the logging message format (see Table 18 for a descriptive list of the parameters).
  2. Select a tab under Set up Filters to display the items that you want to use for filtering messages. For example, select the BusObj tab to display a list of business objects to be used in filtering, and select Time if you want to filter according to the timestamp of the message. You can set up multiple filters, and use them either separately or with one another.
  3. In the displayed list of items, select each item for which you want to view messages in Log Viewer. For example, if you want to view messages related only to the Cost and Customer business objects, select only those business objects in the list. If you want to view only messages that are time-stamped between 5 March 2002 at 9:00 a.m. and 6 March 2002 at 5:00 a.m., select the range for those times under the Time tab.

    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.

  4. Under Activate Filters, select the check box for each filter type that you want to activate. For example, if you want to see all messages for the Cost and Customer business objects (which you specified in the previous step), activate only the BusObj filter. If you want to see only those messages for the Cost and Customer business objects that have a particular timestamp, activate both the BusObj filter and the Time filter.
  5. Click OK. The Filter Settings dialog box closes, and the Log Viewer refreshes to show only those messages that you have allowed through the filters.

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.

Steps for tracing a business object flow

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.

Note:
Flow tracing is performed only when the business object is within the domain of InterChange Server Express, that is, from the connector controller of the source application to the connector controller of the destination application. Business object flow tracing is not performed when the business object is processed by connector agents or applications.

Perform the following steps to trace a business object flow:

  1. Set the trace log file destination, if necessary (see Configuring logging and tracing).
  2. Select the originating triggering business object (not the generic business object) to trace and set its trace level (see Steps for configuring tracing levels for InterChange Server Express, business objects, and collaborations).
  3. Send an event from the source connector to the destination connector.
  4. Open Log Viewer (see Steps for starting Log Viewer).
  5. Set the display preferences to view the flow tracing (see Overview of Log Viewer display options).
  6. Click any error message button in the MsgID column to view the text of the message.
  7. Click any of the business object name buttons in the BusObj column to view the data contained within the business object.

    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.

Copyright IBM Corp. 2004, 2005