Chapter 6   iTTM Logging: Error, Audit and Raw


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:

• Service start up events

• Service shutdown events, both normal and abnormal

• All configuration changes

• All security domain changes

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

package com.iplanet.trustbase.app; public class DummyService { ...... private static final String SERVICE_STARTED = "START"; // Audit the occurrence of this event in the Audit Log AuditLog.log(new OperationBeginAudit( this.getClass(), SERVICE_STARTED, new String[]{ serviceName.toString() }); ...... }

The three parameters supplied to construct all AuditObjects are as follows:

• this.getClass()
  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.

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:

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.

---

Note	The API classes associated with Audit Logging are uk.co.jcp.tbaseimpl.log.audit.AuditLog, uk.co.jcp.tbaseimpl.log.audit.AuditObject and a number of standard concrete Audit Classes in uk.co.jcp.tbaseimpl.log.audit.type.

---

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.

• 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.

An example of an AuditObject implementation is shown below:

package uk.co.jcp.tbaseimpl.log.audit.type; import uk.co.jcp.tbaseimpl.log.audit.*; /** This class represents an audit object for recording that an operation has begun */ public class OperationBeginAudit extends AuditObject {       public OperationBeginAudit ( Class auditClass , String bundleKey , String [] params )       {          super ( auditClass , bundleKey , params );       }       public static String getAuditTypeString()       {          // The bundleKey is added to this class name to determine the          // actual string to be writteninto the AuditType field of the log          String bundleKey = "OPERATION_BEGIN";          return uk.co.jcp.tbaseimpl.log.audit.AuditObject.getAuditTypeString ( uk.co.jcp.tbaseimpl.log.audit.type.OperationBeginAudit.class, bundleKey );          } }

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.TheNewAuditBundle

The 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.

• Exceptions - An unexpected condition has occurred, that breaks the processing logic

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.

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

Constant	Description
INFORMATION	This constant is to be used to log informational events, such as unlikely sections of code being executed that are not necessarily errors - this should be used sparingly. This has a value of 0.
WARNING	This constant is to be used for error conditions that are expected and handled, but require logging for behaviour analysis. This has a value of 1.
ERROR	This constant is to be used for serious errors which indicate that something is inherently incorrect with the system or the information it contains, but that allow processing to continue, or be retried. This has a value of 2.
FATAL	This constant is to be used for fatal errors from which processing cannot recover, these errors would result in the abandoning of processing. This has a value of 3.

---

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

error_codes table
errorcode	This is the unique errorcode string that identifies the error; this must be 7 characters exactly. The normal for an error code is XXXnnnn. Where XXX is a three-letter code for the service or subsystem and nnnn is a unique number. e.g. IPH0009 is an error in the Identrus Protocol Handler.
classname	The class from which this error is logged. This places a constraint that each error code may only be used from one place.
severity	This is the severity level of the error, described previously. Constants for each of the error severities can be located in the uk.co.jcp.tbaseimpl.log.error.ErrorLog class.
message	This is the localised version of the error message that will appear in the error log. Parameters may be used in this message as described by the standard Java class java.text.MessageFormat. The values to be placed in these parameters are passed in an array of strings that one of the ErrorObject constructors allows.

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
errorid	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.
errorcode	This is the errorcode of the error being logged, see the error_codes table description.
message	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.
timestamp	This is an ORACLE DateTime field that identifies when the error was logged.
severity	This is the severity integer that is taken from the error_codes entry for this error.
classname	This is the classname that logged the error.
machineid	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.
contextid	This context id field is for future expansion.

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
errorid	This links this entry to an entry in the Error table
datatype	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.
data	Free form string data

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

Component	Base Exception	Actions
Servlet	TbaseRuntimeException	Catches TbaseRuntimeExceptions and generates the appropriate HTTP error
Protocol Analyser	ProtocolAnalyserException	may throw ParseException which will result in an HTTP error in the servlet
Message Analyser	MessageAnalyserException	Generated if a RemoteException has occurred, will result in an HTTP error in the servlet.
Message Readers	MessageReaderException	Is caught in the MessageAnalyser if it contains an embedded Message, then that Message is processed, otherwise the exception is propagated through to the servlet.
Message Writers	MessageWriterException	Is propagated back through the MessageAnalyser to the servlet that returns an HTTP error.
Router	RoutingException	Is propagated back through the MessageAnalyser to the servlet that returns an HTTP error
Services	ServiceException	May or may not contain a message, and is propagated back through the router to the MessageAnalyser where it is handled in the same fashion as the MessageReaderException

Raw Logging

The iPlanet Trustbase Transaction Manager provides a facility for logging the raw data comprising an applications inbound and outbound messages. Separate logs are maintained for each application that requires raw logging, and these logs are currently held in database tables. Logs may [ optionally ] be digitally signed, to make tampering with the logged data after-the-fact difficult.

The iPlanet Trustbase Transaction Manager is configured, by default, with a single raw log for Identrus data. In combination with the Identrus log, this meets the requirements for logging in an Identrus Transaction Coordinator.

An application which requires raw logging facilities must use it's own raw log, which is created with the AddLoggerWizard. The AddLoggerWizard creates the appropriate database tables and associates them in iPlanetTrustbase Transaction Manager configuration with a name : the raw log store name. An application can thereafter store data in the new raw log by referring to it by that name, as this simple example shows:

/*

* MY_MIME_TYPE - is the mime type of your message. This is

* present only for historical purposes.

* rawxml - the XML String comprising raw message data

* storename - is the name of raw log store you wish to log to.

*/

MessageLogger mlg = SingletonMessageLoggerManager.getMessageLogger ( MY_MIME_TYPE );

MessageElements me = new MessageElements ( );

   me.put( MessageElements.RAW_DATA, rawxml );

/** the returned Vector of Strings will only contain a single String, which

* is the recordid field of the logged record, and can be used as a foreign key for

* logging further application specific data which refers to the raw data */

Vector ids = mlg.log ( storeName , rawxml );

The result of the log operation is a String identifier [ contained in a Vector for historical reasons ], which is the value of the recordid field in the database record created. This identifier can be used as a foreign key in an application specific log table, permitting the application specific log to refer to the raw log.

The raw log inserts a row into a relational database table for each log operation. The structure of the database table is described here. All raw log tables have the same structure, although each raw log uses a different table, whose name is determined when the raw log is created with the AddLoggerWizard.

The raw logging facility records raw incoming and outbound message data.

Table 6-6    Raw log

raw_data table
Sessionid	The id of the raw log session that wrote this record
Logconnectionid	The id of the connection within the session
Recordid	The id of the record within the connection
recordmarker	A unique monotonically increasing identifier
timestamp	An integer which represents the UNIX time at which the record was logged.
rawdata	The Identrus Message XML, without the CertBundle fields. The certificates from the bundle are logged separately in the "cert_data_table"
digestofrecord	A SHA-1 digest of this record.
signeddigestofcalculation	An RSA signature of this record and data from the previous record.