Copyright © TIBCO Software Inc. All Rights Reserved
Copyright © TIBCO Software Inc. All Rights Reserved


Chapter 5 Tracing, Tracking, and Exception Handling : Tracing

Tracing
Traces are useful both during development (debugging messages) and after the custom adapter has been deployed (error and information messages).
The SDK allows custom adapters to store error message information in a separate file. In the file, each message includes a number of elements, such as the message code, the message role and category, and the message symbol. The custom adapter program uses the message symbol, and the SDK maps the symbol to the message in the file to send out a complete message to the desired location. Storing error messages separate from the actual custom adapter program makes it easier to localize the adapter to a specific language locale.
This section discusses the following topics:
Using Tracing Facilities
This section gives an overview of how to implement tracing in a custom adapter. Some of the example programs included in the TIBCO Adapter SDK (for example, zapadapter) use this approach.
1.
In TIBCO Designer, specify the sinks you want to have available and their associated roles. See the TIBCO Designer Palette Reference for more information.
2.
Prepare an XML file containing elements for each message you expect to use. See Sample XML Message Element. Include a role for each message element. You can use one of the predefined roles or a user-defined role. See Available Tracing Roles.
3.
Process the XML file using the genAeErrors utility (in the SDK_HOME/resourceKit directory).
The utility can have two possible outputs:
Source files that can then be included in the project. This can be either a .cpp and a .h file or a .java file. The output files contain an MMessageBundle and an InitializeMessages definition.
 
      MMessageBundle.addResourceBundle("ZAP","ZAP_Messages");
See the example program for details.
The output file includes a message symbol, which is then to be used in your code. When later call trace() with the message symbol as an argument, all other message elements are used in the trace.
4.
Be sure to call the InitializeMessages() static method in the onInitialization() method in MApp.
5.
During initialization, MApp creates an instance of MTrace that you can retrieve as follows:
C++
   MTrace *pMTrace = pMapp->getTrace();
Java
   MTrace trace = mapp.getTrace();
 
6.
In the custom adapter, call the MTrace method trace() with an MException or an error code. For example:
C++
//.....
pTrace->trace( "ZAP_ERR_NO_CONNECTION", NULL, NULL );
Java
try {
//...
} catch (MException ex) {
MTrace.trace("ZAP_ERR_NO_CONNECTION", ex, null);
}.
It is recommended that you use the genAeErrors utility and the InitializeMessages method instead of creating the MMessageBundle explicitly and adding messages. See the API documentation for more information.
7.
At runtime, the SDK looks up the message corresponding to the message symbol used in the trace() call and sends the complete trace message to the appropriate sink.
See the TIBCO Adapter SDK Satus Codes for a complete list of predefined messages and codes. You may create additional XML files with message codes and related information for the custom adapter.
Available Tracing Roles
The SDK predefines the roles listed in Table 21. In addition, user-defined roles are supported. For instructions on creating user-defined roles, refer to the TIBCO Designer Palette Reference.
Unrecoverable errors. The operation in which the error occurred is skipped. The adapter may continue with the next operation or may stop altogether.
An abnormal condition was found. It does not prevent processing to be performed but special attention from an administrator is recommended.
Multiple Traces and Sinks
With multiple roles and sinks, the output information level can be tuned via modifications to the adapter instance definition. Because each sink receives trace messages corresponding to its assigned role, you can do the following:
Combinations of sinks and roles are specified using TIBCO Designer.
In Figure 12, all error trace messages go to Sink4 and Sink3; all warning messages go to Sink4; all debug messages go to Sink1 and Sink3; and all info trace messages go to Sink1 and Sink2.
Figure 12 Assigning Different Trace Messages to Different Sinks
MTrace and MSink
The two SDK classes MTrace and MSink offer the following services:
MFileSink  Messages are sent to file.
MRvSink  Messages are sent to TIBCO Rendezvous.
MStdioSink  Messages are sent to a user-provided file; usually stderr or stdout.
MHawkSink  Messages are sent to TIBCO Hawk, to the specified microagent method _onUnsolicitedMsg().
The SDK implements trace message handling as follows:
1.
2.
When a custom adapter calls the MApp method start(), MApp prepares for tracing as follows:
a.
Creates an MTrace instance.
b.
Attaches the MTrace to the MApp from which it was called.
c.
d.
Maps trace roles and sinks. Roles group trace messages so related messages can then be examined in one place. There are system-defined roles (error, information, etc.) or you can use a user-defined role.
3.
Each time the custom adapter calls one of the MTrace tracing methods, a role is implicitly specified via the error code that is passed in.
4.
See File Sink Management for information on naming and potential deletion of log files.
Sample XML Message Element
The following message element illustrates how to specify messages inside the trace message XML file.
The XML file is compiled into source files or a Java property file when you run the genAeErrors utility. At runtime, the compiled message is accessed to map from the message code to other message information so the whole trace message can be displayed, sent to the log, etc.

 
<message>
<messageCode>AESDKC-0041</messageCode>
<messageSymbol>M_ERR_CANNOT_FIND_PREFIX</messageSymbol>
<role>errorRole</role>
<category>SerializerCategory:
<description>Deserialization failed to find prefix in Idx list
            </description>
<longDescription/>
<resolution>Deserialization was attempted on an MTree that does
         not contain necessary metadata prefix list information. Either correct
         the sending application or do not attempt to deserialize this MTree (it
         may not have been packed by an SDK-based application)</resolution>
</message>

 
Trace Message Format
In preparation for running a custom adapter, prepare an XML file that matches error codes with other error information. See Sample XML Message Element. Then launch the genAeErrors tool, which generates sources or resource bundles from the XML file.
The message is typically extracted from the MMessageBundle object at runtime. A substitution might occur in a reference field using Error description to fill the field. This ensures each error definition originates from one, and only one, source.
In the log file, each message has the same format, derived from the tracing facility. Table 22 lists each field and corresponding examples.
zap.inst1 (The default applicationId format is <appName.instanceID>)
<tracking information>
Here is an example of a single trace message:
2000 Sep 12 18:13:26:373 zap.inst1 Error [TibrvComm] AESDKJ-000237 AE Operation Request timeout tracking= #<trackingID>#<info1>#<info2>#<info3>#
Table 23 gives details for each field in the trace message.
Name of the product where the error is raised. A combination of the SDK application name and instanceID is appropriate and used by default.
Role of the trace message. See Available Tracing Roles for a definition of the following predefined roles: ERROR, WARN, INFO, and DEBUG.
Not required for DEBUG messages.
Standard categories: Application, Component,Configuration, Database, JMSComm, Marshaller, Metadata, Properties, Rpc, Serializer, TibRvComm, Unicode, Utility, XML
Not required for DEBUG messages.
Application-specific information added to the tracking info to trace the message back to its source. Set initially by the source and carried forward, it is augmented by each intermediate component.
For adapters, ApplicationInfo should be in the following form:
Configuring Tracing Using TIBCO Designer
This section demonstrates how to configure tracing using TIBCO Designer.
By default:
Figure 13 Configure Tracing
You can change the default tracing by selecting or clearing the check boxes in the Logging tab of the Generic Adapter Configuration. You can also change the name of the log file.
For any other changes, for example, for additional sinks, select the Use Advanced Logging check box.
Advanced Logging
With the Use Advanced Logging check box selected, you can create additional sinks or change the default sinks from inside the Advanced folder’s Log Sinks folder.
See the TIBCO Designer Palette Reference for more information.
File Sink Management
In most cases, custom adapters specify a file sink in the adapter configuration, which includes File Limit and File Count attributes. The SDK uses this information as follows:
1.
2.
3.
When File Limit is reached, the SDK renames the current file to file.1 and creates a new file with no extension.
Note that the log file may be slightly larger than the limit because the new file is only created after the limit has been reached.
4.
The SDK repeats this process, renaming all files each time a new file is generated, until it reaches the number of files specified in File Count.
The adapter overwrites the file with the lowest number, that is, the oldest file, when the number of files reaches File Count and that last file reaches File Limit. To avoid that, set either File Count or File Limit to a sufficiently large value.
Setting File Sink Information
To set non-default File Sink information in TIBCO Designer:
1.
2.
In the Advanced folder for the adapter, drag a File Sink into the design panel.
3.

Copyright © TIBCO Software Inc. All Rights Reserved
Copyright © TIBCO Software Inc. All Rights Reserved