Metrics¶
When Monitoring checks run, they generate metrics. These metrics are stored as full resolution data points in the Rackspace Monitoring system. Full resolution data points are periodically rolled up (condensed) into coarser data points.
Depending on your needs, you can use the metrics API to fetch individual data points (fine-grained) or rolled up data points (coarse-grained) over a period of time.
The following sections describe the different types of metrics and provide information about the metrics API operations you can use to review metrics data.
Cumulative and instantaneous metrics¶
Numeric metrics present numbers in one of the two ways, as cumulative values or instantaneous (snapshot) values.
Type |
Alarm |
Graph |
Description |
---|---|---|---|
Cumulative metric |
if (rate(metric[$metricname]) > $threshold) {return new AlarmStatus(CRITICAL, ‘rate is greater than $threshold’); } |
Draw the change rates of the values, the “derivative of order of one.” |
The value presents cumulative statistics from the time the metric was created. The value keeps growing. Example: |
Instantaneous metric |
if (metric[$metricname]) > $threshold) { return new AlarmStatus(CRITCAL, ‘value is greater than $threshold’); } |
Typically draw the value directly. |
The value presents the state at the time the metric is collected. The value can change in any direction. Example: |
Data granularity¶
Rackspace Monitoring supports several granularities of data: full resolution data and rollups computed at 5, 20, 60, 240 and 1440 minute intervals.
When you fetch metrics data points, you specify several parameters to control the granularity of data returned:
A time range for the points
Either the number of points you want returned or the resolution of the data you want returned
When you query by points, the API selects the resolution that will return you the number of points you requested. The API makes the assumption of a 30 second frequency, performs the calculation, and selects the appropriate resolution.
Note
Because the API performs calculations to determine the points returned for a particular resolution, the number of points returned may differ from the specific number of points you request.
You specify resolution |
API returns points |
---|---|
FULL |
5760 |
MIN5 |
576 |
MIN20 |
144 |
MIN60 |
48 |
MIN240 |
12 |
MIN1440 |
2 |
Alternately, the next table shows the resolution the API calculates depending upon the number of points you request:
You specify points in the range |
API calculates resolution |
---|---|
3168-infinite |
FULL |
360-3167 |
MIN5 |
96-359 |
MIN20 |
30-95 |
MIN60 |
7-29 |
MIN240 |
0-6 |
MIN1440 |
Data point expiration¶
Rackspace Monitoring expires data points according to the following schedule:
Resolution |
Expiration |
---|---|
FULL |
2 days |
MIN5 |
10 days |
MIN20 |
20 days |
MIN60 |
155 days |
MIN240 |
300 days |
MIN1440 |
5 years |
Metrics API operations¶
Use the following metrics API operations to create, view, and manage metrics resources.
List metrics by check ID¶
GET /entities/{entityId}/checks/{checkId}/metrics
Lists the metrics associated with the specified checkId
.
This operation can be paginated. For information, see Paginated collections.
This operation does not require a request body.
This operation returns a response body that lists the metrics associated with your check. A single check usually generates several metrics. For example, http checks generate the following metrics: bytes, code, duration, truncated, tt_connect, tt_firstbyte.
Metrics generated by remote checks are generated for each monitoring zone where the check is issued.
Metric names use the syntax:
monitoringZone
.``metricName``
where:
monitoringZone
is the monitoring zone where the check was issued.
metricName
is the name of the metric.
For example a metric called tt_connect
, generated from the dfw
monitoring zone, is labeled as mzdfw.tt_connect
.
Note
Metrics generated by agent checks have no monitoring zone.
The following table shows the possible response codes for this operation:
Response Code |
Name |
Description |
---|---|---|
200 |
OK |
The request completed. |
400 |
Bad request |
The system received an invalid value in a request. |
401 |
Unauthorized |
The system received a request from a user that is not authenticated. |
403 |
Forbidden |
The system received a request that the user is not authorized to make. |
405 |
Method Not Allowed |
The method specified in the request is not supported for the resource. A list of valid methods for the requested resource is included in the response. |
413 |
Over Limit |
The response body is too large. |
500 |
Internal Server Error |
An unexpected condition was encountered. |
503 |
Service Unavailable |
The system is experiencing heavy load or another system failure. |
Request¶
The following table shows the header parameters for the request:
Name |
Type |
Description |
---|---|---|
X-Auth-Token |
String (Required) |
A valid authentication token with administrative access. For details, see Get your credentials |
Note
This operation does not accept a request body.
Response¶
Example List metrics by check ID: JSON response
{
"values": [
{
"name": "mzdfw.available",
"unit": "percent",
"type": "D"
},
{
"name": "mzdfw.average",
"unit": "seconds",
"type": "D"
}
],
"metadata": {
"count": 2,
"limit": null,
"marker": null,
"next_marker": null,
"next_href": null
}
}
Get data points by metric name¶
GET /entities/{entityId}/checks/{checkId}/metrics/{metricName}/plot
Queries for all data points of metricName
between two points in time.
metricName
refers to the fully concatenated metric described in
Metrics API operations.
This operation does not require a request body.
This operation returns a response body that lists all data points
between two points in time for metricName
. To control the data points
returned in the response body, specify the required request URI
parameters described in the following table.
Note
Rackspace Monitoring is currently limited to 1440 data points returned per request. If all your data is not returned, break your request into multiple requests across smaller time ranges.
The following table shows the possible response codes for this operation:
Response Code |
Name |
Description |
---|---|---|
200 |
OK |
The request completed. |
400 |
Bad request |
The system received an invalid value in a request. |
401 |
Unauthorized |
The system received a request from a user that is not authenticated. |
403 |
Forbidden |
The system received a request that the user is not authorized to make. |
405 |
Method Not Allowed |
The method specified in the request is not enabled for the resource. A list of valid methods for the requested resource is included in the response. |
413 |
Over Limit |
The response body is too large. |
500 |
Internal Server Error |
An unexpected condition was encountered. |
503 |
Service Unavailable |
The system is experiencing heavy load or another system failure. |
Request¶
The following table shows the header parameters for the request:
Name |
Type |
Description |
---|---|---|
X-Auth-Token |
String (Required) |
A valid authentication token with administrative access. For details, see Get your credentials |
The following table shows the URI parameters for the request:
Name |
Type |
Description |
---|---|---|
{fromTimeStamp} |
String (Required) |
|
{toTimeStamp} |
String (Required) |
|
{numberPoints} |
String (Required) |
|
{granularity} |
String (Required) |
|
{stats} |
String (Required) |
|
Note
This operation does not accept a request body.
Response¶
Example Fetch data points, full resolution: JSON response
{
"values": [
{
"numPoints": 1,
"average": 4,
"timestamp": 1335744000000
},
{
"numPoints": 1,
"average": 6,
"timestamp": 1335744000030
}
],
"metadata": {
"count": 2,
"limit": null,
"marker": null,
"next_marker": null,
"next_href": null
}
}
Example Fetch data points, rollup: JSON response
{
"values": [
{
"numPoints": 1141,
"average": 4.1,
"timestamp": 1335744000000
},
{
"numPoints": 2880,
"average": 6.05,
"timestamp": 1335830400000
}
],
"metadata": {
"count": 2,
"limit": null,
"marker": null,
"next_marker": null,
"next_href": null
}
}