![]() |
Copyright © TIBCO Software Inc. All Rights Reserved |
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 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.
− 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.
− If you are using Java, you may choose to output a Java properties file. In that case, load the properties file as follows:
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.
5.
6. In the custom adapter, call the MTrace method trace() with an MException or an error code. For example:}.
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.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.
Table 21 Predefined Roles Developer-defined tracing. During normal operating conditions, DEBUG should be turned off. Unrecoverable errors. The operation in which the error occurred is skipped. The adapter may continue with the next operation or may stop altogether. A significant processing step was reached. It is logged for tracking and auditing purposes. An abnormal condition was found. It does not prevent processing to be performed but special attention from an administrator is recommended.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:
• Send the same information to more than one sink. For example, send it to a file and publish it as a TIBCO Rendezvous message.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.
− MFileSink Messages are sent to file.
− MRvSink Messages are sent to TIBCO Rendezvous.
−
− MHawkSink Messages are sent to TIBCO Hawk, to the specified microagent method _onUnsolicitedMsg().
• Format a message string (printf() style).
1. The developer uses the TIBCO Designer software to define sinks and map each sink to one or more roles.
2.
a. Creates an MTrace instance.
b.
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.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.
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.
Table 22 Trace Message Fields 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.
Table 23 Trace Message Details 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. Note that in all data-related messages the trackingId should be traced. 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:
• the Generic Adapter Configuration is set up to support tracing to a log file named according to a variable;Figure 13 Configure TracingYou 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.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.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:
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.
1. In the Generic Adapter Configuration’s Logging tab, click Use Advanced Logging.
2. In the Advanced folder for the adapter, drag a File Sink into the design panel.
![]() |
Copyright © TIBCO Software Inc. All Rights Reserved |