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.
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 |
---|
|
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 configuration property TraceFileName as one of the following:
By default, TraceFileName is set to STDOUT, to indicate use of the startup script's command prompt window as the trace destination. You set this connector configuration property to the trace destination appropriate for your connector.
Table 48 shows the ways that a connector sends a trace message to its
trace destination.
Table 48. Methods for sending a trace message to the trace destination
For information on the generateMsg() method, see "Generating a message string".
In the C++ connector library, the traceWrite(), generateMsg(), and generateAndTraceMsg() methods are defined in two classes:
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 LEVELn where n can be a trace level from 1 to 5. Trace-level constants are defined in the Tracing class.
The C++ code fragment below uses traceWrite() to write a level 4 trace message to log the number of records retrieved from the application.
sprintf(msg, "Fetched %d record(s).", rCount); traceWrite(Tracing::LEVEL4, msg, NULL);
The trace message written to the trace destination contains the date, time, connector name, and message, as shown by the output of this code sample:
[1999/05/28 12.36:48.105] [ConnectorAgent MyConnector] Trace: Fetched 2 record(s).
Both the generateMsg() and generateAndTraceMsg() methods require 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 CxMsgFormat class.
You are responsible for defining what kind of information your connector
returns at each
trace level. Table 49 shows the recommended content for application-specific
connector trace messages.
Table 49. Content of application-specific connector trace messages
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.