A event plugin which catches for example logging errors and dispatches them to a given email address or another sink.

Description

Event capture and forwarding overview

This 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 xmlBlasterPlugins.xml
to give you a first idea about what you can do.

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 <attribute id='destination.smtp'/>)
is send if any logging/severe/* (==log.error) or logging/warning/* occurs.
Further an event is emitted on xmlBlaster startup in run level 8 (see service/RunlevelManager/event/startupRunlevel8)
and if a new client logs in (see client/*/session/*/event/connect).
Those events are send as JMX notifications as well (see <attribute id='destination.jmx'/>).
Adding <attribute id='destination.publish'/> would send
the event as a xmlBlaster message as well, but take care to not send logging events
as such messages will most certainly loop (if they log something they will trigger another message and so forth)!

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 <attribute id='eventTypes'>...</attribute>
markup as a comma separated list, like this you choose exactly the events you want.

Event Name

Description

logging/severe/*

Captures all errors logged, avoid to use this with the publish message sink as this could produce more logging/severe and loop

logging/warning/*

Captures all warnings logged, never use this with the publish message sink as this could produce more logging/warning and loop

service/RunlevelManager/event/startupRunlevel9

Captures event when startup runlevel reaches 9 (RUNNING), any other runlevel is possible as well (note that this plugin must be active beforehand)

service/RunlevelManager/event/shutdownRunlevel8

Captures event when shutdown runlevel reaches 8 (RUNNING_RPE), any other runlevel is possible as well (note that this plugin must be active beforehand)

client/*/session/*/event/connect

Captures event on client login (all clients)

client/[subjectId]/session/[publicSessionId]/event/connect

Captures event on given client login, e.g. "client/joe/session/1/event/connect". The combination of publicSessionId=* and/or subjectId=* is supported.

client/*/session/*/event/disconnect

Captures event on client logout (all clients)

client/[subjectId]/session/[publicSessionId]/event/disconnect

Captures event on given client logout, e.g. "client/joe/session/1/event/disconnect". The combination of publicSessionId=* and/or subjectId=* is supported.

topic/*/event/subscribe

Captures if subscribe() is invoked (on all topics)

topic/[topicId]/event/subscribe

Captures if subscribe() on the specified topic is invoked

client/[subjectId]/session/[publicSessionId]/event/subscribe

Captures if the given client has invoked subscribe(), e.g. "client/joe/session/1/event/subscribe". The publicSessionId can be a wildcard "*".

topic/*/event/unSubscribe

Captures if unSubscribe() is invoked (on all topics)

topic/[topicId]/event/unSubscribe

Captures if unSubscribe() on the specified topic is invoked

client/[subjectId]/session/[publicSessionId]/event/unSubscribe

Captures if the given client has invoked unSubscribe(), e.g. "client/joe/session/1/event/unSubscribe". The publicSessionId can be a wildcard "*".

topic/*/event/alive

Captures if a topic is created (on all topics)

topic/[topicId]/event/alive

Captures event if the given topic is created, e.g. "topic/hello/event/alive"

topic/*/event/dead

Captures if a topic is destroyed (on all topics)

topic/[topicId]/event/dead

Captures event if the given topic is destroyed, e.g. "topic/hello/event/dead"

client/[subjectId]/session/[publicSessionId]/event/connectionState

Captures event if cluster client connection status changes between ALIVE or POLLING or DEAD, e.g. "client/heron/session/1/event/connectionState". The subjectId and/or the publicSessionId can be a wildcard "*".

client/[subjectId]/session/[publicSessionId]/event/callbackState

Captures event if the client callback server goes to ALIVE or POLLING, e.g. "client/joe/session/1/event/callbackState". Note that the status change to DEAD is currently not implemented (it is reported as POLLING). The subjectId and/or the publicSessionId can be a wildcard "*".

client/*/session/*/event/remoteProperties

Captures event when the remote properties of a client change (all clients, triggered when a client publishes a message to topic __sys__remoteProperties)

lowMemoryDetection

This is not directly supported. Note however that on JDK >= 1.5 the LowMemoryDetector does a logging/severe if the memory consumption of the JVM reaches 90% (see -xmlBlaster/jmx/memoryThresholdFactor setting). Please use 'logging/severe/*' to detect this.

heartbeat.360000

Sends a heartbeat notification every given milli seconds. Setting heartbeat without millis specified defaults to one notification per day (86400000 millis).

Sends an event when the specified threshold for the given queue is reached. After the first event, additional
increasing of the queue will only result in an event if the queue has first decreased under the threshold again.
Only the main queues send events, i.e. if you have configured a CACHE having a RAM queue as its transient queue
and a JDBC queue as its persistence, then only the CACHE queue itself will send an event. This can be sent for
all types of destination (email, message, jmx ...).
This behaviour is for all queue events (also topic and subject).
As subjectId and publicSessionId you can either pass a specific value or a '*' (star) as wildcard.
Specific values are always stronger than wildcards. A wildcard on the publicSessionId and a specific
value on subjectId are stronger than the opposite. As a threshold you can either specify an absolute
value or a percentage (values higher than the max value of the queue result in a warning and the
threshold is set to the max value of the queue (100%).

client/[subjectId]/queue/subject/event/threshold.90%

The behaviour described for the callback queues is also valid here.
As subjectId you can either pass a specific value or a '*' (star) as wildcard.
Specific values are always stronger than wildcards. As a threshold you can either specify an absolute
value or a percentage (values higher than the max value of the queue result in a warning and the
threshold is set to the max value of the queue (100%).

topic/[topicId]/queue/history/event/threshold.90%

The behaviour described for the callback queues is also valid here.
As topicId you can either pass a specific value or a '*' (star) as wildcard.
Specific values are always stronger than wildcards. As a threshold you can either specify an absolute
value or a percentage (values higher than the max value of the queue result in a warning and the
threshold is set to the max value of the queue (100%).

topic/[topicId]/persistence/msgUnitStore/event/threshold.90%

The behaviour described for the history queues is also valid here.
As topicId you can either pass a specific value or a '*' (star) as wildcard.
Specific values are always stronger than wildcards. As a threshold you can either specify an absolute
value or a percentage (values higher than the max value of the queue result in a warning and the
threshold is set to the max value of the queue (100%).

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>.

Sink Name

Description

destination.smtp

Sends an email about the occurred event.
Collects multiple events to one mail depending on configuration.
You need to configure at least the email address parameters
mail.stmp.from and mail.smtp.to and
activate the SmtpClient plugin in xmlBlasterPlugins.xml.
If you have a reasonable email provider you can configure it to
forward the mail as an SMS (my provider offers this feature).
The email is send asynchronously by another thread decoupled over a RAM based
producer/consumer queue. This is to protect the xmlBlaster core against
blocking or bad performing smtp servers.
You can change this to synchronous mail delivery with mail.sendAsync=false.
The configuration of the queue size is done as described in the requirement
protocol.email with the asyncSendQueueSizeMax
parameter.

destination.publish

Publishes an xmlBlaster message which contains the occurred event,
currently all messages are published into a topic named '__sys__Event'.
On demand, you can configure the PublishKey and PublishQos as in this example:

The separator between the properties publish.key, publish.qos, publish.content
is a comma ','. If you have a comma in your markup, you can escape it with double quotes '"'.

destination.jmx

Emits an JMX notification for the occurred event.
Open 'jconsole' and 'MBeans->org.xmlBlaster->node->xxx->service->EventPlugin[yyy]'
there choose the 'Notifications[0]' tabulator and click the 'Subscribe' button.
Now you receive the configured events.

destination.exec

Executes the given shell command.
You can specifiy parameters as such:

The given command ist executed (with arguments 10 and 20) in the given dir path.
The envp variables are available as environment variables inside the shell script.
The waitFor defaults to false, so the executing thread continues during shell execution.
You can delay the activation of the EventPlugin with activationDelayAfterStartupSec, like this after
the plugin is created (during startup of xmlBlaster) it will not actively do actions until the given seconds have elapsed.
The separator between the properties command, envp etc
is a comma ','.
See xmlBlaster/config/xmlBlasterPlugins.xml.template for a complete example and how to use the variables in the shell script.

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.

ExampleXML

Example sending client login/logout events

Here is an example how to setup xmlBlasterPlugins.xml
with an JMX and publish data sink. They all will receive
events on coming and going clients.

The content carries the eventType which was the original reason for the message.

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

ExampleXML

Example sending small emails capable for SMS

Here is an example how to setup xmlBlasterPlugins.xml
to send tiny emails which are useful to be forwarded as SMS on your mobile phone.
You will be notified when an error occurs or when xmlBlaster is shutdown.

To send emails you also need to configure the SmtpClient plugin as shown below,
please set the mail.smtp.url variable to find your mail transfer agent (MTA).
Additionally please adjust all email addresses to valid ones in your environment.

The value 43200000 are milliseconds (== 12 hours). Additionally we have configured
to send a heartbeat if a severe logging occurs.
The email subject is [XmlBlaster event: heartbeat.43200000] heron
and here is an example message which is transported in the body of the email, it
replaces the $_{xml} placeholder:

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:

The client publishes a message to the topic __sys__remoteProperties

The PublishQos of the messages contains any number of client properties

Those client properties are kept in RAM by the xmlBlaster SessionInfo instance to this client, they are named remoteProperties

If configured, a heartbeat EventPlugin will send those properties to any configured sink

Note: You can use the jconsole GUI to see the current remote properties in the running server
and manipulate them manually (add another, remove all). Access over telnet works as well.

Note: Access over telnet works as well. Start a telnet session (see requirement admin.telnet)
and type (with the connected 'publish' client from below):
get client/publish/1/?remoteProperties or
set client/publish/1/?addRemoteProperty=someKey&someValue or
get client/publish/1/?clearRemoteProperties

Note: On xmlBlaster restart those properties are lost, the client needs to resend them if desired

Here is a simple java client sending remote properties to xmlBlaster, use this to start playing with the feature:

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

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':

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).

ExampleXML

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:

The template to generate the email content of the email.
Please replace '\n' with ${line.separator} to enforce a new line.

mail.contentSeparator

\n\n========== NEXT ============\n\n

The separator to use if many events are collected into one email.
Please replace '\n' with ${line.separator} to enforce a new line.

mail.collectMillis

43200000

If given > 0 the mails after the first one will be collected the given milli seconds.
It defaults to 12 hours.

mail.sendAsync

true

The email is send asynchronously by another thread decoupled over a RAM based
producer/consumer queue. This is to protect the xmlBlaster core against
blocking or bad performing smtp servers.
You can change this to synchronous mail delivery with mail.sendAsync=false.
The configuration of the queue size and overflow behaviour is done as described in the requirement
protocol.email with the asyncSendQueueSizeMax
parameter.

Valid variables to be replaced in the above templates are all configuration variables
like ${user.home} and additionally the following context specific variables:

The $_{xml} creates a xml dump of the current situation, containing
the current users, sessions, topics and some more detail data.

Publish message specific settings

Property

Default / Example

Description

Impl

publish.key

<key oid='__sys__Event'/>

You can optionally choose another topic name.

publish.qos

<qos>...</qos>

You can optionally choose another publish qos.
The default qos is transient and has a history depth of 2.
The messages have a unlimited life time and forceUpdate is set to true.

publish.content

$_{eventType}

The template to generate the content of the message.
Use ${line.separator} instead of '\n' to enforce a new line.

JMX specific settings

Property

Default / Example

Description

Impl

jmx.content

$_{eventType}: $_{summary}

The template to generate the content of the message field of JMX.
Use ${line.separator} instead of '\n' to enforce a new line.

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.