Previous Contents DocHome Index Next |
iPlanet Trustbase Transaction Manager 2.2.1 Developer Guide |
Chapter 6 Error and Audit Logging
iPlanet Trustbase Transaction Manager provides a set of libraries for use with both error and audit logging. The default implementation of these libraries allow the framework and business components to store information within a relational database for use by external browsers and error management consoles.Both error and audit logs are controlled by a log manager. The log manager stores the data in an appropriate location depending upon its current configuration. This design provides a location independent mechanism for recording error and audit information, and allows components to be re-used between different iPlanet Trustbase Transaction Manager implementations. This log manager is activated each time iPlanet Trustbase Transaction Manager boots. Initially the configuration of the log manager is read from an initialisation file, but in subsequent boot sequences this is read from the persistent configuration object generated by the manager.
Overview
Figure 6-1    iPlanet Trustbase Transaction Manager log manager
The data to be logged by the log manager is supplied by the requesting component in the form of an error or audit log object. The log manager will check the type but not the content of the object being logged. The type checking involved ensures that the object passed is a sub-class of the iPlanet Trustbase Transaction Manager defined error log and audit log classes. This allows the developer to define new error and audit log types for use specifically by the solution e.g. Billing logs.
The Log manager is abstracted from the storage of the data by a Store API. This allows different implementations of a Log e.g. Billing information logs to be stored in different physical repositories, or particular log types e.g. Errors to generate events that are passed to Third Party monitoring systems.
Audit logs
Audit logs are generated at particular points in the lifetime of the iPlanet Trustbase Transaction Manager platform, specifically:These standard iPlanet Trustbase Transaction Manager audit log types are defined in the uk.co.jcp.tbaseimpl.log.audit.type package.
Audit Logging an Event
To cause an entry to be made in the iPlanet Trustbase Transaction Manager Audit Log, create a new instance of the AuditObject type that you wish to log (which must be a sub-type of uk.co.jcp.tbaseimpl.log.audit.AuditObject) and pass the instance to the static method AuditLog.log( ... ).An example of an Audit being logged is shown below
The three parameters supplied to construct all AuditObjects are as follows:
this.getClass()
As mentioned above, there needs to be an AuditBundle file on the class path and registered with the bundle manager (see Defining New Audit Types section) so that the actual audit message can be looked up. For the example above there would be a file AuditBundle.properties created in ..../com/iplanet/trustbase/app which contained the following line:
The first parameter is a class object, whose name will be used as the first part of the internationalisation bundle key for the message. This is normally the class that is logging the audit, to make it easy to relate audit messages to packages. But this may be any class object.SERVICE_STARTED
This is any string which when concatenated with the class name provides a unique bundle key to locate the text of the message for audit purposes. See below for a description of the AuditBundle keys and values.new String[] { serviceName.toString() }
This is an array of strings which are parameters that are combined with the AuditBundle message using the standard java.text.MessageFormat class to provide the final audit message.
com.iplanet.trustbase.app.DummyService_START=The service {0} has begun. This is the fully qualified class name provided by the 'this.getClass()' parameter followed by a '_' character, followed by the SERVICE_STARTED string.
The message that would be associated with this audit would be 'The service {0} has begun.' Where the java.text.MessageFormat class will replace '{0}' with entry 0 in the String array passed to the audit constructor.
Defining New Audit Types
The developer may define new audit log types to allow application or domain specific messages. These must be a sub-class of the uk.co.jcp.tbaseimpl.log.audit.AuditObject class.The most common use of these extended audit types is to log information about messages processed by the iPlanet Trustbase Transaction Manager Service.
Having implemented the new Audit type, the following steps must be completed in order to get the audit type to appear in the standard iPlanet Trustbase Transaction Manager Audit log.
Create the new Audit class and put it into the JAR file for the service that will utilise the Audit. More details of deploying an iPlanet Trustbase Transaction Manager service can be found in later chapters.
An example of an AuditObject implementation is shown below:Create the relevant resource bundles for the audit messages. In order to allow simple localisation of messages into various languages, all audit type strings that appear in the iPlanet Trustbase Transaction Manager audit log are defined in resource bundles. These bundles are located in the same package (i.e. same directory) as the new AuditType class. The format of the name of this resource bundle must be the same as that defined by the standard Java java.util.ResourceBundle class. The format of the bundle is a series of name/value pairs. Where the name is constructed as fully-qualified-audit-type-classname_bundleKey, and the value is the String which should be placed in the AuditType field of the Audit Log.
Create an entry in tbase.properties to register the new Audit Resource Bundle. To do this, add an entry in the section [BundleProviderManager/Audit] that references the fully qualified name of the new Audit Resource Bundle.
Finally enable the new Audit Type in tbase.properties by adding an entry in the following section [uk.co.jcp.tbaseimpl.log.present.audit.AuditLogPresentationConfigService] for each of the new Audit Type classes defined by the service.
Restart iPlanet Trustbase Transaction Manager to activate the new Audit Types, this is required to enable a new service and is therefore not an action normally associated with new Audit Types.
The following file defines the Resource bundle and is located in the package hierarchy in the same place as the OperationBeginAudit class and will be called TheNewAuditBundle_en.properties.
uk.co.jcp.tbaseimpl.log.audit.type.OperationBeginAudit_OPERATION_BEGIN = OPERATION_BEGIN The new bundle is registered in tbase.properties with the following entry, note how the locale extension '_en' is not used in the bundle registration and the .properties extension is not required - this is in line with the standard Java java.util.ResourceBundle class:
[BundleProviderManager/Audit]
bundle=uk.co.jcp.tbaseimpl.log.audit.type.TheNewAuditBundleThe new Audit type is enabled by adding the following entry into tbase.properties.
[uk.co.jcp.tbaseimpl.log.present.audit.AuditLogPresentationConfigS ervice]
auditlog.type.enabled=uk.co.jcp.tbaseimpl.log.audit.type.Operation BeginAudit
Error handling and logging
Errors that occur in the iPlanet Trustbase Transaction Manager platform fall into two categories:
Logic errors - Something about the data or processing is incorrect and the processing needs to reject a request gracefully.
In both cases, iPlanet Trustbase Transaction Manager will use the Log manager to record that an error has occurred so that operational staff may perform appropriate analysis and corrective action.Exceptions - An unexpected condition has occurred, that breaks the processing logic
Error Logging
iPlanet Trustbase Transaction Manager uses a single error log class that takes a severity, the class of object defining the error, and a programmer defined message, plus a set or zero or more string arguments which may be substituted into the message. The default error logging implementation, uk.co.jcp.tbaseimpl.log.error.ErrorLog, defines four constants that indicate the various severity levels:
Table 6-1    Error Severity Types
Note The API classes associated with Error Logging are uk.co.jcp.tbaseimpl.log.error.ErrorLog, uk.co.jcp.tbaseimpl.log.error.ErrorObject.
Logging an error from within iPlanet Trustbase Transaction Manager is as simple as calling ErrorLog.log( .... ) with an instance of an ErrorObject. There are many constructors for ErrorObject, but all of them have at least a string parameter that identifies the unique error code for this error.
The iPlanet Trustbase Transaction Manager error logging mechanism requires that every different occurrence of an error be given a code which unique throughout iPlanet Trustbase Transaction Manager. All of the error information for the Error Logging sub-system in iPlanet Trustbase Transaction Manager is contained in the following database tables:
All unique error codes have their details stored in Table 6-2:
Table 6-2    Error_codes
The actual error log table is described below, this table is not normally viewed by the administrator directly, instead there is an Oracle view called errorview that provides a resolved view of the errors that have been logged.
Table 6-3    Error
Error table
This is a unique id for the error log entry; it is generated from a monotonic sequence that means that this field may be used to accurately order error messages in the order that they were logged.
This is the errorcode of the error being logged, see the error_codes table description.
The final message string that is generated from the message string in the error_codes table combined with the variable parameters from the runtime system substituted in.
This is an ORACLE DateTime field that identifies when the error was logged.
This is the severity integer that is taken from the error_codes entry for this error.
This is a string representing the IP address of the iPlanet Trustbase Transaction Manager that logged the error - this may be different in a multi-node IAS installation.
When an error is logged it is often accompanied by some free form string data which helps to store the context in which the error occurred to aid diagnosis. The most common example of such data is exception stack traces.
Table 6-4    Error Support
error_support table
This links this entry to an entry in the Error table
This datatype is an arbitrary string identifier that categorises the data in the data field. The only value for this field defined by iPlanet Trustbase Transaction Manager is "STACKTRACE" which identifies the contents of the data field to be a Java Exception Stack Trace.
The tables described above encapsulate the whole data driven error logging mechanism that iPlanet Trustbase Transaction Manager supports.
Defining a New Error
Defining a new error is very simple; it involves making a new entry in the error_codes table. There are currently no tools to support this operation, but it may be accomplished through the use of basic SQL. The only consideration is that the error_code field must be unique - this is enforced by an ORACLE level table constraint, so if the new code is inserted without error then the code is unique.A sample error code is inserted using the SQL defined below:
INSERT INTO error_codes values
(
'TST0001',
'com.iplanet.trustbase.sample.service',
'1',
'This is the only exception in the test service'
);This error may then be logged using the following piece of code:
.....
}
catch (Exception exc)
{
ErrorLog.log( new ErrorObject( "TST0001", exc );
}
.....This will result in an entry being made in the error table as well as the related stack trace being logged in the error_support table.
Exception Handling
Exception handling, as with the logging of logical errors, should also log information before the appropriate exception is thrown, in order to enable users and developers of the system to analyse the situation that caused them to arise.The iPlanet Trustbase Transaction Manager exception hierarchy is designed to allow the various components to throw exceptions back to their calling component without the calling component having to explicitly include handling code. This is achieved by having each successive 'level' of exceptions (as related to each successive 'level' of the code) derive from the previous level. For instance consider the example of a service throwing an exception derived from ServiceException. If the service does not explicitly handle the exception it will be passed back to the Router (as the calling component), and because ServiceException is derived from RoutingException we can expect the router to be able to handle the exception gracefully.
Figure 6-2    iPlanet Trustbase Transaction Manager Exception Hierarchy
It is imperative that developers of extension to the system maintain this hierarchical approach to exception inheritance in order that the handling code built into the current iPlanet Trustbase Transaction Manager system will function correctly.
The hierarchical nature of the iPlanet Trustbase Transaction Manager exceptions allows the exception handling to be done differently depending upon where the exception occurs. The components and the associated actions performed are shown in Table 6-5:
Table 6-5    Exceptions
Previous Contents DocHome Index Next
Copyright © 2001 Sun Microsystems, Inc. Some preexisting portions Copyright © 2001 Netscape Communications Corp. All rights reserved.
Last Updated April 19, 2001