Trace messages

Tracing is an optional troubleshooting and debugging feature that can be turned on for connectors. When tracing is turned on, system administrators can follow events as they work their way through the IBM WebSphere business integration system.

WebSphere InterChange Server

When InterChange Server is the integration broker, you can also use tracing on connector controllers, and other components of the InterChange Server system.

Tracing in an application-specific component allows you and other users of your connector code to monitor the behavior of the connector. Tracing can also track when specific connector functions are called by the connector framework. Trace messages that you provide for the connector application-specific code augment the trace messages provided for the connector framework.

Enabling tracing

By default, tracing on a connector is turned off. Tracing is turned on for a connector when the connector configuration property TraceLevel is set to a non-zero value in Connector Configurator. You can set TraceLevel to a value from 1 to 5 to obtain the appropriate level of detail. Level 5 tracing logs the trace messages of all lower trace levels.

WebSphere InterChange Server

Tip:
For information on turning on tracing for connector controllers or for other components of the InterChange Server system, see the System Administration Guide in the IBM WebSphere InterChange Server documentation set.

Identifying a trace destination

A connector sends its trace messages into its trace destination, which is an external destination that is available for viewing by those needing to review the execution state of the connector. The trace destination is defined at connector configuration time by the setting of the Tracing field in the Trace/Log Files tab of Connector Configurator as one of the following:

By default, the connector's trace destination is set to the console, which indicates use of the startup script's command prompt window as the trace destination. Set this trace destination as appropriate for your connector.

Sending a trace message to the trace destination

Table 54 shows the ways that a connector sends a trace message to its trace destination.

Table 54. Methods for sending a trace message to the trace destination
Connector library method Description
traceWrite() and generateMsg() Takes as input a text string or a string generated from a message in a message file and a trace-level constant to indicate the trace level. This method writes a trace message for the specified trace level or greater to the trace destination. To generate a character string from the message text in a message file, use the generateMsg() method with the message type set to XRD_TRACE.
generateAndTraceMsg() Combines the functionality of the traceWrite() and generateMsg() methods into a single call.

For information on the generateMsg() method, see Generating a message string.

Note:
It is not required that trace messages be localized in the message file. Whether trace messages are contained in a message file is left at the discretion of the developer. For more information, see Locale-sensitive design principles.

In the Java connector library, the traceWrite(), generateMsg(), and generateAndTraceMsg() methods are defined in the CWConnectorUtil class.

The traceWrite() and generateAndTraceMsg() require a trace level as an argument. This argument specifies the trace level to use for a trace message. When you turn on tracing at runtime, you specify a trace level at which to run the tracing. All trace messages in your code with trace levels at or below the runtime trace level are sent to the trace destination. For more information, see Recommended content for trace messages.

To specify a trace level to associate with a trace message, use a trace-level constant of the form TRACELEVELn where n can be a trace level from 1 to 5. Trace-level constants are defined in the CWConnectorLogAndTrace class.

The generateMsg() method requires a message type as an argument. This argument indicates the severity of the message. Because trace messages do not have severity levels, you just use the XRD_TRACE message-type constant. Message-type constants are defined in the CWConnectorLogAndTrace class.

Note:
The generateAndTrace() method does not require a message type as an argument. The method automatically assumes the XRD_TRACE message-type constant.

Recommended content for trace messages

You are responsible for defining what kind of information your connector returns at each trace level. Table 55 shows the recommended content for application-specific connector trace messages.

Table 55. Content of application-specific connector trace messages
Level Content
0 Trace message that identifies the connector version. No other tracing is done at this level.
1 Trace messages that:
  • Log status messages and identifying (key) information for each business object processed.
  • Record each time the pollForEvents() method is executed.
2 Trace messages that:
  • Identify the business object handlers used for each object the connector processes.
  • Log each time a business object is posted to InterChange Server, either from gotApplEvent() or executeCollaboration().
  • Indicate each time a request business object is received.
3 Trace messages that:
  • Identify the foreign keys being processed (if applicable). These messages appear when the connector has encountered a foreign key in a business object or when the connector sets a foreign key in a business object.
  • Relate to business object processing. Examples of this include finding a match between business objects, or finding a business object in an array of child business objects.
4 Trace message that:
  • Identify application-specific information. Examples of this information include the values returned by the methods that process the application-specific information fields in business objects.
  • Identify when the connector enters or exits a function. These messages help trace the process flow of the connector.
  • Record any thread-specific processing. For example, if the connector spawns multiple threads, a message should log the creation of each new thread.
5 Trace message that:
  • Indicate connector initialization. Examples of this message include the value of each connector configuration property that has been retrieved from InterChange Server.
  • Detail the status of each thread the connector spawns while it is running.
  • Represent statements executed in the application. The connector log file contains all statements executed in the target application and the value of any variables that are substituted (where applicable).
  • Record business object dumps. The connector should output a text representation of a business object before it begins processing (showing the object the connector receives from the integration broker) and after it has processed the object (showing the object the connector returns to the integration broker).

Note:
The connector should deliver all the trace messages at the specified trace level and lower.

For information on the content and level of detail for connector framework trace messages, see the System Administration Guide in the IBM WebSphere InterChange Server documentation set.

Copyright IBM Corporation 1997, 2004. All Rights Reserved.