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:
- 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.
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.
