org.mortbay.cometd.ext
Class StatisticsExtension

java.lang.Object
  extended by org.mortbay.cometd.ext.StatisticsExtension
All Implemented Interfaces:
org.cometd.Extension

public class StatisticsExtension
extends java.lang.Object
implements org.cometd.Extension

StatisticsExtension This extension helps gather statistics about round-trip message times. It works by intercepting a message sent from a client to request a statistics measurement be started, and then propagates messages to each client, measuring how long it takes for the clients to receive and respond to the message. A summary of the statistics collected is then sent back to the originating client. The server recognizes a request to start a statistics measurement looking in the received message for a key with a particular value (_statsRequestSentinel). As clients can generate messages with arbitrarily deep structures, you can specify an array of keys (_statsRequestKeys), where each element in the array is one level deeper down a nested structure. NOTE that if your messages are not just Map you will need to subclass this extension to do the message examination. Optionally, the extension can only look for these messages on a specific channel (_statsRequestChannel). The message can also specify the time to wait for all clients to respond to the probe message. The default is 10seconds. For example, if the _statsReqestKeys = {"chat"} and the sentinel is "//stats" (these is the default) a client would publish a message like so:

chat: //stats,20
The server will deliver a message back to the sending client:
chat: //stats-confirm Statistic id=99 started. Results due in 20s.
The inbound message is examined to see if it has the structure of a potential stats message. If a stats request is recognized, a new stats collection started, and the id of the stats collection and timestamp on the server is appended. Then, the server passes the message back to Bayeux so that it can be processed, and published out. At this point, the extension's send() method is called. If a stats request with an id and timestamp is recognized, the outbound message is modifed to be a probe message (_probeSentinel) and the sending time appended to the message. A client receives the probe message, and responds by publishing a reply (_probeReplySentinel). Continuing the example above, assuming we set _probeSentinel = "stats-probe", then each client will receive a message like:
chat: //stats-probe,20::--99::--1243945849978::--12345667464
Where ::-- are field delimiters, 99 is the id of the statistic collection underway and 1243945849978 is the time on the server the stats request was received, and 12345667464 is the server time at which the stats probe was published to all clients. The client responds with the same message, but prefixed by "//stats-reply":
chat: //stats-reply::--99::--1243945849978::--12345667464
The server receives the replies from each client, and updates the min,max and average statistics for: In other words, if T0 is the time at which the original stats request is received on the server, and T1 is the time at which the stats probe is sent, and T2 is the time the probe reply is received: After waiting the prescribed interval, eg 20 secs, to collect as many of the clients' messages as possible, it sends a message to the client who originated the statistics request with the results, eg:
chat://stats-results Id 2: samples=1, avgR=43, minR=43, maxR=43, avgI=42, minI=42, maxI=42, avgA=1, minA=1, maxA=1, avgC=42, minC=42, maxC=42
Note that there can be many stats collections in progress at once.


Nested Class Summary
 class StatisticsExtension.Statistic
          Statistic One measurement of min,max and average roundtrip time of a cometd message to all clients.
 
Field Summary
protected  java.lang.String _delim
           
protected  java.lang.String _probeChannel
          Channel on which outbound stats probes are sent to clients.
protected  java.lang.String[] _probeKeys
          Structure of keys to look for on outbound messages that indicate a probe being sent.
protected  java.lang.String _probeReplyChannel
          Channel on which to expect stats probe replies from clients.
protected  java.lang.String[] _probeReplyKeys
          Structure of keys to look for on inbound message with probe replies from clients.
protected  java.lang.String _probeReplySentinel
          Sentinel prefix on inbound message with probe results from a client.
protected  java.lang.String _probeSentinel
          Sentinel prefix that is put on an outbound stats probe message to indicate a probe to all clients.
protected  java.util.Map<java.lang.String,StatisticsExtension.Statistic> _statistics
           
protected  java.lang.String _statsConfirmSentinel
          Sentinel sent to user to indicate confirmation of start of a stats run.
protected  java.lang.String _statsRequestChannel
          Channel on which to examine inbound messages for a stats request.
protected  java.lang.String[] _statsRequestKeys
          Structure of keys to look for on inbound message that is a request to start a stats run.
protected  java.lang.String _statsRequestSentinel
          Sentinel received on inbound that indicates request to start stats run.
protected  java.lang.String _statsResultSentinel
          Sentinel prefix sent do user to indicate the results of the stats run.
protected  long _timeout
           
protected  java.util.Timer _timer
           
protected static java.util.concurrent.atomic.AtomicLong COUNTER
           
 
Constructor Summary
StatisticsExtension()
           
 
Method Summary
protected  StatisticsExtension.Statistic createStatistic(org.cometd.Client from, java.lang.String marker)
          Start a statistics collection run.
 java.lang.String getDelim()
           
 java.lang.String[] getProbeKeys()
           
 java.lang.String[] getProbeReplyKeys()
           
 java.lang.String getProbeReplySentinel()
           
 java.lang.String getProbeSentinel()
           
 java.lang.String getStatsConfirmSentinel()
           
 java.lang.String[] getStatsRequestKeys()
           
 java.lang.String getStatsRequestSentinel()
           
 java.lang.String getStatsResultSentinel()
           
 long getTimeout()
           
 java.util.Map<java.lang.String,java.lang.Object> matchKeys(java.util.Map<java.lang.String,java.lang.Object> map, java.lang.String[] keys)
           
 java.util.Map<java.lang.String,java.lang.Object> matchMessage(org.cometd.Message message, java.lang.String channel, java.lang.String[] keys)
           
 java.lang.String matchSentinel(java.util.Map<java.lang.String,java.lang.Object> map, java.lang.String key, java.lang.String sentinel)
           
protected  StatisticsExtension.Statistic newStatistic(org.cometd.Client from, long timeout)
           
protected  void onStatisticsRequest(org.cometd.Message message)
          Override to be able to modify the message that has been identified as a statistics request
 org.cometd.Message rcv(org.cometd.Client from, org.cometd.Message message)
          Called whenever a message is received from a client.
 org.cometd.Message rcvMeta(org.cometd.Client from, org.cometd.Message message)
           
 org.cometd.Message send(org.cometd.Client from, org.cometd.Message message)
          Called before an outbound message is sent.
 org.cometd.Message sendMeta(org.cometd.Client from, org.cometd.Message message)
           
 void setDelim(java.lang.String delim)
           
 void setProbeChannel(java.lang.String channel)
           
 void setProbeKeys(java.lang.String[] keys)
           
 void setProbeReplyChannel(java.lang.String channel)
           
 void setProbeReplyKeys(java.lang.String[] keys)
           
 void setProbeReplySentinel(java.lang.String val)
           
 void setProbeSentinel(java.lang.String val)
           
 void setStatsConfirmSentinel(java.lang.String val)
           
 void setStatsRequestChannel(java.lang.String channel)
           
 void setStatsRequestKeys(java.lang.String[] keys)
           
 void setStatsRequestSentinel(java.lang.String val)
           
 void setStatsResultSentinel(java.lang.String val)
           
 void setTimeout(long timeout)
           
protected  void updateStatistic(org.cometd.Client from, org.cometd.Message message, java.lang.String marker)
          Update a statistics collection with the result for the client.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

COUNTER

protected static java.util.concurrent.atomic.AtomicLong COUNTER

_statsRequestChannel

protected java.lang.String _statsRequestChannel
Channel on which to examine inbound messages for a stats request. Can be null, in which case all channels are examined.


_statsRequestKeys

protected java.lang.String[] _statsRequestKeys
Structure of keys to look for on inbound message that is a request to start a stats run.


_statsRequestSentinel

protected java.lang.String _statsRequestSentinel
Sentinel received on inbound that indicates request to start stats run.


_statsConfirmSentinel

protected java.lang.String _statsConfirmSentinel
Sentinel sent to user to indicate confirmation of start of a stats run.


_statsResultSentinel

protected java.lang.String _statsResultSentinel
Sentinel prefix sent do user to indicate the results of the stats run.


_probeChannel

protected java.lang.String _probeChannel
Channel on which outbound stats probes are sent to clients.


_probeSentinel

protected java.lang.String _probeSentinel
Sentinel prefix that is put on an outbound stats probe message to indicate a probe to all clients.


_probeKeys

protected java.lang.String[] _probeKeys
Structure of keys to look for on outbound messages that indicate a probe being sent.


_probeReplyChannel

protected java.lang.String _probeReplyChannel
Channel on which to expect stats probe replies from clients. Can be null, in which case, all channels are examined.


_probeReplyKeys

protected java.lang.String[] _probeReplyKeys
Structure of keys to look for on inbound message with probe replies from clients.


_probeReplySentinel

protected java.lang.String _probeReplySentinel
Sentinel prefix on inbound message with probe results from a client.


_delim

protected java.lang.String _delim

_statistics

protected java.util.Map<java.lang.String,StatisticsExtension.Statistic> _statistics

_timer

protected java.util.Timer _timer

_timeout

protected long _timeout
Constructor Detail

StatisticsExtension

public StatisticsExtension()
Method Detail

setStatsRequestKeys

public void setStatsRequestKeys(java.lang.String[] keys)

getStatsRequestKeys

public java.lang.String[] getStatsRequestKeys()

setStatsRequestSentinel

public void setStatsRequestSentinel(java.lang.String val)

getStatsRequestSentinel

public java.lang.String getStatsRequestSentinel()

setStatsRequestChannel

public void setStatsRequestChannel(java.lang.String channel)

setStatsConfirmSentinel

public void setStatsConfirmSentinel(java.lang.String val)

getStatsConfirmSentinel

public java.lang.String getStatsConfirmSentinel()

setStatsResultSentinel

public void setStatsResultSentinel(java.lang.String val)

getStatsResultSentinel

public java.lang.String getStatsResultSentinel()

setProbeChannel

public void setProbeChannel(java.lang.String channel)

setProbeSentinel

public void setProbeSentinel(java.lang.String val)

getProbeSentinel

public java.lang.String getProbeSentinel()

setProbeKeys

public void setProbeKeys(java.lang.String[] keys)

getProbeKeys

public java.lang.String[] getProbeKeys()

setProbeReplyKeys

public void setProbeReplyKeys(java.lang.String[] keys)

getProbeReplyKeys

public java.lang.String[] getProbeReplyKeys()

setProbeReplySentinel

public void setProbeReplySentinel(java.lang.String val)

getProbeReplySentinel

public java.lang.String getProbeReplySentinel()

setProbeReplyChannel

public void setProbeReplyChannel(java.lang.String channel)

setTimeout

public void setTimeout(long timeout)

getTimeout

public long getTimeout()

setDelim

public void setDelim(java.lang.String delim)

getDelim

public java.lang.String getDelim()

rcv

public org.cometd.Message rcv(org.cometd.Client from,
                              org.cometd.Message message)
Called whenever a message is received from a client. A client will initiate a stats collection run by sending a message containing the _statsRequestKeys structure with a _statsRequestSentinel as the value of the final key in the structure. This message is then passed on to the application, who should pass it back unmodified so that the send () method on this Extension can be called, where we can take timestamps and start measuring the stats. Filter the inbound messages to determine if we have received a reply to a stats probe.

Specified by:
rcv in interface org.cometd.Extension
See Also:
Extension.rcv(org.cometd.Client, org.cometd.Message)

onStatisticsRequest

protected void onStatisticsRequest(org.cometd.Message message)
Override to be able to modify the message that has been identified as a statistics request

Parameters:
message - the bayeux message identified as statistics request

rcvMeta

public org.cometd.Message rcvMeta(org.cometd.Client from,
                                  org.cometd.Message message)
Specified by:
rcvMeta in interface org.cometd.Extension

send

public org.cometd.Message send(org.cometd.Client from,
                               org.cometd.Message message)
Called before an outbound message is sent. Note this is called once per message only, not once per client. A request to start statistics collection should be passed on unmodified from the application. We will intercept this on the way to clients and start a stats run. We modify the outbound message to be a stats-probe message. If your application is likey to modify the message structure significantly from the _statsRequestKeys structure, then configure the _probeKeys so we know how to filter the outbound message.

Specified by:
send in interface org.cometd.Extension
See Also:
Extension.send(org.cometd.Client, org.cometd.Message)

sendMeta

public org.cometd.Message sendMeta(org.cometd.Client from,
                                   org.cometd.Message message)
Specified by:
sendMeta in interface org.cometd.Extension

matchMessage

public java.util.Map<java.lang.String,java.lang.Object> matchMessage(org.cometd.Message message,
                                                                     java.lang.String channel,
                                                                     java.lang.String[] keys)

matchKeys

public java.util.Map<java.lang.String,java.lang.Object> matchKeys(java.util.Map<java.lang.String,java.lang.Object> map,
                                                                  java.lang.String[] keys)

matchSentinel

public java.lang.String matchSentinel(java.util.Map<java.lang.String,java.lang.Object> map,
                                      java.lang.String key,
                                      java.lang.String sentinel)

createStatistic

protected StatisticsExtension.Statistic createStatistic(org.cometd.Client from,
                                                        java.lang.String marker)
Start a statistics collection run.

Parameters:
from -
message -
marker -

updateStatistic

protected void updateStatistic(org.cometd.Client from,
                               org.cometd.Message message,
                               java.lang.String marker)
Update a statistics collection with the result for the client.

Parameters:
from -
message -
marker -

newStatistic

protected StatisticsExtension.Statistic newStatistic(org.cometd.Client from,
                                                     long timeout)


Copyright © 1995-2010 Mort Bay Consulting. All Rights Reserved.