com.opencloud.rhino.monitoring.stats.ext

Interface StatsManagementMBean

public interface StatsManagementMBean

The StatsManagementMBean is the entry point for clients wanting to extract statistical information from a Rhino SLEE.

The StatsManagementMBean provides methods that allow clients to determine what statistical parameter sets the Rhino cluster is capable of providing and an API for extracting statistical information.

Session API

Client applications extract statistical information from Rhino using the session API provided by this MBean. With the session API client create one or more sessions each with an instance of the StatsManagementMBean running in a Rhino cluster (see createSession(). Client applications may specify the counters and frequency distributions they are interested in by subscribing them to their session. The API provides two ways for clients to retrieve subscribed statistical data, the mode of delivery used depends on the method used to create the session. createSession() creates a JMX session where statistics are delivered to the client when the client calls getAccumulatedSamples(long). Sessions created using createDirectSession() do not accumulate samples for clients to retrieve over JMX, instead they establish a socket connection directly from each Rhino node to the client and send statistical data using a proprietary protocol.

For general usage the JMX delivery method is recommended.

Session API Example

To use the session API to retrieve statistics, a client must follow the following steps:

• Create a session using createSession().

• Subscribe a number of statistics to the session using subscribeCounter(long, int, String, String, SubscriptionMode) and subscribeSample(long, int, String, String, SubscriptionMode, int, int), store the returned subscription id’s for each.

• Have Rhino begin accumulating snapshots for the subscribed statistics by calling startCollecting(long, long).

• Periodically retrieve accumulated snapshots from the MBean by calling getAccumulatedSamples(long), use the saved subscription id’s to map each element in the snapshot to a subscribed statistic.

The following code snippet gives an example of reading the "active" statistic from the "Activities" parameter set and the "activeRootSbbs" statistic from the "Services" parameter set. The client will have Rhino take a snapshot of the counters every 1 second, and download the snapshots from Rhino every 5 seconds:

 DateFormat df = new SimpleDateFormat("yyyy.MM.dd 'at' HH:mm:ss z");
 ObjectName statsManagement = new ObjectName(StatsManagementMBean.OBJECT_NAME);
 StatsManagementMBean mbean = (StatsManagementMBean) getMBeanProxy(statsManagement, StatsManagementMBean.class, false);
 long sessionId = mbean.createSession();
 int nodeId = 0; // "all nodes"
 int activeRootSbbs = mbean.subscribeCounter(sessionId, nodeId, "Services", "activeRootSbbs", SubscriptionMode.SIMPLE_GAUGE);
 int activeActivities = mbean.subscribeCounter(sessionId, nodeId, "Activities", "active", SubscriptionMode.SIMPLE_GAUGE);

 // rhino will begin gathering samples every 1 sec
 mbean.startCollecting(sessionId, 1000);

 while (true) {
     Thread.sleep(5000);

     Snapshot[] snapshots = mbean.getAccumulatedSamples(sessionId);
     for (int i = 0; i < snapshots.length; i++) {
         Snapshot snapshot = snapshots[i];
         String date = df.format(new Date(snapshot.getTimestamp()));
         int[] subsIds = snapshot.getSubscriptionIds();
         for (int j = 0; j < subsIds.length; j++) {
             final int subsId = subsIds[j];
             if (subsId == activeActivities)
                System.out.println(date
                            + ": active activities="+snapshot.getData()[j][0]);
             else if (subsId == activeRootSbbs)
                System.out.println(date
                            + ": active SBBs="+snapshot.getData()[j][0]);
             else System.err.println("Unknown subscription id: "+subsId);
         }
     }
 }

Field Summary

Fields

Modifier and Type	Field and Description
static String	OBJECT_NAME

Method Summary

Modifier and Type	Method and Description
com.opencloud.rhino.monitoring.stats.session.DirectSessionState	createDirectSession() Create a new statistics sampling session with direct delivery of statistics over a socket connection.
long	createSession() Create a new statistics sampling session.
Snapshot[]	getAccumulatedSamples(long sessionId) Get all accumulated snapshots for a session.
int[]	getMembers() Returns an array of node ids representing the current cluster membership.
String[]	getParameterSetNames() Returns all known parameter set names.
String[]	getParameterSetNames(String filter) Returns the parameter set names of all parameter sets belonging to a specified parameter set.
String	getParameterSetType(String parameterSetName) Returns the type of a parameter set.
CompositeData	getParameterSetTypeDescription(String type) Returns a tabular data representing the parameter set type description.
TabularData	getParameterSetTypeDescriptions() Returns a tabular data containing the descriptions for the available parameter set types.
TabularData	getParameterSetTypeMappings() Returns a tabular data containing mappings from parameter sets to parameter set types.
String[]	getParameterSetTypes() Returns the parameter set types supported by the server.
String[]	getRootParameterSetNames() Returns the names of all root parameter sets.
void	removeSession(long sessionId) Remove a previously created statistics session.
void	startCollecting(long sessionId, long pollingPeriod) Start collecting statistics for a session.
void	stopCollecting(long sessionId) Stop collecting statistics for a session.
int	subscribeCounter(long sessionId, int nodeid, String parameterSetName, String statisticName, SubscriptionMode mode) Subscribe a counter type statistic to a session.
int	subscribeSample(long sessionId, int nodeid, String parameterSetName, String statisticName, SubscriptionMode mode, int generations, int rolloverPeriod) Subscribe a sample type statistic to a session.
void	unsubscribe(long sessionId, int subscriptionId) Remove a subscription from a session.

Field Detail

OBJECT_NAME

static final String OBJECT_NAME

See Also:

Constant Field Values

Method Detail

getMembers

int[] getMembers()

Returns an array of node ids representing the current cluster membership.

Returns:

node id array.

getParameterSetTypes

String[] getParameterSetTypes()

Returns the parameter set types supported by the server.

Returns:

an array of parameter set type names.

getRootParameterSetNames

String[] getRootParameterSetNames()

Returns the names of all root parameter sets.

Returns:

an array of parameter set names, identifying the available root parameter sets.

Since:

Rhino 1.4.5

getParameterSetNames

String[] getParameterSetNames()

Returns all known parameter set names.

Returns:

an array of known parameter set names.

Since:

Rhino 1.4.5

getParameterSetNames

String[] getParameterSetNames(String filter)
                       throws NullPointerException,
                              UnknownStatsParameterSetException

Returns the parameter set names of all parameter sets belonging to a specified parameter set.

Parameters:

filter - the prefix that all returned parameter set names must start with.

Returns:

an array of parameter set names.

Throws:

NullPointerException - if filter is null.

UnknownStatsParameterSetException - if parameterSetName does not identify a known parameter set.

Since:

Rhino 1.4.5

getParameterSetType

String getParameterSetType(String parameterSetName)
                    throws NullPointerException,
                           UnknownStatsParameterSetException

Returns the type of a parameter set.

Parameters:

parameterSetName - the name of the parameter set.

Returns:

the parameter set type, or null if the parameter set has no defined type.

Throws:

NullPointerException - if parameterSetName is null.

UnknownStatsParameterSetException - if parameterSetName does not identify a known parameter set.

Since:

Rhino 1.4.5

getParameterSetTypeMappings

TabularData getParameterSetTypeMappings()
                                 throws ManagementException

Returns a tabular data containing mappings from parameter sets to parameter set types. Containing 4 columns, all of type java.lang.String.

• The "pset-namespace" column contains the namespace the parameter set exists in. This value is null if the parameter set exists in the global environment.

• The "pset-name" column contains the parameter set name.

• The "type-namespace" column contains the namespace of the parameter set type used by the parameter set. This value is null if the parameter set has no type or the parameter set type exists in the global environment.

• The "type-name" column contains the name of the parameter set type used by the parameter set. This value is null if the parameter set has no type.

Throws:

ManagementException - if an internal error occurs.

getParameterSetTypeDescription

CompositeData getParameterSetTypeDescription(String type)
                                      throws NullPointerException,
                                             UnknownStatsParameterTypeException,
                                             ManagementException

Returns a tabular data representing the parameter set type description. Contains 4 columns:

• A "namespace" column of type java.lang.String

• A "name" column of type java.lang.String

• A "description" column of type java.lang.String

• A "stats" column, which is tabular data of the composite type described below

Each value in the "stats" column is tabular data of a composite type containing these columns:

An "id" column of type java.lang.Integer

A "name" column of type java.lang.String

A "type" column of type java.lang.String

A "description" column of type java.lang.String

A "short-name" column of type java.lang.String

An "unit-label" column of type java.lang.String

A "source-units" column of type java.lang.String

A "display-units" column of type java.lang.String

A "default-view" column of type java.lang.String

An "is-replicated" column of type java.lang.Boolean

A "can-aggregate" column of type java.lang.Boolean

Parameters:

type - the name of a parameter set type returned by getParameterSetType(String) or getParameterSetTypes().

Throws:

NullPointerException - if type is null.

UnknownStatsParameterTypeException - if the specified parameter set type does not exist.

ManagementException - if an internal error occurs.

getParameterSetTypeDescriptions

TabularData getParameterSetTypeDescriptions()
                                     throws ManagementException

Returns a tabular data containing the descriptions for the available parameter set types. Each entry in the TabularData has the same structure as the CompositeData returned by the getParameterSetTypeDescription(String) method.

Throws:

ManagementException - if an internal error occurs.

createSession

long createSession()
            throws ManagementException

Create a new statistics sampling session.

Clients using this method to create a session should use periodic calls to getAccumulatedSamples(long) to retrieve statistics.

Returns:

new session id

Throws:

ManagementException - if an internal error occurs during session creation

createDirectSession

com.opencloud.rhino.monitoring.stats.session.DirectSessionState createDirectSession()
                                                                             throws ManagementException

Create a new statistics sampling session with direct delivery of statistics over a socket connection.

Clients using this method to create a session should not use periodic calls to getAccumulatedSamples(long) to retrieve statistics. Instead Rhino cluster members will connect directly to the clients published IP and port to deliver the statistics over a proprietary protocol.

Returns:

DirectSessionState object for the new session

Throws:

ManagementException - if an internal error occurs during session creation

removeSession

void removeSession(long sessionId)
            throws NoSuchStatsSessionException,
                   ManagementException

Remove a previously created statistics session.

All subscriptions attached to the session will be removed. If the session is currently collecting statistics (ie. startCollecting(long, long) has been called), the collection timer will be stopped. If sample type statistics are included in the session Rhino will stop collecting samples for those frequency distributions.

Parameters:

sessionId - session id of the session to remove

Throws:

NoSuchStatsSessionException - if the session id is invalid or the session has already been removed

ManagementException - if an internal error occurs during session removal

subscribeCounter

int subscribeCounter(long sessionId,
                     int nodeid,
                     String parameterSetName,
                     String statisticName,
                     SubscriptionMode mode)
              throws NullPointerException,
                     UnknownStatsParameterSetException,
                     UnrecognizedStatisticException,
                     NoSuchStatsSessionException,
                     ManagementException

Subscribe a counter type statistic to a session.

The counter type statistic will be added to the session’s subscription list. If samples are being collected (ie. startCollecting(long, long) has been called), values for the counter subscription will start appearing immediately in all subsequent snapshots.

Parameters:

sessionId - session id of the session to subscribe the counter with

nodeid - node id of the cluster member from which to retrieve the counter, or the special node id 0 to get counter values from all nodes

parameterSetName - name of the parameter set containing the counter

statisticName - name of the statistic from the parameter set

mode - a subscription mode from SubscriptionMode - one of SIMPLE_COUNTER, SIMPLE_GAUGE, DELTA_COUNTER or PER_SECOND_COUNTER.

Returns:

subscription id for the new subscription, this id can be used to match up results in a Snapshot with the correct values

Throws:

NullPointerException - if parameterSetName, statisticName, or mode is null.

UnknownStatsParameterSetException - if the parameter set does not exist

UnrecognizedStatisticException - if the statistic name does not exist within the parameter set

NoSuchStatsSessionException - if the session id is invalid or the session has been removed

ManagementException - if an internal error occurs processing the subscription

subscribeSample

int subscribeSample(long sessionId,
                    int nodeid,
                    String parameterSetName,
                    String statisticName,
                    SubscriptionMode mode,
                    int generations,
                    int rolloverPeriod)
             throws NullPointerException,
                    UnknownStatsParameterSetException,
                    UnrecognizedStatisticException,
                    NoSuchStatsSessionException,
                    ManagementException

Subscribe a sample type statistic to a session.

The sample type statistic will be added to the session’s subscription list, and all Rhino nodes included in the subscription (according to the nodeid parameter) will begin building a frequency distribution for the samples.

If samples are being collected (ie. startCollecting(long, long) has been called) frequency distribution values for the sample subscription will start appearing immediately in all subsequent snapshots

Parameters:

sessionId - session id of the session to subscribe the sample statistic with

nodeid - node id of the cluster member from which to retrieve the counter, or the special node id 0 to get counter values from all nodes

parameterSetName - name of the parameter set containing the counter

statisticName - name of the statistic from the parameter set

mode - a subscription mode from SubscriptionMode - one of ROLLING_FREQUENCY_DISTRIBUTION, PERMANENT_FREQUENCY_DISTRIBUTION or RESETTING_FREQUENCY_DISTRIBUTION

generations - number of generations to keep (ignored unless mode is ROLLING_FREQUENCY_DISTRIBUTION)

rolloverPeriod - rollover period for each generation (ignored unless mode is ROLLING_FREQUENCY_DISTRIBUTION)

Returns:

subscription id for the new subscription, this id can be used to match up results in a Snapshot with the correct values

Throws:

NullPointerException - if parameterSetName, statisticName, or mode is null.

UnknownStatsParameterSetException - if the parameter set does not exist

UnrecognizedStatisticException - if the statistic name does not exist within the parameter set

NoSuchStatsSessionException - if the session id is invalid or the session has been removed

ManagementException - if an internal error occurs processing the subscription

unsubscribe

void unsubscribe(long sessionId,
                 int subscriptionId)
          throws ManagementException,
                 NoSuchStatsSessionException

Remove a subscription from a session.

The subscribed statistic will be removed from the session’s subscription list. If samples are being collected (ie. startCollecting(long, long) has been called) the statistic will stop appearing in all subsequent snapshots. If the statistic is a sample type statistic Rhino will stop collecting samples for it’s frequency distribution.

Parameters:

sessionId - session id of the session to unsubscribe from

subscriptionId - subscription id of the subscription to remove (must have been previously returned by subscribeCounter(long, int, String, String, SubscriptionMode) or subscribeSample(long, int, String, String, SubscriptionMode, int, int).

Throws:

ManagementException - if an internal error occurs

NoSuchStatsSessionException - if the session id is invalid or the session has been removed

getAccumulatedSamples

Snapshot[] getAccumulatedSamples(long sessionId)
                          throws NoSuchStatsSessionException

Get all accumulated snapshots for a session.

When a session begins collecting snapshots startCollecting(long, long) accumulated snapshots are stored within session state on the Rhino node which owns the session (typically the node running the MBean server used to create the session). Clients must periodically call getAccumulatedSamples to extract all stored snapshots. This method clears the list of stored snapshots so there is no need for clients to check for duplicate or overlapping snapshots.

If the session is not currently collecting snapshots, or there are no snapshots available an empty array will be returned.

Clients should not call this method if the direct delivery mode of stats collection is in use (ie. the session was created using createDirectSession().

Parameters:

sessionId - session id

Returns:

an array of Snapshot

Throws:

NoSuchStatsSessionException - if the session id is invalid or the session has been removed

startCollecting

void startCollecting(long sessionId,
                     long pollingPeriod)
              throws NoSuchStatsSessionException

Start collecting statistics for a session.

A collection timer will be started on the session owning node (typically the node running the MBean server used to create the session) with the specified pollingPeriod and a new snapshot collected each time the timer fires. What happens with the snapshot depends on how the session was created:

• for sessions created with createSession() new snapshots are simply appended to the snapshot list, where they can be retrieved by clients using getAccumulatedSamples(long).

• for sessions created with createDirectSession() new snapshot information is delivered directly to clients by the originating nodes over a socket connection using a proprietary communication protocol.

A note on timeouts

Sessions that are collecting statistics will be timed out and removed if inactive for a period of time. A session is considered inactive if it is currently collecting statistics and getAccumulatedSamples(long) has not been called for some time. The timeout period is calculated by Rhino’s statistics manager and is the greater of:

• The globally configured session timer (a millisecond value, stats-session-timer from rhino-config.xml)

• 10 * the session’s pollingPeriod when collection is started by calling this method

Clients must take care to call getAccumulatedSamples(long) frequently enough to avoid this timeout or the session will be removed by Rhino and all state attached to the clients session will be lost. Typically calling every 5 * pollingPeriod milliseconds will be very safe.

Note that the above applies only to standard statistics sessions. Direct delivery sessions use a proprietary mechanism built into the rhino-stats client protocol to determine session liveness.

Parameters:

sessionId - session id

pollingPeriod - desired time in milliseconds between snapshots

Throws:

NoSuchStatsSessionException - if the session id is invalid or the session has been removed

stopCollecting

void stopCollecting(long sessionId)
             throws NoSuchStatsSessionException

Stop collecting statistics for a session.

If the session is collecting statistics it’s session timer will be cancelled. No session state is removed and any subscriptions and accumulated snapshots remain as part of the sessions state. Once this method is called on a session that is collecting statistics that session is no longer subject to removal due to timeout.

Parameters:

sessionId - session id

Throws:

NoSuchStatsSessionException - if the session id is invalid or the session has been removed