WebSphere

Message Logger mediation primitive

Use the Message Logger mediation primitive to store messages in a relational database. Alternatively, you can use the custom logging functionality to write to other storage mediums.

Introduction

The Message Logger mediation primitive can 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 under a schema qualifier of ESBLOG. The CommonDB database is, as its name suggests, used for a number of different runtime functions.
  • Logs to the CommonDB database identified by the JNDI location jdbc/mediation/messageLog, and the run time 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.

Rather than having the ESBLOG.MSGLOG table in the CommonDB database, you can create the table in your own database. You can use the createMessageLoggerResource.jacl script to help you create the ESBLOG.MSGLOG table in your own database.

You can also use the createMessageLoggerResource.jacl script to identify different schema qualifiers. To identify different schema qualifiers you use the createMessageLoggerResource.jacl script to create a WebSphere® environment variable called ESB_MESSAGE_LOGGER_QUALIFER.

When you install and configure your runtime product you can specify which physical database is used as the CommonDB database. For example, you might define the CommonDB database as being a DB2® database. Refer to the runtime installation documentation for further information on the CommonDB database.

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 run time 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, 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 can either manually configure the required data source, or use the createMessageLoggerResource.jacl script to create database resources for the Message Logger.
If your run time has a mixed cell, (where some nodes are at version 6.1.0 and some are below version 6.1.0), the nodes below version 6.1.0 will 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. Refer to the runtime documentation for further information on the federation of nodes.

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 and i5/OS, because there can be only one physical database throughout the z/OS or i5/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 or i5/OS system, additional databases must exist on other systems. You could have other databases on any of the following systems: other z/OS systems, i5/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: http://java.sun.com/j2se/1.4.2/docs/api/java/util/logging/package-summary.html. 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 WebSphere Enterprise Service Bus implementation of Handler classes does not call, either the flush(), or close() methods of a handler.

Properties

Common

Logging Type
Identifies whether to log the message to a Database or using the custom logging functionality.
Enabled
Defines whether the message is mediated by the Message Logger mediation primitive. By default the mediate action of the Message Logger mediation primitive is enabled. You can suspend the mediate action by clearing the checkbox.
Root
An XPath 1.0 expression representing the scope of the message to be logged. You can specify: /, /body, /headers, or your own XPath expression. / refers to the complete SMO, /body refers to the body section of the SMO, /headers refers to the headers of the SMO. If you specify your own XPath expression, the part of the SMO you specify is processed. The message to be logged is converted to XML from the point specified by Root.

Database

Data source name
The JNDI name of the datasource that defines where the data will be logged. From version 6.1.x onwards, the default jdbc/mediation/messageLog maps to the CommonDB database.
Transaction mode
Defines whether to commit changes to the database, in the flow's transaction or in a new transaction. If you specify Same, the message is logged in the flow's transaction. By default, the flow is executed under a local transaction although the mediation component can be configured to run under a global transaction. If a global transaction is specified and a failure occurs in the flow then the global transaction, including the log operation, is rolled back. If you specify New, the message is logged in its own local transaction. In this case, if a failure occurs in the flow the message logging is not rolled back.

Custom

Handler
You can provide a Handler implementation class to customize the behavior of the custom logger. You can log through more than one Handler implementation class if you want. Optionally, you can provide Formatter implementation classes, Filter implementation classes, or both. For more information, see: http://java.sun.com/j2se/1.4.2/docs/api/java/util/logging/Handler.html
Filter
You can provide a Filter implementation class with a Handler implementation class to customize the behavior of the custom logger. For more information, see: http://java.sun.com/j2se/1.4.2/docs/api/java/util/logging/Filter.html
Formatter
You can provide a Formatter implementation class with a Handler implementation to customize the behavior of the custom logger. For more information, see: http://java.sun.com/j2se/1.4.2/docs/api/java/util/logging/Formatter.html
Level
Identifies the level at which the message is logged by the custom logging functionality. For more information, see: http://java.sun.com/j2se/1.4.2/docs/api/java/util/logging/Level.html
Literal
Identifies the exact content of what is logged by the custom logging functionality. This is used in conjunction with the Formatter value.
Table 1. Message Logger mediation primitive properties
Property Type Valid Values
Data source name Database String

Default: jdbc/mediation/messageLog

Enabled Common Clear the checkbox if you want to suspend the mediate action.

Default: Selected

Filter Custom Full String range - should identify the implementing class with package name

Default: com.ibm.ws.sibx.mediation.primitives.logger.WESBFilter

Formatter Custom Full String range - should identify the implementing class with package name

Default: com.ibm.ws.sibx.mediation.primitives.logger.WESBFormatter

Handler Custom Full String range except null or empty string - should identify the implementing class with package name

Default: com.ibm.ws.sibx.mediation.primitives.logger.WESBFileHandler

Level Custom Severe, Warning, Config, Info, Fine, Finer, Finest

Default: Info

Literal Custom Full String range - see java.util.logging docs for specifics

Default: {0},{1},{2}.{3},{4},{5}

Logging type Common Database, Custom

Default: Database

Root Common String: an XPath expression representing the root of the transformation

Default: /body

Transaction mode Database String: Same or New

Default: Same

Table 2. Message Logger database table schema
Column Name SQL Type Key Field Description
TimeStamp TIMESTAMP Y The UTC timestamp, indicating when the message was logged to the database.
MessageID VARCHAR Y The message ID, from the SMO.
MediationName VARCHAR Y The name of the mediation primitive instance that logged the message.
ModuleName VARCHAR N The name of the mediation module instance that contains the Message Logger primitive.
Message CLOB N The SMO, or part of the SMO, transcoded into XML.
Version VARCHAR N The version of the logged SMO.

Considerations

Consider the following when using the Message Logger mediation primitive with a relational database:

Consider the following when using the Message Logger mediation primitive with custom logger:


reference Reference topic

Terms of use | Feedback


Timestamp icon Last updated: 20 June 2010 00:39:58 BST (DRAFT)


http://publib.boulder.ibm.com/infocenter/dmndhelp/v6r2mx/topic//com.ibm.wbit.help.medprim620.doc/ref/rwesb_MessageLoggermediationprimitive.html
Copyright IBM Corporation 2005, 2010. All Rights Reserved.
This information center is powered by Eclipse technology (http://www.eclipse.org).
iDoc on