Message Logger mediation primitive

Introduction

You can use the Message Logger mediation primitive to store messages in a relational database, or in other storage mediums if you use the custom logging functionality. The Message Logger mediation primitive logs messages to a relational database using an IBM-defined database schema (table structure). It can write to other storage mediums, such as flat files, through the use of the custom logging facility.

The Message Logger mediation primitive logs an XML transcoded copy of the service message object (SMO). The default behavior is to log just the message payload but the mediation primitive can be configured to log the complete SMO, or a part of the SMO defined by an XPath expression. Along with the message contents the mediation primitive also logs a timestamp, the message identifier, the primitive instance name, the mediation module instance name and the SMO version number.

If you are using a relational database, the message that is logged is stored in a database column called: Message. The other data that is logged is stored in columns with an appropriate heading, as documented later in this topic.

The Message Logger mediation primitive has one input terminal (in), one output terminal (out) and one fail terminal (fail). The in terminal is wired to accept a message and the other terminals are wired to propagate a message. The input message triggers logging to a database, or though a custom logger; and if the logging is successful, the out terminal propagates the original message. If an exception occurs during the processing of the input message, the fail terminal propagates the original message, together with any exception information.

The custom logging implementation is based on the java.util.logging package.

Details

By default, the Message Logger mediation primitive acts as follows:

Logs to the CommonDB database, using the table MSGLOG. This table is placed under a schema qualifier that is determined by your database product. You can specify the default schema name during the profile creation, when you configure the database. You must use the correct default schema name for your type of database. Table 1 describes the structure of the Message Logger database table. For further information, see the runtime documentation.
Logs to the CommonDB database identified by the JNDI location jdbc/mediation/messageLog, and the run time environment creates a data source at jdbc/mediation/messageLog but points this data source to the CommonDB database. The CommonDB database has a JNDI location of: jdbc/WPSDB. The jdbc/mediation/messageLog data source is scoped at the same level as the jdbc/WPSDB data source.

Table 1. Message Logger database table structure
Database type	Default schema	Additional information
DB2 Universal	<dbUserId>
DB2 for z/OS	dbSchemaName	The database alias name, which is generally the same as dbUserId.
Oracle	<dbUserId>
SQL Server	dbo	dbo is the default schema name. `DatabaseMetaData::getUserName()` returns dbo for embedded drivers, and dbUserId for Microsoft drivers.

In summary, with version 6.1.2, and later, the default is for the Message Logger mediation primitive to use the CommonDB database and for the runtime environment to map the data source at jdbc/mediation/messageLog to the CommonDB database.

Migration (only applicable if using a relational database)

Before version 6.1.0, the Message Logger mediation primitive did not use the CommonDB database. Before version 6.1.0:

On distributed platforms, the default installation of the runtime product created a stand-alone application server, and a local Derby database and datasource. The local Derby database was called EsbLogMedDB. The Message Logger mediation primitive was configured to use this Derby database, by default.
On z/OS®, the installation of the runtime product created an application server, and a sample database and datasource. The Message Logger mediation primitive could be configured to use either a Derby or a DB2® database.

If you used the Message Logger mediation primitive before version 6.1.0, and move to version 6.1.x or above, any messages stored at the previous location remain at that location. If you want to maintain a single location for Message Logger messages you can take one of the following actions:

Manually move old data into the CommonDB database.
Continue using the previous database. If you want to use the previous location you must manually configure the required data source.

If your runtime environment has a mixed cell, where some nodes are version 6.1.0 or above and some nodes are below version 6.1.0, the nodes below version 6.1.0 behave in one of the following ways:

Continue storing message information in the database identified by their jdbc/mediation/messageLog data source.
Start storing message information in the database identified by their new jdbc/mediation/messageLog data source.

The action taken by the pre-6.1.0 nodes depends on whether the nodes are configured to reject, or accept, JNDI changes during the federation process. For further information on the federation of nodes, see the runtime documentation.

Usage

You can use the Message Logger mediation primitive to store messages that you process later. The logged messages can be used for various purposes. For example, you could use the logged messages for data mining, message replay or for auditing.

Because the data is logged as XML it can be processed by any XML-aware application. Many databases, including DB2, provide built-in capabilities to handle XML contained in a database column. You can also use XML processing code to manipulate the XML in your Formatter implementation class.

With a relational database

Your Message Logger mediation primitives can log to the following:

One database, which can be either the CommonDB database or another database.
Multiple schemas in one database, including the CommonDB database. Multiple schemas can be useful for z/OS, because there can be only one physical database throughout the z/OS system. Multiple schemas allow you to compartmentalize data held on one database. For example, you might have test data and production data on the same database, but under different schemas.
Multiple databases. Two or more Message Logger mediation primitives can log to different databases. For example, you might want to log to a DB2 database and an Oracle database.
- Because there can be only one physical database throughout a z/OS system, additional databases must exist on other systems. You could have other databases on any of the following systems: other z/OS systems, distributed systems.

With custom logging

Each Message Logger mediation primitive must have a Handler implementation class specified. If you have multiple Message Logger mediation primitives they can either use the same Handler implementation class or any number of appropriate Handler implementation classes. You can, optionally, provide Formatter implementation classes, Filter implementation classes, or both.

By default, the default Handler implementation class logs every message to a file stored in the system temporary directory as defined by the java.io.tmpdir system property, this is typically /tmp or /var/tmp on a Unix system and C:\Documents and Settings\<user>\Local Settings\Temp on a windows system. The file will be called MessageLog.log.

With the default value for the Literal property the call to MessageFormat.format(<LogRecord>.getMessage(), <LogRecord>.getParameters()) in the default Formatter implementation class means the following:

{0} would then be substituted with the Time Stamp value - logMessageParameters[0]
{1} would then be substituted with the Message ID value - logMessageParameters[1]
{2} would then be substituted with the Mediation Name value - logMessageParameters[2]
{3} would then be substituted with the Module Name value - logMessageParameters[3]
{4} would then be substituted with the Message value - logMessageParameters[4]
{5} would then be substituted with the version value - logMessageParameters[5]

Entries for each message would look similar to the following example:

29/04/08 15:11,9A85B1D2-0119-4000-E000-13E4091443BC,MessageLogger1,CustomLogging,abc,6

If you are using the custom logging, you need to implement the Handler, Formatter and Filter classes to customize the behavior of the logger. For further information on implementing these classes, see Java 2 SDK, Standard Edition Documentation. The default implementation class names are as follows:

Handler property : com.ibm.ws.sibx.mediation.primitives.logger.WESBFileHandler
Formatter property : com.ibm.ws.sibx.mediation.primitives.logger.WESBFormatter
Filter property : com.ibm.ws.sibx.mediation.primitives.logger.WESBFilter

Note: The IBM® Business Process Manager implementation of Handler classes does not call, either the flush(), or close() methods of a handler.

With a relational database