REQUIREMENT
admin.events
|
|
REQUIREMENT admin.events |
|
| Type | NEW |
| Priority | LOW |
| Status | CLOSED |
| Topic | A event plugin which catches for example logging errors and dispatches them to a given email address or another sink. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Des cription |
Event capture and forwarding overviewThis is a configurable event capture plugin which has for example the characteristics of sending an email to a given address when an error is logged. But this plugins offers many more xmlBlaster internal events to capture and offers to send the events to other destinations like JMX notifications or send them as ordinary xmlBlaster messages. This is useful for clients or administrators to be notified on certain core events.  Example setup Here is an example setup configured in
<plugin id='EventPlugin' className='org.xmlBlaster.engine.EventPlugin'>
<action do='LOAD' onStartupRunlevel='7' sequence='11'
onFail='resource.configuration.pluginFailed'/>
<action do='STOP' onShutdownRunlevel='6' sequence='11'/>
<attribute id='eventTypes'>
logging/severe/*,
logging/warning/*,
service/RunlevelManager/event/startupRunlevel8,
client/*/session/*/event/connect
</attribute>
<attribute id='destination.smtp'>
mail.smtp.from=xmlBlaster@localhost,
mail.smtp.to=demo@localhost,
mail.collectMillis=10000
</attribute>
<attribute id='destination.jmx'/>
</plugin>
The first two <action> tags just configure the plugin itself to be loaded by xmlBlaster on startup and to be removed again on shutdown
In the above example an email (see List of supported event sources Note that this plugin must be active on a runlevel early enough depending on the event you want to capture. Those event types can be added to
List of supported event sinks Once an event occurs it is forwarded to one or multiple of the listed sinks described in the following table, see the configuration tags <attribute id='destination.XXX'>...</attribute>.
Additional notes We access the xmlBlaster core directly to register the supported internal events, hence this plugin works only if it is in the same virtual machine (JVM) as the xmlBlaster server. All events don't throw any exceptions as this plugin should have no influence on the regular work-flow of xmlBlaster. Email sink features A delay can be defined to let the dispatcher wait between sent messages, this way, in case of many errors, several errors can be dispatched in the same email, avoiding unnecessary noise. In other words, if an error occurs an email is sent immediately, but after this email until the next email is sent the dispatcher sleeps. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Example XML |
Example sending client login/logout events Here is an example how to setup <plugin id='messageEvents' className='org.xmlBlaster.engine.EventPlugin'> <action do='LOAD' onStartupRunlevel='8' sequence='4'/> <action do='STOP' onShutdownRunlevel='7' sequence='4'/> <attribute id='eventTypes'>client/*/session/*/event/connect,client/*/session/*/event/disconnect</attribute> <attribute id='destination.publish'/> <attribute id='destination.jmx'/> </plugin> JMX Jconsole screenshotThe following screen shot shows the JMX events received by
 Received messagesA client subscribing to <key oid='__sys__Event' contentMimeExtended='1.0'> <org.xmlBlaster><event/></org.xmlBlaster> </key> <content size='33'>client/Publisher/-3/event/connect</content> <qos> <clientProperty name='_nodeId'>heron</clientProperty> <clientProperty name='_subjectId'>Publisher</clientProperty> <clientProperty name='_publicSessionId' type='long'>-3</clientProperty> <clientProperty name='_absoluteName'>/node/heron/client/Publisher/-3</clientProperty> <clientProperty name='_eventType'>client/Publisher/-3/event/connect</clientProperty> <clientProperty name='_summary'>Login of client /node/heron/client/Publisher/-3</clientProperty> <clientProperty name='_description'>Login of client /node/heron/client/Publisher/-3</clientProperty> </qos> The content carries the If you want to receive the login/logout events like done in xmlBlaster before version 1.3, please read the engine.LoginLogoutEvent requirement. In the example section is a configuration which can be used to simulate the old behaviour |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Example XML |
Example sending small emails capable for SMS Here is an example how to setup To send emails you also need to configure the SmtpClient plugin as shown below,
please set the
<plugin id='smtp' className='org.xmlBlaster.util.protocol.email.SmtpClient'>
<action do='LOAD' onStartupRunlevel='4' sequence='7'
onFail='resource.configuration.pluginFailed'/>
<action do='STOP' onShutdownRunlevel='4' sequence='9'/>
<attribute id='mail.smtp.url'>smtp://xmlBlaster:xmlBlaster@localhost:25</attribute>
</plugin>
<plugin id='smallEmergencyEvents' className='org.xmlBlaster.engine.EventPlugin'>
<action do='LOAD' onStartupRunlevel='8' sequence='9'/>
<action do='STOP' onShutdownRunlevel='7' sequence='9'/>
<attribute id='eventTypes'>logging/severe/*,service/RunlevelManager/event/shutdownRunlevel8</attribute>
<attribute id='destination.smtp'>
mail.subject=xmlBlaster $_{eventType},
mail.content=$_{datetime} $_{id} $_{errorCode} $_{summary},
mail.contentSeparator=${line.separator}${line.separator},
mail.smtp.from=xmlBlaster@somecompany.com,
mail.smtp.to=admin@somecompany.com,
"mail.smtp.cc=xmlBlaster@et.universe,somebody@somewhere.xx",
mail.collectMillis=360000
</attribute>
</plugin>
Email GUI screenshotThe following screen shot shows the email received when xmlBlaster shuts down:
 The mail send is very small and could be forwarded as an SMS to your mobile phone. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Example XML |
Example sending heartbeat status messages Here is an example how to setup To send emails you also need to configure the SmtpClient plugin as shown below,
please set the
<plugin id='smtp' className='org.xmlBlaster.util.protocol.email.SmtpClient'>
<action do='LOAD' onStartupRunlevel='4' sequence='7'
onFail='resource.configuration.pluginFailed'/>
<action do='STOP' onShutdownRunlevel='4' sequence='9'/>
<attribute id='mail.smtp.url'>smtp://xmlBlaster:xmlBlaster@localhost:25</attribute>
</plugin>
<plugin create='true' id='heartbeatEmail' className='org.xmlBlaster.engine.EventPlugin'>
<action do='LOAD' onStartupRunlevel='8' sequence='14'/>
<action do='STOP' onShutdownRunlevel='7' sequence='14'/>
<attribute id='eventTypes'>
logging/severe/*,
heartbeat.43200000
</attribute>
<attribute id='destination.smtp'>
mail.smtp.from=xmlBlaster@localhost,
mail.smtp.to=xmlblasterStatus@someadmin.somecompany.eu,
mail.content=$_{xml},
mail.collectMillis=0
</attribute>
</plugin>
The value 43200000 are milliseconds (== 12 hours). Additionally we have configured
to send a heartbeat if a severe logging occurs.
The email subject is
<node id='heron'>
<uptime>18</uptime>
<runlevel>9</runlevel>
<instanceId>/xmlBlaster/node/heron/instanceId/1136980484733</instanceId>
<version>1.1</version>
<revisionNumber>14569:14573M</revisionNumber>
<freeMem>2647416</freeMem>
<maxFreeMem>68969848</maxFreeMem>
<maxMem>72876032</maxMem>
<usedMem>3906184</usedMem>
<serverTimestamp>2006-01-11 12:55:03.59</serverTimestamp>
<numClients>2</numClients>
<clientList>__sys__jdbc,__RequestBroker_internal[heron],joe</clientList>
<client id='joe'>
<session id='1'>
<state>ALIVE</state>
<remoteProperty name='logging/error'>Some severe problem occurred</remoteProperty>
</session>
</client>
<numTopics>1</numTopics>
<topicList>__sys__Event</topicList>
<numGet>0</numGet>
<numPublish>2</numPublish>
<numUpdate>0</numUpdate>
<lastWarning>[HtPasswd] Security risk, no access control:
The passwd file is switched off with 'Security.Server.Plugin.htpasswd.secretfile=NONE'
</lastWarning>
<lastError></lastError>
<versionInfo>version=1.1,revision=14569:14573M,os.name=Linux,os.version=2.6.13-15-default,
java.vm.vendor=Sun Microsystems Inc.,java.vm.version=1.5.0_05-b05,os.arch=i386,
build.timestamp=01/11/2006 12:52 PM,build.java.vendor=Sun Microsystems Inc.,
build.java.version=1.5.0_05
</versionInfo>
<see>http://www.xmlBlaster.org/xmlBlaster/doc/requirements/admin.events.html</see>
</node>
Note that the markup is similar to that described in the admin.commands requirement. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Example XML |
Examples of published messages The following list shows typical messages send by this plugin. Note the clientProperty names used.
<key oid='__sys__Event' contentMimeExtended='1.0'>
<org.xmlBlaster><event/></org.xmlBlaster>
</key>
<content size='23'>topic/*/event/subscribe</content>
<qos>
<clientProperty name='_subscriptionId'>__subId:heron-1136812798913000000</clientProperty>
<clientProperty name='_nodeId'>heron</clientProperty>
<clientProperty name='_description' encoding='base64'>...</clientProperty>
<clientProperty name='_eventType'>topic/*/event/subscribe</clientProperty>
<clientProperty name='_summary'>New subscription of client /node/heron/client/joe/1
on topic airport</clientProperty>
<clientProperty name='_publicSessionId' type='long'>1</clientProperty>
<clientProperty name='_subjectId'>joe</clientProperty>
<clientProperty name='_absoluteName'>/node/heron/client/joe/1</clientProperty>
<clientProperty name='_topicId'>airport</clientProperty>
</qos>
<key oid='__sys__Event' contentMimeExtended='1.0'>
<org.xmlBlaster><event/></org.xmlBlaster>
</key>
<content size='47'>service/RunlevelManager/event/shutdownRunlevel8</content>
<qos>
<clientProperty name='_nodeId'>heron</clientProperty>
<clientProperty name='_description'>shutdown from RUNNING to RUNNING_PRE</clientProperty>
<clientProperty name='_eventType'>service/RunlevelManager/event/shutdownRunlevel8</clientProperty>
<clientProperty name='_summary'>Shutdown to RUNNING_PRE (8)</clientProperty>
</qos>
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Example XML |
Observing the remote status of connected clients Clients can publish their status to xmlBlaster and this status can be observed by the EventPlugin framework. For example a client can choose to send its error logging to xmlBlaster or other fatal situations like low memory or lost database connections. The remoteProperties are available with JMX, so you can easily observe or manipulate them with the jconsole. To do this the steps are as follows:
Here is a simple java client sending remote properties to xmlBlaster, use this to start playing with the feature: Start xmlBlaster with this
<plugin create='true' id='heartbeatPropertyEvent' className='org.xmlBlaster.engine.EventPlugin'>
<action do='LOAD' onStartupRunlevel='8' sequence='14'/>
<action do='STOP' onShutdownRunlevel='7' sequence='14'/>
<attribute id='eventTypes'>
client/*/session/*/event/remoteProperties,
heartbeat.43200000
</attribute>
<attribute id='destination.publish'>
publish.content=$_{xml}
</attribute>
<attribute id='destination.smtp'>
mail.smtp.from=xmlBlaster@localhost,
mail.smtp.to=blue8@localhost,
mail.content=$_{xml},
mail.collectMillis=0
</attribute>
<attribute id='destination.jmx'>
jmx.content=$_{xml},
</attribute>
</plugin>
With the above configuration a heartbeat message is send every 12 hours (43200000 msec) and additionally an event is send when the remote properties are changed. The events are send to any JMX destination, additionally with email to blue8@localhost and finally to the topic __sys__Event Start a subscriber to receive the events:
And now publish three remote properties:
The event received by the above subscriber may look similar to this:
<node id='heron'>
<uptime>210</uptime>
<runlevel>9</runlevel>
<instanceId>/xmlBlaster/node/heron/instanceId/1141049201013</instanceId>
<version>1.1.1</version>
...
<client id='publish'>
<session id='1'>
<state>UNDEF</state>
<remoteProperty name='myDatabase'>postgres@192.168.1.20</remoteProperty>
<remoteProperty name='someStrangeProperty' encoding='base64'>KDx8QD4/</remoteProperty>
<remoteProperty name='logging/error'>Some severe problem occurred</remoteProperty>
</session>
</client>
<numTopics>1</numTopics>
...
</node>
It is possible to send remoteProperties on login with the ConnectQos clientProperties, for details please consult the interface.connect requirement. Remote properties can be administrated by messages send to topic '__sys__remoteProperties'. They are routed in a cluster environment to the destination given in PublishQos. This example clears all remote properties of client 'joe' from cluster node 'avalon':
java javaclients.HelloWorldPublish \
-dispatch/connection/plugin/socket/hostname heron \
-dispatch/connection/plugin/socket/port 7607 \
-queue/connection/defaultPlugin RAM,1.0 \
-plugin/socket/compress/type zlib:stream \
-Security.Client.DefaultPlugin "htpasswd,1.0" \
-session.name _remotePropResetter \
-passwd secret \
-oid __sys__remoteProperties \
-destination /node/avalon/client/joe/session/1 \
-content clear
The message content contains the command, in this case 'clear'. The destination routes the message to cluster node 'avalon', looks up the session name 'joe/1' and removes its remote properties. Other supported commands are 'set' to set all delivered client properties from this PublishQos, 'clearLastError' and 'clearLastWarning' to clear the last log of the xmlBlaster server itself (as seen in jconsole). |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Example XML |
Examples for filling up a queue and get threshold alarm The xmlBlasterPlugins.xml.template contains a more complete plugin configuration but for this test this is enough:
<plugin create='false' id='thresholdEventsCbQueue' className='org.xmlBlaster.engine.EventPlugin'>
<action do='LOAD' onStartupRunlevel='8' sequence='4'/>
<action do='STOP' onShutdownRunlevel='7' sequence='4'/>
<attribute id='eventTypes'>client/*/session/*/queue/callback/event/threshold.90%</attribute>
<attribute id='destination.publish'>
"publish.key=<key oid='__queueFillingUp'/>"
</attribute>
</plugin>
And try it on command line:
# Start the server:
java -Dcom.sun.management.jmxremote org.xmlBlaster.Main
# Publish messages:
java javaclients.HelloWorldPublish -session.name Publisher/1 -numPublish 1000
# All in one line:
java javaclients.HelloWorldSubscribe -session.name Subscriber/1 -persistentSubscribe true
-dispatch/callback/retries -1 -interactiveUpdate true -queue/callback/maxEntries 10
# Watch the messages:
java javaclients.simplereader.SimpleReaderGui -xpath "//key" -session.name sniffer
The subscriber has configured the callback queue to max 10 messages and it will block on first update message. Hit ten times enter for the publisher and the sniffer will show the alarm message. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Configure |
These parameters allow to configure the plugin. Email data sink specific settings
Valid variables to be replaced in the above templates are all configuration variables like ${user.home} and additionally the following context specific variables:
$_{datetime}
$_{summary}
$_{description}
$_{instanceId}
$_{nodeId}
$_{eventType}
$_{errorCode}
$_{versionInfo}
$_{loginName}
$_{pubSessionId}
$_{xml}
The Publish message specific settings
JMX specific settings
NOTE: Configuration parameters are specified on command line (-someValue 17) or in the
xmlBlaster.properties file (someValue=17). See requirement "util.property" for details. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| See API | org.xmlBlaster.engine.EventPlugin | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| See API | org.xmlBlaster.util.protocol.email.SmtpClient | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| See REQ | admin | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| See REQ | admin.jmx | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| See REQ | admin.telnet | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| See REQ | engine.LoginLogoutEvent | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| See REQ | util.log.plugin |
This page is generated from the requirement XML file xmlBlaster/doc/requirements/admin.events.xml
