IBM BPM, V8.0.1, All platforms > Authoring services in Integration Designer > Services and service-related functions > Access external services with adapters > Configure and using adapters > IBM WebSphere Adapters > Adapter Toolkit > Implementing code from the IBM WebSphere Adapter Toolkit > Problem determination > Logging and tracing messages

Trace messages

Trace messages convey information that is intended for support teams and developers. Such information includes stack dumps for exceptions and operation logic for debugging purposes. Because trace messages are directed at the teams that wrote or support the adapter rather than customers, trace messages need not be translated and can, in fact, be hard-coded in the adapter.

Writing a trace message

You use the trace method of the LogUtils class to generate a trace message. This method has two signatures. One of them is informational. The other is associated with an exception.

void trace
   (Level l, String classname, String method, String msg)

void trace
   (Level l, String classname, String method, String msg, Exception ex)

In an outbound or inbound scenario, to get the LogUtils object instance, in IBM Integration Designer, Right click the method and select the following option:

• Source > Insert Trace Statement

In an outbound scenario, you can use the logger property as a consistent way to get a log object to write log or trace messages into log or trace files.

Trace messages might contain data from the customer's EIS. Because a customer might be unwilling to send a trace file that contains sensitive data to a support specialist for analysis, you can optionally use the traceConfidential method of the LogUtils class to write confidential trace messages whose EIS-specific content is replaced by a string of XXX's when the customer enables the HideConfidentialTrace property. Like the trace method, the traceConfidential method has two signatures. One of them is informational. The other is associated with an exception.

void traceConfidential
   (Level l, String classname, String method, String msg, Object[] confidentialData)

void traceConfidential
   (Level l, String classname, String method, String msg, Object[]
confidentialData, Exception e) 

Example of informational trace message

getLogUtils().trace
(Level.Fine, "EISSAResourceAdapter", "openConnect", "Successfully connected to EIS Simulator");

Example of exception trace message

getLogUtils().trace(Level.Finer, "EISSAResourceAdapter", "closeConnection", "While attempting to close the connection to EIS Simulator, EISS API reported that the server had already closed the connection previously due to inactivity. Ignoring because connection was closed all the same", EISSAPIException);

Example of trace message for the outbound scenario

public<AdapterPrefixName>ConnectionFactory(ConnectionManager connMgr, WBIManagedConnectionFactory mcf)
{
super(connMgr, mcf);
getLogUtils().trace(Level.FINE,"com.ibm.(AdapterPrefixName).outbound.
<AdapterPrefixName>ConnectionFactory", "<AdapterPrefixName>ConnectionFactory()", "test");}

Example of trace message for the inbound scenario

public javax.resource.cci.Record getRecordForEvent
(com.ibm.j2ca.extension.eventmanagement.Event event)
throws javax.resource.ResourceException, javax.resource.spi.CommException {
logger.trace(Level.FINE, "com.ibm.<AdapterPrefixName>inbound.<AdapterPrefixName>EventStoreWithXid", "getRecordForEvent()", "test");
return null;}}

Example of trace message for the outbound scenario with confidential tracing property enabled

public<AdapterPrefixName>ConnectionFactory(ConnectionManager connMgr, WBIManagedConnectionFactory mcf) {
super(connMgr, mcf);
getLogUtils().traceConfidential(Level.FINE, "com.ibm.<AdapterPrefixName>.outbound.<AdapterPrefixName>ConnectionFactory", "<AdapterPrefixName>ConnectionFactory()", "test", new Object[] { "str" });}

Example of trace message for the inbound scenario with confidential tracing property enabled

public javax.resource.cci.Record getRecordForEvent
(com.ibm.j2ca.extension.eventmanagement.Event event)
throws javax.resource.ResourceException, javax.resource.spi.CommException {
logger.traceConfidential(Level.FINE, "com.ibm.<AdapterPrefixName>.inbound.<AdapterPrefixName>EventStoreWithXid", "getRecordForEvent()", "test", new Object[] { "str" });
return null;}

In the previous code snippets, getLogUtils() and logger are instances of the LogUtils class.

Trace levels

Three trace levels allow users to adjust the level of detail. Consult the guidelines shown in the following table to determine which trace level to assign to a trace message.

Trace level indicators

Level	Indicator	Significance
Fine	1	This trace features the lowest level of detail. It includes broad actions taken by the adapter such as establishing a connection to the EIS, converting an event in the EIS to a business object (key values only), processing a business object (key values only).
Finer	2	This trace provides more detailed information about adapter logic, including API calls to the EIS and any parameters or return values.
Finest	3	This is the most detailed level and includes method entry, exit, and return values. Include complete business object dumps and all detail needed to debug problems.

Configure log and trace detail level

Set the trace level on the package that you want to trace to all in the Change Log Detail Levels field:

For example, if the adapter package name is com.ibm.myadapter, modify the Change Log Detail Levels pane and add com.ibm.myadapter.* = all."

Performance considerations

Tracing assists developers and troubleshooters. Due to the significant performance cost incurred by tracing, however, many customers disable it in production environments. When developing or troubleshooting, it is good practice to check whether tracing is enabled before building to generate trace messages. You can do this by checking method LogUtils.isTraceEnabled( java.util.logging.Level) before building the adapter. The following is an example:

if(logUtils.isTraceEnabled(Level.Fine) {
	   getLogUtils().trace(...);

Logging and tracing messages