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 |
- 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.
|
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:
- To File: The absolute pathname of an external file, which must
reside on the same machine as the connector's process (with its
connector framework and application-specific component)
- To console (STDOUT): The command prompt window generated when
the connector startup script
starts the connector
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.
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.
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.
