MetricGroup (Vordel SDK)

java.lang.Object
- com.vordel.reporting.rtm.api.MetricGroup

public class MetricGroup
extends java.lang.Object

A MetricGroup object is used to record metrics for Real-time Monitoring within the Gateway, and to generate custom metric data for the Transaction Event Log. Metrics written to the Analytics database are no longer an exact copy of the Real-time metrics. Analytics data is generated from the Transaction Event Log. It is possible to use this Java Metrics API to write custom metric data to the Transaction Event Log. This custom metric data can then be written to the Analytics database if metrics generation is configured in the Node Manager.

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 documentation for a complete list of MetricGroupTypes defined in the Gateway's configuration store. It is possible via the Metrics API, to create a custom 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 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 custom 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");

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

In order to view the metrics cached in the Gateway after running the code above, enter the following URL into your browser, (the value instance-1 in the url may vary depending on your topology) :-

  https://localhost:8090/api/router/service/instance-1/api/monitoring/metrics/totals?name=StockQuote&type=Service

If you wish to generate a custom metric for something whose type is not defined in the Gateway's configuration store, you must register the custom 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.axway.com:3306/axway. 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.axway.com:3306/axway", databaseMGType);
 switch (sqlStatementType) {
 case QUERY:
       databaseMetricGroup.increment("numQueries");
       break;
 case INSERT:
       databaseMetricGroup.increment("numInserts");
       break;
 case DELETE:
       databaseMetricGroup.increment("numDeletes");
       break;        
 }

 MetricGroupTypeRegistry.getInstance().registerMetricGroupType(new MetricGroupType("Database", new String[] {"numQueries", "numInserts", "numDeletes"}));
 MetricGroup databaseMetricGroup = new MetricGroup("jdbc:mysql://db.axway.com:3306/axway", "Database");
 switch (sqlStatementType) {
 case QUERY:
       databaseMetricGroup.increment("numQueries");
       break;
 case INSERT:
       databaseMetricGroup.increment("numInserts");
       break;
 case DELETE:
       databaseMetricGroup.increment("numDeletes");
       break;        
 }

A metric group can be stored in the Real-time cache, and/or the Transaction Event Log. By default, system metrics will be stored in the Real-time cache only, as similar metric data will be generated for the Analytics database based on the Transaction Event Log content. Custom metric groups created via the Metrics Java API will be written to the Transaction Event Log only, by default. The custom metric data written to the Transaction Event Log will be written to the Analytics database, (if metrics generation is turned on at the Node Manager, and processing of custom metrics is turned on). By default the custom metric data will not be available over the Monitoring REST API as it is not held in the Real-time cache. The following is a sample of the format of the data written to the Transaction Event Log for a custom metric:-

  {
   "type": "customMetric",
   "time": 1424946534796,
   "metricGroup": {
       "names": [
           "jdbc:mysql://db.axway.com:3306/axway"
       ],
       "types": [
           "Database"
       ]
   },
   "metrics": [
       {
           "ruleType": "Increment",
           "metric": "numQueries",
           "value": 1
       }
   ]
  }

The destination(s) of a custom metric group may be modified as follows:-

  databaseMGType.setDestination(EnumSet.of(MetricDestination.RealtimeCache, MetricDestination.EventLog));

  databaseMGType.setDestination(EnumSet.of(MetricDestination.RealtimeCache));

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

numQueries: A count of the number of queries
numInserts: A count of the number of inserts
numDeletes: A count of the number of deletions
queryResponseTimeMin: The minimum time it takes to run a query
queryResponseTimeMax: The maximum time it takes to run a query
queryResponseTimeAvg: The average time it takes to run a query
insertResponseTimeAvg: The average time it takes to run an insert statement
numTables: The number of tables in the database
databaseDiskSize: The current size of the data in the database
numInsertsForId-lt-100: The number of inserts for user ids in range 0-99
numInsertsForId-lt-200: The number of inserts for user ids in range 100-199
numInsertsForId-gteq-200: The number of inserts for user ids in range >=200

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", null, false, true));
 databaseMGT.addMetricType(new MetricTypeValue("insertResponseTime", null, null, "insertResponseTimeAvg", null, false, true));
 databaseMGT.addMetricType(new MetricTypeValue("numTables", null, null, null, null, true, true));
 databaseMGT.addMetricType(new MetricTypeValue("databaseDiskSize", null, null, null, null, true, true));
 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.axway.com:3306/axway", 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);

The following is a sample of the format of the data written to the Transaction Event Log for the above code. Note that metrics of type MetricTypeRangeCount are not supported in the Transaction Event Log.

{
    "type": "customMetric",
    "time": 1424953235397,
    "metricGroup": {
        "names": [
            "jdbc:mysql://db.axway.com:3306/axway"
        ],
        "types": [
            "DatabaseTracker"
        ]
    },
    "metrics": [
        {
            "ruleType": "Increment",
            "metric": "numQueries",
            "value": 1
        }
    ]
}
{
    "type": "customMetric",
    "time": 1424953235397,
    "metricGroup": {
        "names": [
            "jdbc:mysql://db.axway.com:3306/axway"
        ],
        "types": [
            "DatabaseTracker"
        ]
    },
    "metrics": [
        {
            "ruleType": "Increment",
            "metric": "numInserts",
            "value": 3
        }
    ]
}
{
    "type": "customMetric",
    "time": 1424953235398,
    "metricGroup": {
        "names": [
            "jdbc:mysql://db.axway.com:3306/axway"
        ],
        "types": [
            "DatabaseTracker"
        ]
    },
    "metrics": [
        {
            "ruleType": "Increment",
            "metric": "numDeletes",
            "value": 10
        }
    ]
}
{
    "type": "customMetric",
    "time": 1424953235398,
    "metricGroup": {
        "names": [
            "jdbc:mysql://db.axway.com:3306/axway"
        ],
        "types": [
            "DatabaseTracker"
        ]
    },
    "metrics": [
        {
            "ruleType": "TrackMin",
            "metric": "queryResponseTimeMin",
            "value": 320
        },
        {
            "ruleType": "TrackMax",
            "metric": "queryResponseTimeMax",
            "value": 320
        },
        {
            "ruleType": "TrackAverage",
            "metric": "queryResponseTimeAvg",
            "value": 320
        }
    ]
}
{
    "type": "customMetric",
    "time": 1424953235398,
    "metricGroup": {
        "names": [
            "jdbc:mysql://db.axway.com:3306/axway"
        ],
        "types": [
            "DatabaseTracker"
        ]
    },
    "metrics": [
        {
            "ruleType": "TrackAverage",
            "metric": "insertResponseTimeAvg",
            "value": 676
        }
    ]
}
{
    "type": "customMetric",
    "time": 1424953235398,
    "metricGroup": {
        "names": [
            "jdbc:mysql://db.axway.com:3306/axway"
        ],
        "types": [
            "DatabaseTracker"
        ]
    },
    "metrics": [
        {
            "ruleType": "TrackWatermark",
            "metric": "numTables",
            "value": 20
        }
    ]
}
{
    "type": "customMetric",
    "time": 1424953235398,
    "metricGroup": {
        "names": [
            "jdbc:mysql://db.axway.com:3306/axway"
        ],
        "types": [
            "DatabaseTracker"
        ]
    },
    "metrics": [
        {
            "ruleType": "TrackWatermark",
            "metric": "databaseDiskSize",
            "value": 5643576
        }
    ]
}

A MetricGroupType may have one or more child MetricGroupTypes. For example, the Service MetricGroupType could have a child MetricGroupType called Method for each method. This would make it possible to generate metrics for a service and method combination, e.g. how may times did method getQuote get called for the service StockQuote. For example:-

 MetricGroup serviceMetricGroup = new MetricGroup("StockQuote", "Service");
 MetricGroup methodMG = new MetricGroup("getQuote", "Method", serviceMetricGroup);
 methodMG.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

Constructors
Constructor and Description
`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`.
`MetricGroup(java.lang.String name, java.lang.String type, MetricGroup parent, boolean reading)` Constructs a `MetricGroup` and automatically registers the `MetricGroupType` if it is not is already registered.

Method Summary

Methods
Modifier and Type	Method and Description
`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:-
    - Auto-registration via definition in the configuration store.
    - Auto-registration via MetricGroup constructor which takes the MetricGroupType as a parameter.
    - Explicit registration via the the registerMetricGroupType(String) method on MetricGroupTypeRegistry.
    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:-
    - Auto-registration via definition in the configuration store.
    - Auto-registration via MetricGroup constructor which takes the MetricGroupType as a parameter.
    - Explicit registration via the the registerMetricGroupType(String) method on MetricGroupTypeRegistry.
    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,
           java.lang.String type,
           MetricGroup parent,
           boolean reading)
```
    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.
    
    reading - If true, indicates that returned MetricGroup will be read but not updated. Used internally for cache management.
  - 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

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

Class MetricGroup

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

MetricGroup

MetricGroup

MetricGroup

MetricGroup

MetricGroup

Method Detail

getName

getId

getMetricGroupType

getParent

increment

increment

setValue

addSample