Log messages

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
Log messages

Log messages convey timely information intended for consumption by customers: warnings about potential problems, errors that have occurred and suggested fixes for those errors, and information that is necessary or helpful to understanding how the adapter operates.

Message files

To facilitate translation of log messages for different user groups, place all log messages in a resource bundle file rather than hard-code them in the adapter itself. The convention for packaging this bundle file is to embed it in the adapter RAR as <adapter package>.emd/logMessages.properties.
The message file can contain one or more messages. Each message should consists these three parts:

Message Identifier – The message ID follows the format NNNNNmmmmS, where NNNNN is a five-letter component prefix, mmmm is the message number, and S identifies the message type.
For example, a message identifier such as ABCDE0001E has a component identifier of ABCDE and a message number of 0001. The message type E tells you this is an error message. The component identifier must be registered with IBM to avoid conflicts between products. The type identifier should conform to one of the values specified in the Log Level table shown below. The message number is left to you.
Explanation – The explanation provides an in-depth description of the message. Assume that the customer is unfamiliar with the meaning of the base message. The explanation is the first level of help documentation for users, not a crutch for a poorly written base message.
User Action – For every explanation of what went wrong, typically there are actions that customers can take to rectify the situation or to ensure that it doesn't happen again. The User Action field provides detailed information about what customers can do and is very much like first-level help documentation.

The following is an example of a message file:
0001=CWYBS0001I: Adapter {1} started.
0001.explanation=The adapter has successfully initialized 
 and is now ready to service requests.
0001.useraction=

0004=CWYBS9999E: Failed to establish connection link to 
server on host {1}.
0004.explanation=The adapter is unable to contact
the backend application.  
Business data cannot be exchanged with the backend until this issue is resolved.  
0004.useraction= Check your adapter configuration and ensure 
that the specified host and port match the machine and port 
on which the backend is listening. If correct, check that your 
backend application is on-line and accepting requests.  
Message types

There are two message types for adapters, ADAPTER_RBUNDLE and BASE_RBUNDLE. The BASE_RBUNDLE is reserved for the Adapter Foundation Classes. The message types are used to distinguish between the adapter and the base classes message file. The default value of Message Type field is ADAPTER_RBUNDLE. You use only the ADAPTER_RBUNDLE message type because you should only access adapter message file.

Log levels

Log Levels and indicators

Level Indicator Significance
Fatal F Task cannot continue. Component cannot function
Severe E Task cannot continue. Component can still function. This can also indicate an impending unrecoverable error, including situations that strongly suggest that resources are on the verge of being depleted.
Warning W Potential error or impending error. This includes conditions that indicate a progressive failure - for example, the potential leaking of resources.
Audit A Significant event affecting server state or resources
Info I General information outlining overall task progress.

Writing a log message

Use the log method of the LogUtils class to generate log messages. This method accepts parameters similar to that of the trace file. Instead of providing a hard-coded message, however, provide a key to the message from the log message file. This log method can also take optional parameters if there are values to be substituted in the message.
void log   (Level l, int bundleType, String classname, 
	String method, String msgKey)

void log   (Level l, int bundleType , String classname, 
	String method, String msgKey, 
   Object[] params)
For example, if you have defined parameters in your log message such as "Successfully processed business object {1} with id {2}", you would provide values for those parameters using the argument params[].
Since parameters are not translated, avoid passing hard-coded phrases as parameters because the resulting message will be a combination of English and translated text. Values that are language-independent, such as key values or object names, are appropriate as log message parameters.
Similarly to trace messages, parameters in a log message can contain data from the customer's EIS. Because a customer might be unwilling to send a log file that contains sensitive data to a support specialist for analysis, you can optionally use the logConfidential method of the LogUtils class to generate confidential log messages whose EIS-specific content is replaced by a string of XXX's when the customer enables the HideConfidentialTrace property. Like the log method, the logConfidential method accepts parameters similar to that of the trace file. Instead of providing a hard-coded message, however, provide a key to the message from the log message file. The logConfidential method can also take optional parameters if there are values to be substituted in the message.
void logConfidential
  (Level l, int bundleType, String classname, String method, 
	String msgKey, Object[] params)

void logConfidential
  (Level l, String classname, String method, String msgKey, 
	CBEEngineData engine)

void logConfidential
  (Level l, String classname, String method, String msgKey, 
	Object[] params)

void logConfidential
  (Level l, String classname, String method,String msgKey, 
	Object[] params,CBEEngineData engineData)
In an outbound or inbound scenario, to get the LogUtils object instance, in IBM Integration Designer. Right click the method and select the Source Insert Log Statement option:.

Example of log message for the outbound scenario
public HelloWorldConnectionFactory(ConnectionManager connMgr, 
WBIManagedConnectionFactory mcf) {
		super(connMgr, mcf);
		getLogUtils().log(Level.INFO, LogUtilConstants.ADAPTER_RBUNDLE, 				"com.ibm.helloworld.outbound.HelloWorldConnectionFactory", 				"HelloWorldConnectionFactory()", "10");		
	      }
Example of log 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.log(Level.INFO, LogUtilConstants.ADAPTER_RBUNDLE, 				"com.ibm.helloworld.inbound.HelloWorldEventStoreWithXid", 				"getRecordForEvent()", "10");
		return null;
	}
Example of log message for the outbound scenario with confidential tracing property enabled
public HelloWorldConnectionFactory(ConnectionManager connMgr, WBIManagedConnectionFactory mcf) {
		super(connMgr, mcf);
		getLogUtils().logConfidential(Level.INFO, 				LogUtilConstants.ADAPTER_RBUNDLE, 				"com.ibm.helloworld.outbound.HelloWorldConnectionFactory", 				"HelloWorldConnectionFactory()", 				"10", new Object[] { "str" });		
	}
Example of log 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.logConfidential(Level.INFO, 
		LogUtilConstants.ADAPTER_RBUNDLE, 				"com.ibm.helloworld.inbound.HelloWorldEventStoreWithXid", 				"getRecordForEvent()", 				 "10", new Object[] { "test" });
	    			return null;
	}
In the previous code snippets, getLogUtils() and logger are instances of the LogUtils class.

Logging and tracing messages

Level	Indicator	Significance
Fatal	F	Task cannot continue. Component cannot function
Severe	E	Task cannot continue. Component can still function. This can also indicate an impending unrecoverable error, including situations that strongly suggest that resources are on the verge of being depleted.
Warning	W	Potential error or impending error. This includes conditions that indicate a progressive failure - for example, the potential leaking of resources.
Audit	A	Significant event affecting server state or resources
Info	I	General information outlining overall task progress.