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.
