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
Providing information about the runtime state of the adapter is a critical aspect of adapter development. The Adapter Foundation Classes include the LogUtils class. When implemented, this functionality enables developers to target information to various user roles, enabling them to filter information by levels of importance and to generate informational events that can be monitored by and acted upon by IBM BPM.
Information about the runtime state of the adapter is invaluable not only to support teams trying to resolve problems but also to users looking to monitor the adapter and track its operations. For these reasons, you should focus early in your adapter development process on what information to provide, which users to target, and how to most efficiently and clearly communicate the information.
The JCA 1.5 specification provides minimal support for communicating information to users. It defines a single stream to which the adapter writes any information. As a result, without additional tools or support, users cannot filter information, analyze information or, in general, easily determine what information is of interest to them.
The New Adapter wizard generates code skeleton using Adapter Foundation Classes to provide you with a consistent method to get the LogUtils object in your own implementation. This is very useful when an adapter wants to record business information or needs to track execution flow. The LogUtils class allows you to direct information usefully to various users by generating three types of "messages": trace, log, and event messages. Each has a distinct purpose and conveys different information.
- The following guidelines apply to trace messages:
- They do not contain information needed by general users to resolve problems
- They encapsulate information intended for support and other development teams
- They need not be translated
- They can be hard-coded in the adapter itself
- They feature three levels of detail: fine, finer, and finest
- The following guidelines apply to log messages:
- They encapsulate information such as warnings and errors that are targeted at general users of the adapter
- Rather than hard-code log messages in the adapter, place them in a separate log message file to facilitate translation in to localized languages
- They feature multiple levels that users can employ to filter log messages
- The following guidelines apply to event messages:
- They provide information about the state of the adapter for use by monitor tooling
- Represented as common base event data at run time, event messages can be included in the extended LogUtils.log method signatures
Support for protecting sensitive user data in log and trace files
WebSphere Adapter Toolkit provides support for confidential tracing of properties. This means that when you decide whether a property might contain potentially sensitive data then use a special interface to record that information in a log or trace message. Data recorded with the special interface is displayed in the logs by a "XXXX". This functionality is most useful to customers who mainly deal with numerous confidential information such as banks, healthcare companies and defense. This property is a part of the Adapter Foundation Classes, and so it can be used by any adapters.
When a property is marked as confidential and if it needs to be logged or traced, then you record the information using a special confidential log and trace method provided in the logUtils will be invoked.
The following types of information are considered potentially sensitive data and will be hidden:
- The contents of a business object
- The contents of the object key of the event record
- User names, Password, Environment, and Role
- The URL used to connect to the Enterprise Information System (EIS)
The following types of information are not considered potentially sensitive data and will not be hidden:
- The contents of the event record that are not part of the event record object key.
For example, the transactionID ( XID), event ID, business object name, and event status
- Business object schemas
- Call sequences
Inserting log and trace messages
The WebSphere Adapter Toolkit automatically provides entry and exit tracing statements to the generated code, excluding constructors and accessor methods. The WebSphere Adapter Toolkit does not add logging and tracing statements to the generated code for a JCA resource adapter. You will not be able to manually add logging and tracing to the generated JCA adapter code.
You can insert log or trace statements into your generated IBM WebSphere adapter code using a dialog box that collects information about the log or trace statement to be generated and insert the appropriate code at the cursor position.
- 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.- 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.