Chapter 22. System Auditing
22.1. Message Store
The message store is a database persistence mechanism that has been designed to allow you to do audit-tracking. The message store reads and writes messages upon request. Each message must have a unique identification number. As with other ESB services, the message store is "pluggable", which means that you can "plug in" your own persistence mechanism should you desire to do so, though a default database persistence mechanism is supplied.
In the event of a system failure, the message store is also used as a holding place for messages that need to be re-delivered.
Note
If something other than a database is required, such as a file persistence mechanism, you can write your own service and then override the default behaviour with a configuration change.
22.2. Service Route Filter
The ServiceRouteFilter (
org.jboss.internal.soa.esb.message.filter.ServiceRouteFilter) is an auditing mechanism that allows you to track a message's path through different services. Like any other filter, you need to enable it from within the jbossesb-properties.xml file.
22.3. Audit the Data in the Message Store
Procedure 22.1. Task
- Open
jbossesb-properties.xmlin a text editor:vi jbossesb-properties.xml - Go to the section called filters and edit it as per the following code sample:
@lt;properties name="filters"@gt; @lt;property name="org.jboss.soa.esb.filter.1" value="org.jboss.internal.soa.esb.message.filter.MetaDataFilter"/@gt; @lt;property name="org.jboss.soa.esb.filter.2" value="org.jboss.internal.soa.esb.message.filter.GatewayFilter"/@gt; @lt;property name="org.jboss.soa.esb.filter.3" value="org.jboss.internal.soa.esb.message.filter.ServiceRouteFilter"/@gt; @lt;/properties@gt; - Save the file and exit.it will now check messages and services for whether or not service route information should be recorded. On either a per-service or a per-message level, you can tell the filter to add the route information into the context.
- To configure it on a service level, add recordRoute="true" in your service definition.
<service category="FirstServiceESB" name="SimpleListener" description="Hello World" recordRoute="true"> - To configure it on a message level, add a service-record-route property to the message properties and set it to
true.
22.4. TraceFilter
The TraceFilter (
org.jboss.internal.soa.esb.message.filter.TraceFilter) is the JBoss Enterprise SOA Platform's meta-data filter. Its role is to record entries in the log whenever a message interacts with a component. It enables you to trace an event and have information on it returned to you. For example, you can set it to trace certain kinds of messages and display their movements to make it easier to monitor them.
22.5. Log Message
By default, every interaction between components and messages is logged. Log messages contain header information linking them to the main messages. Thus, you can correlate messages sent across multiple SOA instances.
22.6. Identify a Log Message
Procedure 22.2. Task
Determining if a Message is a Log Messages
To identify a log message, open it up and see if it adheres to the following format:header: [ To: EPR: PortReference < <wsa:Address ftp://foo.bar/> >, From: null, ReplyTo: EPR: PortReference < <wsa:Address http://bar. foo/> >, FaultTo: null, Action: urn:dowork, MessageID: urn:foo/bar /1234, RelatesTo: null ]
22.7. Filter for Log Messages
Procedure 22.3. Task
Open the jbossesb-properties.xml File
Open thejbossesb-properties.xmlin a text editor:vi SOA_ROOT/jboss-as/server/PROFILE/deployers/esb.deployers/jbossesb-properties.xml.- Scroll down to the "Filter" section of the file.
- Set the org.jboss.soa.esb.messagetrace property to on. Now that it is enabled, every message that passes through it is logged.
- To gain more precise control over which messages are logged and which are ignored, set the org.jboss.soa.esb.permessagetrace property to on as well. This causes the filter to ignore those messages for which the org.jboss.soa.esb.message.unloggable property is set to yes.
Save
Save the file and exit.
Result
The TraceFilter is switched on. Whenever a message passes through this filter, you will see the following at the information level:
TraceFilter.onOutput ( header: [ To: EPR: PortReference < <wsa:Add ress ftp://foo.bar/> >, From: null, ReplyTo: EPR: PortReference < <wsa:Address http://bar.foo/> >, FaultTo: null, Action: urn:dowork , MessageID: urn:foo/bar/1234, RelatesTo: null ] )
TraceFilter.onInput ( header: [ To: EPR: PortReference < <wsa:Addr ess ftp://foo.bar/> >, From: null, ReplyTo: EPR: PortReference < < wsa:Address http://bar.foo/> >, FaultTo: null, Action: urn:dowork, MessageID: urn:foo/bar/1234, RelatesTo: null ] )
Note
This filter does not affect the input or output message.
