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:
"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 are sent to the InterChange Server Express message destination. A connector logs message to STDOUT by default, but can be configured to send a local destination log file to the InterChange Server Express 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 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 16.. When business objects are configured for flow tracing messages, they use these fields and the additional fields, denoted by an asterisk in Table 16.. 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 17. |
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 17 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:
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.
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) 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 18 describes the properties you can edit that determine where a
connector agent logs messages.
Table 18. 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.
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 48 shows the progression of files using this configuration.
Figure 48. 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:
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 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 WebSphere Business Integration Server Express Installation Guide. 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.
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 19. 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".
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 20. 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".
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 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 21 describes the configurable levels associated with business
object tracing:
Table 21. 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 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 22 describes the configurable levels associated with gateway
tracing:
Table 22. 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). |