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
propertiesProperty |
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 schemaColumn 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:
- If the Data source name is not valid, or the
data source cannot be obtained from JNDI, a runtime exception occurs.
- If the database cannot be found, or the database returns an error,
a runtime exception occurs.
- If you want to create your own database resources, you can use
the createMessageLoggerResource.jacl script. At
run time, the createMessageLoggerResource.jacl script
is stored at: install_root/bin/createMessageLoggerResource.jacl.
- If you want to create your own database resources, the runtime
product provides data definition language (ddl) files that describe
the table schema. The Table.ddl files are stored at: install_root/util/EsbLoggerMediation/database_
type/Table.ddl. Where database_ type refers
to the type of database. For example, DB2UDB_V82.
If you create your own database and want to use the default JNDI name
for your data source, you must remove the default data source.
- If you want to create the table ESBLOG.MSGLOG on
an Oracle database, the ESBLOG user must exist. In order to add the
ESBLOG user you must have SYSDBA privileges. When you install and
configure your runtime product, you can define the Common database
as being an Oracle database and the installation process can create
the table ESBLOG.MSGLOG in the CommonDB database.
The ESBLOG user must exist before you try to create the table ESBLOG.MSGLOG.
Alternatively, you might decide to create the table ESBLOG.MSGLOG in
your own database, using the createMessageLoggerResource.jacl
script or a Table.ddl file. Again, the ESBLOG user
must already exist before you try to create the table ESBLOG.MSGLOG.
- If the XPath expression is not found in the input message, an
entry is still logged in the database but the Message column
is empty.
- If more than one Message Logger mediation primitive is used in
a particular flow, the display name must be unique.
- There is no mediation primitive specifically designed to access
data logged to a database. However, you can access the database using
the Database Lookup mediation primitive, a Custom Mediation primitive,
a Java component or an external application. If you write a custom
SCA component you can access the database using a Java™ Database
Connectivity (JDBC) call, your own Enterprise Java Bean
(EJB) or the JDBCMediator. The JDBCMediator is described under the
section "Using the Java Database
Connectivity Mediator Service" in the WebSphere Application
Server information center.
Consider the following when using the Message Logger mediation
primitive with custom logger:
- In any Formatter implementation class, a call to <LogRecord>.getParameters(),
will always return an Object array containing six elements. The content
of the array is as follows .
Table 3. Formatter implementation
class array contentElement |
Object Type |
Item |
Description |
0 |
String |
Time Stamp |
The UTC timestamp, indicating when the message
was logged to the database. |
1 |
String |
Message ID |
The message ID, from the SMO. |
2 |
String |
Mediation Name |
The name of the mediation primitive instance
that logged the message. |
3 |
String |
Module Name |
The name of the mediation module instance that
contains the Message Logger primitive. |
4 |
Data Object |
Message |
The SMO, or part of the SMO. |
5 |
String |
Version |
The version of the logged SMO. |
You should decide how much of this information you want to
log using a combination of the Literal property value and the Formatter
implementation.
- In the Filter implementation class, there is scope to perform
some complex filtering on which messages get logged, by performing
a <LogRecord>.getParameters() call and testing
the returned results.