Using log and trace files for troubleshooting

This section describes how to use log and trace files for troubleshooting. The following topics are covered:

"About logging"

Configuring e-mail notification of log messages

About tracing

"Configuring logging and tracing"

About logging

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.

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

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:

Note:
Log Viewer is an IBM WebSphere ICS system tool, which means it runs only on Windows operating systems. To configure or view a UNIX log file or message using Log Viewer, copy the file from the UNIX machine to a Windows machine that has the IBM WebSphere ICS product installed.

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

Collaboration object messages

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

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.

Message formats

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:

Table 1. Message format

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.

Table 2. Message types

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.

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

System logs

InterChange Server logs

InterChange Server can log messages to the following destinations:

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.

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

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.

High-Availability system logs

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.

Log/Trace file management

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:

Configuring e-mail notification of log messages

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.

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.

Configuring e-mail notification at the system level

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:

  1. From System Manager, right-click the server under Server Instances, then select Edit Configuration. The upper-right section of the System Manager window becomes a tool in which you can edit the InterchangeSystem.cfg file.
  2. Click the E-mail tab. A dialog box appears in the upper-right section of the System Manager window in which you can enter the parameters necessary for configuring e-mail notification at the system level (see Figure 2).

    Figure 2. Edit Configuration, E-mail tab


  3. Select an e-mail type from the "E-mail send type" drop-down menu. Your choices are "Java mail" or "Connector mail."
  4. Type one or more valid e-mail addresses in each subsystem field. The address must be SMTP-compliant. For information on SMTP compliancy, see Using Valid E-mail addresses.
  5. Select the "Save <server_name>" option from the File drop-down menu of System Manager. The system-level e-mail notification information you entered is saved in the InterchangeSystem.cfg file.

Configuring the e-Mail business object

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.

  1. From System Manager, right-click the EmailNotification business object, then select "Edit definition." The EmailNotification Business Object Designer window appears.
  2. From the Attributes tab, type in the return e-mail address in the Defaults column of the FromAddress attribute.
  3. Select Save from the File drop-down menu.
  4. Close Business Object Designer.

Configuring the e-Mail connector

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:

  1. From System Manager, double-click the EmailConnector object. The Connector Configurator window appears.
  2. From the Connector Specific Properties tab, double-click the Value cell for the SMTP_MailHost property, then type in the name of the Simple Mail Transport Protocol (SMTP) host in the text field.
  3. Click Save > To Project from the File drop-down menu.
  4. Close the Connector Configurator window.

Configuring e-mail notification at the collaboration object level

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.

Note:
Configuration parameters set at the collaboration object level supersede those set at the system level.

To set an e-mail address to receive messages for a collaboration, do the following:

  1. From System Manager, right-click the collaboration object for which you want to configure e-mail notification, then select Properties. The Properties dialog box appears.
  2. In the Collaboration General Properties tab, enter a valid e-mail address in the "Email notification address" field. The address must be SMTP-compliant. For information on SMTP compliancy, see Using Valid E-mail addresses.
  3. Click OK to save your changes and close the window.
  4. Restart the collaboration for changes to take effect.

Configuring e-mail notification at the connector level

This section describes how to configure e-mail notification for a specific connector.

Note:
Configuration parameters set at the collaboration object level supersede those set at the system level.
  1. From System Manager, right-click the connector for which you want to configure e-mail notification, then select Edit Definition. The Connector Configurator window appears.
  2. From the Properties tab, select true in the Value field of the LogAtInterchangeEnd property. This enables connector messages to be mailed to the InterChange Server log.
  3. Click Save > To Project from the File drop-down menu.
  4. Close the Connector Configurator window.
  5. Restart the connector for the change to take effect.

Using Valid E-mail addresses

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.

About tracing

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 of InterChange Server

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.

Tracing collaboration objects

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

Tracing connectors

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.

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.

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 maps

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

Tracing business objects (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 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.

Tracing Web gateways

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

Tracing SNMP agents

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.

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:

"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

Configuring connector tracing

Configuring map tracing

Opening the Edit Configuration tool

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:

  1. From System Manager right-click a server listed under Server Instances, 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.
  2. Click either the Tracing Levels tab or the Trace/Log Files tab to configure tracing and message logging. See Configuring InterChange Server logging and tracing destinations and Configuring tracing levels for InterChange Server, business objects, and collaborations for task instructions.

Configuring InterChange Server logging and tracing destinations

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.

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

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

    Figure 3. Edit Configuration tool, Trace/Log Files tab


  2. In the Logging area, select the destination for system logging. You can log to both system console and a log file, but this option should be used only for debugging and on development systems.
    1. To log to the system console (standard output), which is the default, make sure the To console (STDOUT) box is checked. To disable the console as the logging destination, uncheck the To console (STDOUT) option.
    2. To log to a file, click the To File box and either type in the full pathname of the file or click the browse (...) button to navigate to the log file.
    3. If you select a log file, optionally configure the size of the file in MBs (or keep the default, Unlimited) and the number of archive files to create. For information about archives, see "Maintaining event archives".
  3. In the Tracing area, select the destination for system tracing.
    1. To log to the system console (standard output), click the To console (STDOUT) box. To disable the console as the logging destination, uncheck the To console (STDOUT) option.

      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.

    2. To log to a file, click the To File box and either type in the full pathname of the file or click the browse (...) button to navigate to the trace file.
    3. If you select a trace file, configure the size of the file in MBs (or keep the default, unlimited checked) and the number of archive files to create. For information about archives, see "Maintaining event archives".
  4. To configure WebSphere MQ tracing, accept the default pathname of the file or click the browse (...) button to navigate to the log file.
  5. Click OK 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.

Configuring stack trace

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.

  1. From the InterChage Server Component Management view in System Manager, right-click the ICS instance for which you want to configure stack tracing, then select Edit Configuration.

    The upper-right quadrant of the System Manager becomes a tool in which you can edit the InterchangeSystem.cfg file (see Figure 4).

    Figure 4. Configuring stack tracing


  2. In the Trace/Log Files tab, enter the following values:

Configuring other InterChange Server logging and tracing parameters

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:

  1. From the InterChage Server Component Management view in System Manager, right-click the ICS instance for which you want to set the maximum size for log and trace files, then select Edit Configuration.

    The upper-right quadrant of the System Manager becomes a tool in which you can edit the InterchangeSystem.cfg file (see Figure 4).

  2. To limit the log file, in the Trace/Log Files tab, select a number to represent the maximum log file size from the Log file drop-down menu, then select Byte, KB (kilobyte), MB (megabyte), or GB (gigabyte).
    Note:
    The To File and the Unlimited checkboxes in the Logging section must both be selected before you can enter a maximum log file size.
  3. To limit the trace file, in the Trace/Log Files tab, select a number to represent the maximum trace file size from the Trace file drop-down menu, then select Byte, KB (kilobyte), MB (megabyte), or GB (gigabyte).
    Note:
    The To File and the Unlimited checkboxes in the Tracing section must both be selected before you can enter a maximum trace file size.
  4. Stop and restart InterChange Server.

To configure the number of archive files:

  1. From the InterChage Server Component Management view in System Manager, right-click the ICS instance for which you want to set the maximum size for log and trace files, then select Edit Configuration.

    The upper-right quadrant of the System Manager becomes a tool in which you can edit the InterchangeSystem.cfg file (see Figure 4).

  2. To set the number of log or trace file archives, from the Trace/Log Files tab, select a number from the "Number of archives" drop-down list from either the Logging or Tracing section.
    Note:
    The To File and the Unlimited checkboxes must both be selected before you can select a number from the "Number of archives" drop-down menu. This is true for either the Logging or Tracing section.
  3. Stop and restart InterChange Server.

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:

To configure the destination for connector agent logging using Connector Configurator, connect to a server, then follow these steps:

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.
  1. From System Manager, right-click a connector object, then select Edit Definitions. The Connector Configurator widow appears.
  2. From the Standard Properties tab, select one of the logging property values (see Table 3 for an explanation of these values), then click Edit.
  3. Enter the new value in Value field, then click OK.

    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.

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

    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.

  5. Restart the connector for changes to take effect.

Configuring tracing levels for InterChange Server, business objects, and collaborations

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:

  1. From Edit Configuration tool, select the Tracing Levels tab. Two categories appear in the window: Flow Tracing Levels and IBM WebSphere Business Integration System Tracing Levels (see Figure 5).

    Figure 5. Edit Configuration tool, Tracing Levels tab


  2. To configure subsystem tracing, in the IBM WebSphere Business Integration Trace Levels section, click the down arrow next to the subsystems you want to trace and set the trace level using the down arrow menu.

    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.

  3. To configure tracing for collaborations, in the Flow Tracing Levels section, click the Component down arrow and select Collaborations.

    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.

  4. To configure flow tracing for business objects, click the Component down arrow and select Business Objects. For a description of tracing levels for business objects, see Tracing business objects (flow tracing).

    The business object names that are configured for the system display in the list box.

    1. Click the down arrow in the Level area to select the trace level for that business object.
  5. Click OK to save changes and exit.

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

Configuring the collaboration object trace level

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:

  1. From System Manager, right-click the collaboration object name, then select Properties. The Properties dialog box appears.
  2. Select a System trace level value, then click OK.

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:

  1. From System Manager, right-click the collaboration object name, then select Properties. The Properties dialog box appears.
  2. In the Collaboration Trace Level field, select a value, then click OK.

    A collaboration object starts tracing as soon as its tracing level changes.

Configuring connector tracing

For background information, see Tracing connectors.

Connector controller tracing

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:

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.
  1. From System Manager, right-click the connector object, then select Edit Definitions. The Connector Configurator window appears.
  2. From the Standard Properties tab, click in the Value field of the ControllerTraceLevel property, then set the controller tracing level.
  3. Select Save > To Project from the File drop-down menu.
  4. Close Connector Configurator.

Connector agent tracing

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:

  1. From System Manager, right-click the connector, then select Edit Definitions. The Connector Configurator window appears
  2. From the Standard Properties tab, click the Value field of the AgentTraceLevel property, then set the agent tracing level.
  3. Select Save > To Project from the File drop-down menu.
  4. Close Connector Configurator.

Configuring map tracing

For background information, see Tracing maps. To set the trace level for a map:

  1. From System Manager, right-click the map object, then select Properties. The Maps Property Page appears (see Figure 6).

    Figure 6. Maps Property Page


  2. In the Trace Level field, enter the appropriate value.
  3. Click OK.

Using tracing

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.

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

Note:
Log Viewer is a WebSphere ICS tool, which means it runs only on Windows machines. To configure or view a UNIX log file using Log Viewer, copy the log file from the UNIX machine to a Windows machine that has the WebSphere ICS product installed.

Viewing log messages

InterChange Server 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 to be running. The WebSphere ICS 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:

Using Log Viewer

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.

Note:
Log Viewer is a WebSphere ICS tool, which means it runs only on Windows operating systems. To configure or view a UNIX log file using Log Viewer, copy the log file from the UNIX machine to a Windows machine that has the WebSphere ICS product installed.

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.

Figure 7. Log Viewer


Setting Log Viewer Preferences
  1. Log Viewer preferences are set by selecting the Preferences option from Log Viewer Edit menu.

    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:

  2. To change the background color and font of the Log Viewer messages, click the Format tab.

    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:

  3. To change which Log Viewer columns display, click the Columns tab.

    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:

Changing how messages are viewed

The View menu contains additional options to change Log Viewer displays. In that menu, you'll find the following options:

Manipulating the 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 header 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})

Filtering messages

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:

  1. In the Filter Settings dialog, choose a tab under Set up Filters to display the items that you want to use for filtering messages. For example, choose the BusObj tab to display a list of business objects to be used in filtering, and choose 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 in conjunction with each other.
  2. 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 timestamped between 5 March 2002 at 9:00 AM and 6 March 2002 at 5:00 PM, 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, or to deselect all the displayed items, or to invert your current selection choices.

  3. Under Activate Filters, check the 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.
  4. Choose OK. The Filter Settings dialog closes, and the Log Viewer display 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, 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

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.

Note:
Flow tracing is performed only while the business object is within the domain of InterChange Server, 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 while the business object is being processed by connector agents or applications.

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 Configuring tracing levels for InterChange Server, business objects, and collaborations).
  3. Send some event from the source connector to the destination connector.
  4. Open Log Viewer (see Using Log Viewer).
  5. Set the display preferences to view the flow tracing (see Changing how messages are viewed).
  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. 1997, 2004