## org.mortbay.cometd.ext
Class StatisticsExtension

    java.lang.Object
      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<String,Object> 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:

- RoundTrip: time since the stats request was received on the server to stats-reply
- Application: time spent in the application between time stats request received to probe being published
- Infrastructure: time since probe published to reply received
- Cometd: portion of Infrastructure time that was due to cometd processing (estimate based on TimesyncExtension network lag calculation)

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:

- RoundTrip = T2-T0
- Application = T1-T0
- Infrastructure = T2-T1
- Cometd = Infrastructure - Lag

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.