Metrics Query¶
Overview¶
The BIG-IQ Metrics Query API enables you to fetch statistical information about BIG-IP system activity during a time interval. BIG-IQ saves this statistical information as entities which are defined as sets of Dimensions and Metrics which are associated with a module name, product name, and one or more metricset groups. Dimensions are characteristic extents of the system, such as “Client IP”, “URL” or “Virtual Server”. Metrics are measures of activity, such as “count”, “sum”, “min” or “max”. A MetricSet is a set of closely related Metrics which are often used together, such as “Average Server Latency”, “Max Server Latency”, and “Min Server Latency”. When you call the Metrics Query API, you must specify the product, module and metricset to identify which entity to use. See the BIG-IQ Analytics Entities topic for a catalog of entities which BIG-IQ provides for system metrics.
The BIG-IQ monitors the BIG-IP system by tracking events. The BIG-IQ Events API can be used to fetch the number of events which have occurred during a time interval and fetch detailed information about specific events. The BIG-IQ HTTP Traffic Query API enables you to retrieve information about HTTP transactions.
REST Endpoint: /mgmt/ap/query/v1/tenants/{tenant-id}/products/{product}/metric-query¶
If there are multiple tenants, the placeholder {tenant-id} represents the ID of the specific tenant being queried. If there is only one tenant this value can be set to the value: default. The placeholder {product} represents the analytic service product name of the entity which is applicable to the type of statistical information to be queried. See the Analytics Entities topic for a catalog of entities which BIG-IQ provides for system metrics.
Requests¶
POST /mgmt/ap/query/v1/tenants/{tenant-id}/products/{product}/metric-query¶
You can send a POST request to the metric-query endpoint to retrieve statistical information.
Request Parameters¶
The JSON in the body of a POST request can include the following parameters.
| Name | Type | Required | Description |
|---|---|---|---|
| aggregations | object | True for a “By Time” query. | A map object containing one or more [Aggregation-Name]. An aggregation means a metric value which summarizes the metric over the specified time range and object. The aggregations map enables requests for multiple metrics. You can choose any name for the [Aggregation-Name], however the BIG-IQ UI always uses a combination of the metricSet and the metric, separated by “$” sign. For example, “transactions$avg-count-per-sec”. The name can be used as the value of sortMetric. |
| metric | string | True if using aggregations. | Specifies the type of metric. Possible values: “max”, “min”, “sum”, “count”, “avg-count-per-sec”, “avg-value-per-sec”, “avg-value-per-event”, “sumsq” or “stddev”. |
| metricSet | string | True if using aggregations. | A set of metrics which are collected together. |
| dimension | string | False | A measurable extent of the system. If this field is omitted from a “Entities Count” query then the response is a count of all dimensions in the system. |
| dimensionFilter | object | False | A dimension filter is a set of conditions or constraints on the dimensions of the requested entities. The basic dimension filters are Dimension Binary Predicate, In Dimension Predicate and PrefixSearch. A filter can be a simple constraint or a complex logical expression. For more explanation, see the Dimension Filters section. |
| args | An array of dimension filters. | False | Used to combine basic filters into complex filters. The type of arg can be “and” or “or”. |
| dimension | string | Required with a dimensionFilter. | The dimension that the filter compares to value. |
| type | string | Required with a dimensionFilter. | Specifies the kind of filter. For more explanation see the Dimension Filters section. |
| value | string | Required with a dimensionFilter. | The string, number or boolean value the filter compares to the dimension specified in dimension. |
| kind | string | True | The value in this field is a keyword which identifies the kind of query as “By Time”, “Entities Count” and “Entities”. For an explanation of these kinds, and the keyword values, see the Query Kinds section. |
| limit | number | Only available if kind is “ap:query:stats:entitiesCount”. This parameter is optional. | If a large number of objects are returned, a query by entities returns only the top 10 objects by default, this limit can be changed by using the optional limit field. |
| module | string | True | The statistical module to be queried. Each module defines a set of statistical information and it derives a set of possible dimensions and metricSets. See the Analytics Entities topic for a list of the entities which BIG-IQ provides for system metrics. |
| sortMetric | string | False | The entities in the response are sorted by sortMetric and sortOrder. The top of the entities list is ordered on sortMetric, for example “transactions$count”. If no sorting is selected, then the order of returned objects is arbitrary. |
| sortOrder | string | False | The entities in the response are sorted by sortMetric and sortOrder. The ascendant or descendant order is specified by sortOrder. Possible values are “asc” or “desc”. If no sorting is selected, then the order of returned objects is arbitrary. |
| source | string | True | Only “bigip” is supported currently. This field indicates the source to be queried. |
| timeGranularity | object | True | The time granularity is a value which controls the time interval between one data point and another. It is approximately the size of the time interval used to aggregate several data points. Note that the response can have an actual time granularity different from that which was requested. See the section below about Requested versus actual time granularity and range. |
| duration | number | True | Duration of the time interval in the units specified by unit. |
| unit | string | True | Possible values: “SECONDS”, “MINUTES”, “HOURS” or “DAYS”. |
| timeRange | object | True | Specifies the start and end times for the query. Can be formatted as epoch time, for example, the time range can be specified as “from”: “1437584763000000” and “to”: “1437584773000000”. The time range can also be specified relative to current time. For example, a time interval of between 12 hours ago and now can be formatted as “from”: “-P12H”, “to”: “now”. A time interval of between 2 days ago and yesterday can be formatted as: “from”: “-P2D”, “to”: “-P1D”. See the section below about Requested versus actual time granularity and range. |
| from | string | True | The start time of the query’s time interval. |
| to | string | True | The end time of the query’s time interval. |
Query Parameters¶
None
Response¶
The response can contain the following parameters.
HTTP/1.1 200 OK
| Name | Type | Description |
|---|---|---|
| count | number | Internal information which be can be ignored. |
| requestDurationInMillis | number | The time taken to generate the response in milliseconds. |
| result | object | These are the parameters which apply to the response. |
| source | string | This field indicates the source queried. |
| module | string | This field specifies the statistical module queried. |
| timeRange | string | Specifies the start and end times for the query. Can be formatted as epoch time, for example, the time range can be specified as “from”: “1437584763000000” and “to”: “1437584773000000”. The time range can also be specified relative to current time. For example, a time interval of between 12 hours ago and now can be formatted as “from”: “-P12H”, “to”: “now”. A time interval of between 2 days ago and yesterday can be formatted as: “from”: “-P2D”, “to”: “-P1D”. See the section below about Requested versus actual time granularity and range. |
| from | string | The start time of the query’s time interval. |
| to | string | The end time of the query’s time interval. |
| timezone | string | Time zone of the query. For example, “UTC”. |
| durationInSec | number | Duration of time range in seconds. |
| durationInMillis | number | Duration of time range in milliseconds. |
| result | array | The result content of the query. This depends upon the type of query. For an explanation of these kinds, see the Query Kinds and the Examples section. |
| totalPoints | number | The sum of all counts. Like counts, this is internal information which can be ignored. |
| timeGranularity | object | This is the actual time granularity and it applies to all the data points mentioned in the result. timeGranularity indicates the time interval between data points and the size of the sample used to aggregate data points. The result can have a different time granularity from that requested. See the section below about Requested versus actual time granularity and range. |
| duration | number | Duration of the time interval in the units specified by unit. |
| unit | string | Possible values: “SECONDS”, “MINUTES”, “HOURS” or “DAYS”. |
| timeMillis | number | The last point in time that statistics were provided for the time range. |
Permissions¶
| Role | Allow |
|---|---|
| admin | Yes |
Query Kinds¶
There are three kinds of query: “By Time”, “Entities Count” and “Entities”. The following table summarizes the objects that can be in the request and the response for each kind of query.
| kind | Request | Response |
|---|---|---|
| ap:query:stats:byTime | kind, module, timeRange, timeGranularity, aggregations, dimensionFilter | Returns a series of data points in time, based on optional filters, time range, and time granularity. The timeGranularity in the response applies to all data points in the result. |
| ap:query:stats:entitiesCount | kind, module, timeRange, dimension, dimensionFilter | Returns a count of entities matching a set of filters returned as a number in result. |
| ap:query:stats:byEntities | kind, module, timeRange, dimension, sortMetric, sortOrder, aggregations, dimensionFilter, limit | Returns a list of objects, sorted by a requested metric. Each in the list is returned as dimension and value. For example, “client-ip”: “130.77.1.1” or “transaction-response-size$avg-value-per-sec”: 0. Each object also has the requested metric aggregations relevant to that object. This query returns the top 10 objects by default, which can be modified by the “limit” field. The entities are group by the “dimension” field. The entities are sorted by sortMetric and sortOrder. |
Dimension Filters¶
The basic dimension filters are Dimension Binary Predicate, In Dimension Predicate and PrefixSearch. A filter can be specified using the type, dimension and value fields.
| Name | type | dimension | value |
|---|---|---|---|
| Dimension Binary Predicate | Specifies the logical operator as one of: “eq”, “neq”, “lt”, “gt”, “lte” or “gte”. | The dimension to be compared to value. | The string, number or boolean value to be compared. |
| In Dimension Predicate | Use “in” to determine if dimension contains any of the values specified in value. | The dimension to be compared to values. | The array of string, number or boolean values to be compared to dimension. |
| PrefixSearch | Use to match dimension with the prefix specified in value. Searches for the prefix instead of entire value. | The dimension to be compared to value. | The prefix to match. The prefix is case sensitive. |
This is an example of a simple dimension filter on a single url.
{
"dimensionFilter": {
"type": "eq",
"dimension": "url",
"value": "http://mydomain.com"
}
}
You can combine the basic dimension filters into complex logical dimension filters using “and” and “or” and taking basic filters for arguments. For example, the following example combines basic Binary Predicate and In Predicate filters to make a complex filter.
{
"dimemsionFilter": {
"type": "and",
"args": [{
"type": "or",
"args": [{
"type": "eq",
"dimension": "url",
"value": "http://domain1.com"
},
{
"type": "eq",
"dimension": "rc",
"value": "200"
}
]
},
{
"type": "and",
"args": [{
"type": "in",
"dimension": "url",
"values": [
"http://domain1.com",
"http://domain2.com"
]
},
{
"type": "neq",
"dimension": "rc",
"value": "200"
}
]
}
]
}
}
Requested versus actual time granularity and range¶
The time granularity of the result can be different than requested because the actual time interval depends upon the largest interval available over the total requested time range. Data is collected at 30 second intervals and after 10 hours this data is aggregated into a 1 hour resolution. This means if your requested time range is less than 1 hour, and your requested time granularity is less than 30 seconds, the actual interval in the response will be for 30 second intervals. If your requested range is between 30 seconds and 1 hour, the actual interval in the result will be rounded down to the closest multiple of 30 seconds. If your requested interval is greater than 1 hour, the actual interval of the result will be rounded down to the number of hours closest to the requested time granularity.
Similarly, the actual time range of the result can be different than requested by the values of to and from provided in the request. The actual time range is always 30 seconds or larger. If your requested range is between 30 seconds and 1 hour, the actual range in the result will be rounded up to the closest multiple of 30 seconds. If your requested time range is greater than 1 hour, the actual range of the result will be rounded up to the number of hours closest to the requested time range.
Examples¶
POST for a query by time¶
A query by time returns a series of data points in time, based on optional filters, time range, and time granularity. This query kind is identified by the keyword: “ap:query:stats:byTime”
POST https://192.0.2.242/mgmt/ap/query/v1/tenants/default/products/local-traffic/metric-query
The JSON in the body of the POST can look similar to the following example.
{
"kind": "ap:query:stats:byTime",
"source": "bigip",
"module": "http",
"timeRange": {
"from": 1471185600000,
"to": 1471790411802
},
"timeGranularity": {
"duration": 3024,
"unit": "SECONDS"
},
"aggregations": {
"transactions$avg-count-per-sec": {
"metricSet": "transactions",
"metric": "avg-count-per-sec"
},
"transaction-request-size$avg-value-per-sec": {
"metricSet": "transaction-request-size",
"metric": "avg-value-per-sec"
},
"transaction-response-size$avg-value-per-sec": {
"metricSet": "transaction-response-size",
"metric": "avg-value-per-sec"
}
},
"dimensionFilter": {
"type": "and",
"args": [{
"type": "eq",
"dimension": "hostname",
"value": "shai-hulud.nomix.ts.f5net.com"
},
{
"type": "eq",
"dimension": "virtual",
"value": "/Common/phpAuction_VS_1"
}
]
}
}
Response¶
The response to the POST can look similar to the following.
{
"result": {
"source": "bigip",
"module": "http",
"timeRange": {
"from": "1471185600000",
"to": "1471790411802",
"timezone": "UTC",
"durationInSec": 604811,
"durationInMilis": 604811802
},
"timeGranularity": {
"duration": 3000,
"unit": "SECONDS"
},
"result": [{
"timeMillis": 1471431630000,
"count": 33,
"transactions$avg-count-per-sec": 0.4656765676567658,
"transaction-response-size$avg-value-per-sec": 297.9762376237625,
"transaction-request-size$avg-value-per-sec": 89.70858085808582,
"server-latency$avg-value-per-event": 1.9000708717221828
},
{
"timeMillis": 1471434660000,
"count": 101,
"transactions$avg-count-per-sec": 1.9801980198019813,
"transaction-response-size$avg-value-per-sec": 1267.1155115511551,
"transaction-request-size$avg-value-per-sec": 381.54290429042896,
"server-latency$avg-value-per-event": 3.4578333333333333
},
{
"timeMillis": 1471437690000,
"count": 1,
"transactions$avg-count-per-sec": 0.019801980198019802,
"transaction-response-size$avg-value-per-sec": 12.66930693069307,
"transaction-request-size$avg-value-per-sec": 3.8148514851485147,
"server-latency$avg-value-per-event": 2.1
}
],
"totalPoints": 135
},
"requestDurationInMillis": 9
}
POST for a query by entities count¶
A query by entities count returns a count of the entities matching a set of filters. This query kind is identified by the keyword: “ap:query:stats:entitiesCount”.
POST https://192.0.2.242/mgmt/ap/query/v1/tenants/default/products/local-traffic/metric-query
The JSON in the body of the POST can look similar to the following example.
{
"kind": "ap:query:stats:entitiesCount",
"source": "bigip",
"module": "http",
"dimension": "application",
"timeRange": {
"from": 1471185600000,
"to": 1471790411802
},
"dimensionFilter": {
"type": "and",
"args": [{
"type": "eq",
"dimension": "hostname",
"value": "shai-hulud.nomix.ts.f5net.com"
},
{
"type": "eq",
"dimension": "virtual",
"value": "/Common/phpAuction_VS_1"
}
]
}
}
Response¶
The response is the count and it is provided as a number in the result. The response to the POST can look similar to the following.
{
"result": {
"source": "bigip",
"module": "http",
"timeRange": {
"from": "1471185600000",
"to": "1471790411802",
"timezone": "UTC",
"durationInSec": 604811,
"durationInMilis": 604811802
},
"result": 3
},
"requestDurationInMillis": 4
}
POST for a query by entities¶
A query by entities provides a list of objects, sorted by a requested metric. This query kind is identified by the keyword: “ap:query:stats:byEntities” When there is a large number of objects, this query returns the top 10 objects by default, the limit can be modified by the “limit” field. The entities are group by the “dimension” field.
The entities are sorted by sortMetric and SortOrder. If no sorting is selected, then the list of returned objects and order of return is arbitrary, determined by the DB that is being used.
POST https://192.0.2.242/mgmt/ap/query/v1/tenants/default/products/local-traffic/metric-query
The JSON in the body of the POST can look similar to the following example.
The following example is requesting for top 5 client-ips, sorted by transactions$count, however for every provided client ip, several metrics are provided, such as: transaction-response-size$avg-value-per-sec, client-latency$avg-value-per-event, etc
{
"kind": "ap:query:stats:byEntities",
"source": "bigip",
"module": "http",
"timeRange": {
"from": 1517131143000,
"to": 1617131918000
},
"dimension": "client-ip",
"sortMetric": "transactions$count",
"sortOrder": "desc",
"aggregations": {
"transactions$count": {
"metricSet": "transactions",
"metric": "count"
},
"transaction-request-size$avg-value-per-sec": {
"metricSet": "transaction-request-size",
"metric": "avg-value-per-sec"
},
"transaction-response-size$avg-value-per-sec": {
"metricSet": "transaction-response-size",
"metric": "avg-value-per-sec"
},
"server-latency$avg-value-per-event": {
"metricSet": "server-latency",
"metric": "avg-value-per-event"
},
"client-latency$avg-value-per-event": {
"metricSet": "client-latency",
"metric": "avg-value-per-event"
},
"transaction-e2e-time$avg-value-per-event": {
"metricSet": "transaction-e2e-time",
"metric": "avg-value-per-event"
}
},
"limit": 5
}
Response¶
The result of a query by entities is an array of objects, each one has the requested dimension as a field name with the name of the object as the value (such as “client-ip”: “130.77.1.1” in the example above). Each object also has the requested metric aggregations relevant to that object.
Note that in the following example “client-ip”: “Aggregated” is being returned because the requested dimension is “client-ip”.
{
"result": {
"source": "bigip",
"module": "http",
"timeRange": {
"from": "1551000240000",
"to": "1551189180000",
"timezone": "Asia/Jerusalem",
"durationInMillis": 188940000,
"durationInSec": 188940
},
"result": [{
"count": 1850,
"transaction-response-size$avg-value-per-sec": 0,
"transactions$count": 6340,
"client-ip": "Aggregated",
"transaction-request-size$avg-value-per-sec": 6.927839525775378,
"client-latency$avg-value-per-event": 0,
"server-latency$avg-value-per-event": 0,
"transaction-e2e-time$avg-value-per-event": 0
},
{
"count": 158,
"transaction-response-size$avg-value-per-sec": 0,
"transactions$count": 324,
"client-ip": "128.77.4.1",
"transaction-request-size$avg-value-per-sec": 0.3549698316926008,
"client-latency$avg-value-per-event": 0,
"server-latency$avg-value-per-event": 0,
"transaction-e2e-time$avg-value-per-event": 0
},
{
"count": 153,
"transaction-response-size$avg-value-per-sec": 0,
"transactions$count": 316,
"client-ip": "25.77.3.4",
"transaction-request-size$avg-value-per-sec": 0.34453265586958826,
"client-latency$avg-value-per-event": 0,
"server-latency$avg-value-per-event": 0,
"transaction-e2e-time$avg-value-per-event": 0
},
{
"count": 143,
"transaction-response-size$avg-value-per-sec": 0,
"transactions$count": 296,
"client-ip": "117.77.3.1",
"transaction-request-size$avg-value-per-sec": 0.3242934264845983,
"client-latency$avg-value-per-event": 0,
"server-latency$avg-value-per-event": 0,
"transaction-e2e-time$avg-value-per-event": 0
},
{
"count": 135,
"transaction-response-size$avg-value-per-sec": 0,
"transactions$count": 288,
"client-ip": "130.77.1.1",
"transaction-request-size$avg-value-per-sec": 0.31552873928231184,
"client-latency$avg-value-per-event": 0,
"server-latency$avg-value-per-event": 0,
"transaction-e2e-time$avg-value-per-event": 0
}
]
},
"requestDurationInMillis": 148
}