XmlBlaster Logo

REQUIREMENT

admin.checkpoint

XmlBlaster Logo


Type NEW
Priority HIGH
Status CLOSED
Topic Trace the message flow at pre-defined checkpoints
Des
cription

Introduction

If you need more control about where your messages are ending up you should consider to switch on this plugin. On several checkpoints inside the xmlBlaster server you can output a message passing by into a log file.

Activate the plugin

The first step is to setup the server side configuration and load the plugin:

xmlBlasterPlugins.xml:
   <plugin create='true' id='Checkpoint' className='org.xmlBlaster.util.checkpoint.Checkpoint'>
      <action do='LOAD' onStartupRunlevel='1' sequence='1'
                           onFail='resource.configuration.pluginFailed'/>
      <action do='STOP' onShutdownRunlevel='0' sequence='1'/>
      <attribute id='filterClientPropertyKey'>wfguid</attribute>
      <attribute id='showAllMessages'>true</attribute>
      <attribute id='xmlStyle'>true</attribute>
      <attribute id='showAllClientProperties'>false</attribute>
      <attribute id='log4j.configuration'>/srv/conf/log4j.properties</attribute>
      <attribute id='log4j.debug'>false</attribute>
   </plugin>

Note that showAllMessages is set to true, so all published messages are traced. If you want to limit tracing to specific messages, set showAllMessages to false and add a client property to the PublishQos and specify this client property key in the above plugin configuration (here it is filterClientPropertyKey="wfguid"). Now only messages having a "wfguid" (a workflow global unique identifier) client property will be logged.

The output is using the apache commons logging framework.
If a log4j.jar file is found it is configured in log4j.properties (see example in xmlBlaster/conf/log4j.properties), if not it is configured by java.util.logging with logging.properties (see example in xmlBlaster/conf/logging.properties)

Configure output with log4j

#log4j.properties:
log4j.rootLogger=DEBUG, CHECKPOINT

# Create new file on midnight
log4j.appender.CHECKPOINT=org.apache.log4j.DailyRollingFileAppender
log4j.appender.CHECKPOINT.File=${user.home}/checkPointLogs/checkpoint.log
log4j.appender.CHECKPOINT.DatePattern='.'yyyy-MM-dd

# CHECKPOINT uses PatternLayout. see http://logging.apache.org/log4j/1.2/apidocs/index.html
# %c == xmlBlaster.checkpoint.publish.ack
log4j.appender.CHECKPOINT.layout=org.apache.log4j.PatternLayout
log4j.appender.CHECKPOINT.layout.ConversionPattern=%d{yyyy-MM-dd HH:mm:ss.SSS} %-5p %t RL - -: %m%n
#-----------------------------------------------------------------------------

Configure output with java.util.logging

logging.properties:
#-----------------------------------------------------------------------------
# Trace flow of messages
# See javadoc of xmlBlaster/src/java/org/xmlBlaster/util/checkpoint/Checkpoint.java
# Checkpoints: "publish.enter", "publish.ack", "update.queue.add", "update.ack"
# on cluster-client side: "client.publish.enter", "client.publish.ack"
# INFO dumps the most important data
# FINEST dumps the complete message
# OFF switches a checkpoint off
xmlBlaster.checkpoint=INFO
xmlBlaster.checkpoint.handlers=org.xmlBlaster.util.log.FileHandler2
xmlBlaster.checkpoint.useParentHandlers=false
# Dump complete incoming message
#xmlBlaster.checkpoint.publish.ack.level=FINEST
# Don't log checkpoint "update.queue.add"
#xmlBlaster.checkpoint.update.queue.add.level=OFF
# Standard logging for "update.ack"
#xmlBlaster.checkpoint.update.ack.level=INFO

org.xmlBlaster.util.log.FileHandler2.pattern = %h/logs/xmlBlasterCheckpoint%u%g.log
org.xmlBlaster.util.log.FileHandler2.limit = 1000000
org.xmlBlaster.util.log.FileHandler2.count = 10
org.xmlBlaster.util.log.FileHandler2.formatter = org.xmlBlaster.util.log.XbFormatter
#-----------------------------------------------------------------------------

You can copy the logging.properties to your home directory or pass it on command line:

Start xmlBlaster:

java -Dcom.sun.management.jmxremote
     -Djava.util.logging.config.file=$XMLBLASTER_HOME/config/logging.properties
     org.xmlBlaster.Main -cluster.node.id heron

Publish some messages:

java javaclients.HelloWorldPublish -session.name Publisher/1 -numPublish 1000 -clientProperty[wfguid] 234345667777

Now you can see the message flow in the logging files in $user.home/logs (one log entry is one line)

2007-10-21 13:48:14.260  INFO   12-XmlBlaster.SOCKET.tcpListener-Publisher org.xmlBlaster.util.checkpoint.Checkpoint passingBy:
 <cp>publish.ack</cp> <topicId>Hello</topicId> <wfguid>234345667777</wfguid> <sender>client/Publisher/1</sender>

2007-10-21 13:48:20.860  INFO   13-XmlBlaster.DispatchWorkerPool.marcel-5 org.xmlBlaster.util.checkpoint.Checkpoint passingBy:
 <cp>update.ack</cp> <topicId>Hello</topicId> <wfguid>234345667777</wfguid> <sender>client/Publisher/1</sender> <destination>client/Subscribe/1</destination>

If you prefer a more readably view without xml set xmlStyle to false:

2007-10-21 14:32:42.269  INFO   12-XmlBlaster.SOCKET.tcpListener-Publisher org.xmlBlaster.util.checkpoint.Checkpoint passingBy: 
[cp=publish.ack] [topicId=Hello] [wfguid=234345667777] [sender=client/Publisher/1] [destination=client/Subscribe/1]

The logging output has an ISO 8601 formatted date and time string at the beginning of each line which allows easy sorting of the logging outputs.

The plugin can be configured during runtime using JMX, typically you choose jconsole for administration. In the service/Checkpoint node you can configure the porperties of the Checkpoint plugin and in the logging section the trace intensity.

If the Checkstyle plugin does not fullfill your requirements you can extend the class or write a specific one for your needs.

The xmlBlaster code contains following checkpoints

  1. publish.enter: When the publish call enters the server, processing starts. Only if successfully authorized.
  2. publish.ack: The published message is successfully processed by the xmlBlaster core. The ACK is now returned to the client.
  3. update.queue.add: When the message is put to a callback queue (to be delivered to a subscriber or PtP destination).
  4. update.ack: The receiving client has acknowledged the delivered message.
  5. client.publish.enter: On cluster client side: When the message is going to be forwarded to the next cluster node.
  6. client.publish.ack: On cluster client side: The receiving cluster node has acknowleged the message.
Configure

Configuration of the Checkpoint.java plugin (since v1.6.2)

Property Default / Example Description Impl
showAllMessages false If true all published message are traced, and filtering with filterClientPropertyKey is ignored. Note that internal messages and amdinistrative command messages are never traced. yes
filterClientPropertyKey wfguid If showAllMessages is set to false this string will be used to lookup a client property in the message. If it is found the message is logged, else not. The value of the key is logged as well. You can specify multiple keys separated by commas, if any of those match the message will be logged - ergo sum - keys containing a comma are not supported by this plugin. Example: "wfguid,transactionId,guid" yes
excludeIfClientPropertyKey If the client property key is found in the message the message is not logged. You can specify a comma separated list of such keys like 'table,description,quickKey'. yes
xmlStyle true The logging output is partially formatted with xml tags. yes
showAllClientProperties false By default only the filterClientPropertyKey client property is logged. yes
Checkpoints --- Currently we have following checkpoints:
"publish.enter", "publish.ack", "update.queue.add", "update.ack" and additionally "client.publish.enter", "client.publish.ack" in cluster environments.
In logging.properties you can choose the log level of each checkpoint individually: Choosing INFO dumps the logging output as described above, choosing FINEST dumps the complete message and choosing OFF dumps nothing for the specific checkpoint. Please see logging.properties for usage examples. 		yes
XbFormatter --- In logging.properties the XbFormatter is activated, please see the code of this formatter for its configuration options. On specific demand you can choose any other formatter. yes

NOTE: Configuration parameters are specified on command line (-someValue 17) or in the xmlBlaster.properties file (someValue=17). See requirement "util.property" for details.
Columns named Impl tells you if the feature is implemented.
Columns named Hot tells you if the configuration is changeable in hot operation.

See API org.xmlBlaster.util.checkpoint.Checkpoint
See API org.xmlBlaster.util.log.XbFormatter
See Java logging API

This page is generated from the requirement XML file xmlBlaster/doc/requirements/admin.checkpoint.xml

Back to overview