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

    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);
         }
     }
 }

    • 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

      • getParameterSetInfo

        CompositeData getParameterSetInfo​(String parameterSetName)
                           throws NullPointerException,
                                  UnknownStatsParameterSetException,
                                  ManagementException

        Returns a composite data containing metadata information about the specified parameter set. Contains 3 fields:

        • A "type" field of type java.lang.String. This contains the same value as returned by getParameterSetType(parameterSetName).

        • A "parent" field of type java.lang.String containing the key of the specified parameter set’s parent, if any.

        • A "children" field of type java.lang.String[] containing the keys of any child parameter sets of the specified parameter set.

        Parameters:
        parameterSetName - the name of the parameter set.
        Returns:
        a CompositeData object as described above.
        Throws:
        NullPointerException - if parameterSetName is null.
        UnknownStatsParameterSetException - if parameterSetName does not identify a known parameter set.
        ManagementException - if an internal error occurs generating the composite data.
        Since:
        Rhino 2.7.0

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

      • 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

      • 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

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

        Since Rhino 3.1.0 if the collection timer is already running for the session this method does nothing.

        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 client’s 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