public class MetricGroup
extends java.lang.Object
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");or
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; }or
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));or
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:-
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.
MetricGroupType
,
MetricType
,
Metrics
,
MetricGroupTypeRegistry
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. |
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 . |
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:-
MetricGroup
constructor which takes the MetricGroupType
as a parameter.registerMetricGroupType(String)
method on MetricGroupTypeRegistry
.name
- The name of the MetricGroup
.type
- The name of the MetricGroupType
.java.lang.IllegalArgumentException
- This is thrown if the MetricGroupType
with name type
is not registered.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:-
MetricGroup
constructor which takes the MetricGroupType
as a parameter.registerMetricGroupType(String)
method on MetricGroupTypeRegistry
.name
- The name of the MetricGroup
.type
- The name of the MetricGroupType
.parent
- The parent MetricGroup
.java.lang.IllegalArgumentException
- This is thrown if the MetricGroupType
with name type
is not registered.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.
name
- The name of the MetricGroup
.type
- The MetricGroupType
.parent
- The MetricGroup
parent.reading
- If true, indicates that returned MetricGroup will be read but
not updated. Used internally for cache management.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.
name
- The name of the MetricGroup
.metricGroupType
- The MetricGroupType
.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.
name
- The name of the MetricGroup
.metricGroupType
- The MetricGroupType
.parent
- The parent MetricGroup
.public java.lang.String getName()
MetricGroup
.public int getId()
MetricGroup
.public MetricGroupType getMetricGroupType()
MetricGroupType
of this MetricGroup
.MetricGroupType
public MetricGroup getParent()
MetricGroup
of this MetricGroup
if there is one.public void increment(java.lang.String metricName) throws MetricException
MetricTypeValue
by one.metricName
- The name of the metric, e.g. numMessages.MetricException
- If the MetricType
of the metricName
cannot be incremented.public void increment(java.lang.String metricName, int amount) throws MetricException
MetricTypeValue
by amount
.metricName
- The name of the metric, e.g. numMessages.amount
- The amount to increment the metric by.MetricException
- If the MetricType
of the metricName
cannot be incremented.MetricTypeValue
public void setValue(java.lang.String metricName, int value) throws MetricException
MetricTypeValue
.metricName
- The name of the metric, e.g. systemMemoryTotal, memoryUsed, processingTime.value
- The value of the metricMetricException
- If the MetricType
of the metricName
cannot have setValue()
called on it.MetricTypeValue
public void addSample(java.lang.String metricName, int sample) throws MetricException
MetricTypeRangeCount
.metricName
- The name of the metric, e.g. respTimeRange.sample
- The sample value for the metric.MetricException
- If the MetricType
of the metricName
cannot have addSample()
called on it.MetricTypeRangeCount
This documentation and all its contents and graphics, copyright © 1999 - 2011 Vordel