Tracing

Topics: Interacting With Log4J

Tracing is the key to diagnosing problems and thus to application reliability. iWay Service Manager provides a full complement of tracing services, oriented to diagnostic analysis of the running system.

Experience teaches that tracing can also be a major source of performance degradation. This comes primarily from the string processing needed to form meaningful trace messages. Before you build a message that has several parts, check the following method to determine if the trace message is emitted

logger.isTraceLevelEnabled()

where:

TraceLevel

Is the specified trace level.

If the trace message is not emitted, then there is little purpose to construct it. Too much tracing is as bad as too little. Messages with several values to assist the debugger are easier to work with than several small messages that may get separated on a trace display.

Line feeds and tabs can be included in messages to make them easier to understand. Never start or end a trace message with a tab or line feed.

Tracing in iSM-level servers has been changed from prior releases, although exits written to the older trace() method calls will continue to function. In iSM, trace calls mirror the calls used in other familiar tracing systems, although with distinctions.

In most Java applications, trace levels are hierarchical. Any specific level sets all "lower" levels. In a server, this is expected to run for extended periods of time. The plethora of trace messages that would be generated in such a case when attempting to isolate problems could be enormous. To this end, iWay uses a mechanism based on trace categories. As an example, setting the PARSE category on traces only parsing operations and does not imply that all debugging levels will be consequently set.

When exits are entered, the trace has been enabled for the desired settings. All exits extend a standard base, and this base is a logger. As a result, you do not need to specifically refer to a logger when making trace calls. The protected field logger is available should you wish to use it.

debug("this is a debug message")

and

logger.debug("this is a debug message")

are equivalent.

When coding a listener or emitter, you must specifically refer to the logger in your calls, as these objects do not themselves act as loggers.

All levels provide two calls:

For example, debug(String) and isDebugEnabled() are defined for the debug level.

At the error level, the additional call is provided:

Trace levels supported are:

• BIZERROR level shows error messages associated with processing a document. Rule violations are BIZERROR level. You should not use this level to report problems such as a missing jar or things relating to the environment.
• DATA level shows the incoming and outgoing documents as they pass to and from the protocol channel.
• DEBUG level reports data that is helpful for debugging situations. It shows logic that follows the path of a document. You should not trace too much at DEBUG level.
• DEEP is used for detailed logic tracing. Trace whatever you need to understand why the document processed as it did. Stack traces are reported by the system in DEEP level.
• ERROR level shows error messages relating to operation of the adapter. This level is always displayed.
• INFO provides messages you think the user always needs to see. The server traces almost no messages at INFO level.
• PARSE displays the internal operations of the many parsers in the server. For example, character by character lexical analysis for the function compiler or the XPATH compiler is displayed at this level.
• TREE shows the document as it enters and leaves the system in XML form. Intermediate processing as a document evolves is done at TREE level. iWay makes every attempt to avoid tracing secure information in trees being traced. This includes attempting to locate elements with password values and replacing those values with a fixed number of asterisks.
• WARN shows important information pertaining to some situation, but that does not fall into the category of an error.

In addition to control using the consoles, any trace level can be set on or off using the command window when the server is running as an executable process. The command

set level on|off

where the level specifies the level to be controlled, will turn on or off tracing.

Use set display to see what levels are enabled.