Overview  Package   Class  Tree  Deprecated  Index  Help 
Vordel SDK
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.vordel.reporting.rtm.api
Class MetricGroup

java.lang.Object
  extended by com.vordel.reporting.rtm.api.MetricGroup

public class MetricGroup
extends java.lang.Object

A MetricGroup object is used to record metrics for Realtime Monitoring and Reporting within the Gateway. A MetricGroup instance identifies some system entity for which we are recording a set of metrics, e.g a web service, an external API, an authenticated client, an external target server etc.

A MetricGroup has an associated MetricGroupType object. Each MetricGroupType must be registered with the MetricGroupTypeRegistry. MetricGroupTypes may be defined within the Gateway's configuration store, these MetricGroupTypes will be automatically registered. For example, some of the MetricGroupTypes defined by default are:- Service, Client, TargetServer, SystemOverview. Please refer to the Vordel documentation for a complete list of MetricGroupTypes defined in the Gateway's configuration store. It is possible via the Metrics API, to create a MetricGroup whose associated MetricGroupType is not defined in the Gateway's configuration store, see below for more information.

A MetricGroup has a set of metrics that may be updated for it. The exact list of metrics that may be updated for a MetricGroup is defined in the associated MetricGroupType. A map of MetricType objects in the MetricGroupType object defines this list of metrics. If the MetricGroupType is defined in the Gateway's configuration store, the list of metrics for the MetricGroupType must also be defined in the configuration store. For example, a MetricGroup of type Service may have the following metrics defined for it:- numMessages, successes, failures, exceptions etc. Please refer to the Vordel documentation for more information on these metrics, and the complete list of metrics for each MetricGroupType. If the MetricGroupType of the MetricGroup is not defined in the Gateway's configuration store, then the list of metrics for the MetricGroupType is defined via the metrics API.

For example, say we wish to update the metric numMessages for a Service named StockQuote as another message has been received for it. The MetricGroupType Service and its set of allowed metrics is defined in the Gateway's configuration store. The code to update numMessages is as follows:- 

  new MetricGroup("StockQuote", "Service").increment("numMessages");
or 
  MetricGroup serviceMetricGroup = new MetricGroup("StockQuote", "Service");
  serviceMetricGroup.increment("numMessages");

If you wish to record a metric for something whose type is not defined in the Gateway's configuration store, you must register the MetricGroupType and the allowed set of metrics via the Metrics API. Registration may be done via the MetricGroup constructor, or via a call to the registerMetricGroupType(String) method on MetricGroupTypeRegistry. For example, say we wish to record the number of queries, inserts, and deletions run against a database whose URL is jdbc:mysql://db.vordel.com:3306/vordel. Via the Metrics API, we define a new MetricGroupType named Database with 3 new MetricTypes, namely numQueries, numInserts, and numDeletes. The code is as follows:- 

 MetricGroupType databaseMGType = new MetricGroupType("Database", new String[] {"numQueries", "numInserts", "numDeletes"});
 MetricGroup databaseMetricGroup = new MetricGroup("jdbc:mysql://db.vordel.com:3306/vordel", databaseMGType);
 switch (sqlStatementType) {
 case QUERY:
       databaseMetricGroup.increment("numQueries");
       break;
 case INSERT:
       databaseMetricGroup.increment("numInserts");
       break;
 case DELETE:
       databaseMetricGroup.increment("numDeletes");
       break;        
 }
or 
 MetricGroupTypeRegistry.getInstance().registerMetricGroupType(new MetricGroupType("Database", new String[] {"numQueries", "numInserts", "numDeletes"}));
 MetricGroup databaseMetricGroup = new MetricGroup("jdbc:mysql://db.vordel.com:3306/vordel", "Database");
 switch (sqlStatementType) {
 case QUERY:
       databaseMetricGroup.increment("numQueries");
       break;
 case INSERT:
       databaseMetricGroup.increment("numInserts");
       break;
 case DELETE:
       databaseMetricGroup.increment("numDeletes");
       break;        
 }
Note that the above example assumes that all MetricTypes are of type MetricTypeValue where no minimum, maximum, and average values are to be generated, and where the values are reset at the start of each time window. See MetricType for more information on the different types of metrics that are supported. See the following paragraph for a more complex example with different metric types.

Say we wish to record the following different types of metrics about a database:-

The code below shows how to construct a MetricGroupType for the required metrics above, and also how to update those metrics. 
 MetricGroupType databaseMGT = new MetricGroupType("DatabaseTracker");
 databaseMGT.addMetricType(new MetricTypeValue("numQueries"));
 databaseMGT.addMetricType(new MetricTypeValue("numInserts"));
 databaseMGT.addMetricType(new MetricTypeValue("numDeletes"));
 databaseMGT.addMetricType(new MetricTypeValue("queryResponseTime", "queryResponseTimeMin", "queryResponseTimeMax", "queryResponseTimeAvg", false));
 databaseMGT.addMetricType(new MetricTypeValue("insertResponseTime", null, null, "insertResponseTimeAvg", false));
 databaseMGT.addMetricType(new MetricTypeValue("numTables", null, null, null, true, false));
 databaseMGT.addMetricType(new MetricTypeValue("databaseDiskSize", null, null, null, true, false));
 MetricRange[] metricRanges = new MetricRange[3];
 metricRanges[0] = new MetricRange("numInsertsForId-lt-100", 100, MetricRangeOperator.LT);
 metricRanges[1] = new MetricRange("numInsertsForId-lt-200", 200, MetricRangeOperator.LT);
 metricRanges[2] = new MetricRange("numInsertsForId-gteq-200", 200, MetricRangeOperator.GTEQ);
 databaseMGT.addMetricType(new MetricTypeRangeCount("idRange", metricRanges));
        
 MetricGroup dbMG = new MetricGroup("jdbc:mysql://db-tracked.vordel.com:3306/vordel", databaseMGT);
        
 dbMG.increment("numQueries");
 dbMG.increment("numInserts", 3);
 dbMG.increment("numDeletes", 10);
 // This will generate a value for metrics queryResponseTimeMin, queryResponseTimeMax and queryResponseTimeAvg
 dbMG.setValue("queryResponseTime", 320);
 // This will generate a value for metrics insertResponseTimeAvg
 dbMG.setValue("insertResponseTime", 676);
 dbMG.setValue("numTables", 20);
 dbMG.setValue("databaseDiskSize", 5643576);  
 // This will generate a value for metrics numInsertsForId-lt-100, numInsertsForId-lt-200 and numInsertsForId-gteq-200 
 dbMG.addSample("idRange", 12);

A MetricGroupType may have n child MetricGroupTypes. For example, the Service MetricGroupType has a child MetricGroupType for each client of type ServiceUsagePerClient. In this way it is possible to generate metrics that are for a service and client combination, e.g. how may times did client John Smith invoke the service StockQuote. For example:- 

 MetricGroup serviceMetricGroup = new MetricGroup("StockQuote", "Service");
 MetricGroup clientMG = new MetricGroup("John Smith", "ServiceUsagePerClient", serviceMetricGroup);
 clientMG.increment("numMessages");

Note also that once a MetricGroupType is registered, it cannot be modified unless the Gateway is rebooted. This means you cannot add, or remove a MetricType without a Gateway restart. A Gateway refresh/redeploy will not work.

See Also:
MetricGroupType, MetricType, Metrics, MetricGroupTypeRegistry

Constructor Summary
MetricGroup(java.lang.String name, MetricGroupType metricGroupType)
           Constructs a MetricGroup and automatically registers the MetricGroupType if it is not is already registered.
MetricGroup(java.lang.String name, MetricGroupType metricGroupType, MetricGroup parent)
           Constructs a MetricGroup as a child of another MetricGroup, and automatically registers the MetricGroupType if it is not is already registered.
MetricGroup(java.lang.String name, java.lang.String type)
           Constructs a MetricGroup when the related MetricGroupType is already registered.
MetricGroup(java.lang.String name, java.lang.String type, MetricGroup parent)
           Constructs a MetricGroup when the related MetricGroupType is already registered, and the MetricGroup is a child of another MetricGroup.
 
Method Summary
 void addSample(java.lang.String metricName, int sample)
          Add a sample value to a metric of type MetricTypeRangeCount.
 int getId()
          Returns the id of the MetricGroup.
 MetricGroupType getMetricGroupType()
          Returns the MetricGroupType of this MetricGroup.
 java.lang.String getName()
          Returns the name identifier of the MetricGroup.
 MetricGroup getParent()
          Returns the parent MetricGroup of this MetricGroup if there is one.
 void increment(java.lang.String metricName)
          Increment a metric of type MetricTypeValue by one.
 void increment(java.lang.String metricName, int amount)
          Increment a metric of type MetricTypeValue by amount.
 void setValue(java.lang.String metricName, int value)
          Set the value of a metric of type MetricTypeValue.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

MetricGroup

public MetricGroup(java.lang.String name,
                   java.lang.String type)

Constructs a MetricGroup when the related MetricGroupType is already registered. The MetricGroupType is identified via its name.

A MetricGroupType can be registered by one of the following mechanisms:-

Parameters:
name - The name of the MetricGroup.
type - The name of the MetricGroupType.
Throws:
java.lang.IllegalArgumentException - This is thrown if the MetricGroupType with name type is not registered.

MetricGroup

public MetricGroup(java.lang.String name,
                   java.lang.String type,
                   MetricGroup parent)

Constructs a MetricGroup when the related MetricGroupType is already registered, and the MetricGroup is a child of another MetricGroup.

A MetricGroupType can be registered by one of the following mechanisms:-

Parameters:
name - The name of the MetricGroup.
type - The name of the MetricGroupType.
parent - The parent MetricGroup.
Throws:
java.lang.IllegalArgumentException - This is thrown if the MetricGroupType with name type is not registered.

MetricGroup

public MetricGroup(java.lang.String name,
                   MetricGroupType metricGroupType)

Constructs a MetricGroup and automatically registers the MetricGroupType if it is not is already registered. Note that you cannot modify a previously registered MetricGroupType via another invocation of this constructor, you must restart the Gateway to modify it.

Parameters:
name - The name of the MetricGroup.
metricGroupType - The MetricGroupType.

MetricGroup

public MetricGroup(java.lang.String name,
                   MetricGroupType metricGroupType,
                   MetricGroup parent)

Constructs a MetricGroup as a child of another MetricGroup, and automatically registers the MetricGroupType if it is not is already registered. Note that you cannot modify a previously registered MetricGroupType via another invocation of this constructor, you must restart the Gateway to modify it.

Parameters:
name - The name of the MetricGroup.
metricGroupType - The MetricGroupType.
parent - The parent MetricGroup.
Method Detail

getName

public java.lang.String getName()
Returns the name identifier of the MetricGroup.

Returns:
name

getId

public int getId()
Returns the id of the MetricGroup.

Returns:
id

getMetricGroupType

public MetricGroupType getMetricGroupType()
Returns the MetricGroupType of this MetricGroup.

Returns:
The MetricGroupType

getParent

public MetricGroup getParent()
Returns the parent MetricGroup of this MetricGroup if there is one.

Returns:
parent

increment

public void increment(java.lang.String metricName)
               throws MetricException
Increment a metric of type MetricTypeValue by one.

Parameters:
metricName - The name of the metric, e.g. numMessages.
Throws:
MetricException - If the MetricType of the metricName cannot be incremented.

increment

public void increment(java.lang.String metricName,
                      int amount)
               throws MetricException
Increment a metric of type MetricTypeValue by amount.

Parameters:
metricName - The name of the metric, e.g. numMessages.
amount - The amount to increment the metric by.
Throws:
MetricException - If the MetricType of the metricName cannot be incremented.
See Also:
MetricTypeValue

setValue

public void setValue(java.lang.String metricName,
                     int value)
              throws MetricException
Set the value of a metric of type MetricTypeValue.

Parameters:
metricName - The name of the metric, e.g. systemMemoryTotal, memoryUsed, processingTime.
value - The value of the metric
Throws:
MetricException - If the MetricType of the metricName cannot have setValue() called on it.
See Also:
MetricTypeValue

addSample

public void addSample(java.lang.String metricName,
                      int sample)
               throws MetricException
Add a sample value to a metric of type MetricTypeRangeCount.

Parameters:
metricName - The name of the metric, e.g. respTimeRange.
value - The sample value for the metric.
Throws:
MetricException - If the MetricType of the metricName cannot have addSample() called on it.
See Also:
MetricTypeRangeCount
Overview  Package   Class  Tree  Deprecated  Index  Help 
Vordel SDK
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

This documentation and all its contents and graphics, copyright © 1999 - 2011 Vordel