Retrieve metrics#
You can use the Rackspace Metrics Query API operations to retrieve metrics data from the the Rackspace Metrics database.
The examples in the following sections show how to retrieve different types of metrics data using cURL. The examples also show how to use query parameters to filter and select data.
Before running the examples, review the Rackspace Metrics concepts.
Note
These examples use the $API_ENDPOINT
, $AUTH_TOKEN
, and
$TENANT_ID
environment variables to specify the API endpoint,
authentication token, and project ID values for accessing the service.
Be sure to configure these
variables before running the
code samples.
For more information about all Rackspace Metrics Query API operations, see the Query API reference.
Using query parameters#
You can filter the metrics data returned by the Rackspace Metrics service by appending search and select query parameters to the Rackspace Metrics Query API endpoint as shown in the cURL request example. The following table describes the metrics data attributes that you can use in query requests.
Table: Attributes for filtering data
Name | Type | Description |
---|---|---|
{fromTimeStamp} |
String | from={fromTimeStamp} specifies the timestamp
that marks the beginning of the time range. The
timestamp should be represented as the number of
milliseconds that have elapsed since January 1,
1970. Note that Unix time is typically
represented in seconds, so in many cases it will
be necessary to convert this value to
milliseconds. |
{toTimeStamp} |
String | to={toTimeStamp} specifies the timestamp that
marks the end of the time range. The timestamp
should be represented as the number of
milliseconds that have elapsed since January 1,
1970. Note that "Unix time" is typically
represented in seconds, so in many cases it will
be necessary to convert this value to
milliseconds. |
{numberPoints} |
String | points={numberPoints} specifies the number of
points to display in the results. Either
points or resolution is required. If both
points and resolution are specified at the same
time, the query returns a validation error. |
{granularity} |
String | resolution={granularity} specifies the
granularity of data to query. Valid values are
FULL, MIN5, MIN20, MIN60, MIN240, and MIN1440.
Either points or resolution is required. If
both points and resolution are specified at the
same time, the query returns a validation error. |
{stats} |
String | select={stats} specifies the statistics to
return for the data. The statistics available for
selection are average, variance, min, and max. By
default, the response includes the average
statistic only. You can use multiple select
parameters in a single request. For example,
select=variance&select=max displays
both variance and max in the response. |
Note
For more information about data granularity, see Rackspace Metrics concepts .
Search query parameters#
Search metrics data by sending a GET request to the Rackspace Metrics endpoint
and including search query syntax which specifies a search query parameter
search?query=
and a string to match.
The following example shows a URI template pattern to filter data using search query syntax:
"$API_ENDPOINT/metrics/search?query=string"
The string can include wildcards, which are specified by a *.*
syntax, for example search?query=rackspace.monitoring.entities.*.byte*
.
For an example search request, see Retrieve a list of metric names.
Select query parameters#
Select specific metrics data from the Rackspace Metrics database by sending a GET request to the Rackspace Metrics Query API endpoint for a metrics resource and including query syntax. Query syntax consists of a ? mark separator followed by a set of one or more field value pairs to select data.
The following example shows a URI template pattern to filter data by specifying select criteria:
"$API_ENDPOINT/views/metricname?field1=value1&field2=value2"
Following is the syntax for specifying select criteria:
- Within each field value pair, the field name and value are separated by an
equal sign (=), for example
from=1413337468000&to=1413397348000&points=200
. - Each pair is separated by an ampersand (&), for example
field1=value1&field2=value2&field3=value3...
.
For an example filter request with select parameters, see Retrieve numeric metrics.
Retrieving a list of metric names#
You can use the Rackspace Metrics API to retrieve a list of metrics names that match specified search criteria. You specify the criteria by appending a search query parameter and a string value to match.
Note
To learn more about using query parameters, see Using query parameters.
The following example shows how to retrieve a list of metric names that contain the word "byte" in the name string.
Example: Retrieve a list of metric names cURL request
$ curl -k $API_ENDPOINT/metrics/search?query=rackspace.monitoring.entities.*.byte* \
-X GET \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'X-Auth-Token: $AUTH_TOKEN'
If successful, the GET request returns a list of the metric names that match the search criteria specified in the request.
JSON response
[
{
"metric":"rackspace.monitoring.entities.enta1WzfiH.checks.agent.apache.chTwd4Ahi1.bytes_per_second",
"unit":"unknown"
},
{
"metric":"rackspace.monitoring.entities.enta1WzfiH.checks.agent.apache.chTwd4Ahi1.bytes_per_request",
"unit":"unknown"
},
{
"metric":"rackspace.monitoring.entities.enk7owuM6b.checks.remote.http.chR1MDzv0W.mzlon.bytes",
"unit":"bytes"
},
{
"metric":"rackspace.monitoring.entities.enk7owuM6b.checks.remote.http.chR1MDzv0W.mzord.bytes",
"unit":"bytes"
},
{
"metric":"rackspace.monitoring.entities.enk7owuM6b.checks.remote.http.chR1MDzv0W.mzdfw.bytes",
"unit":"bytes"
}
]
Retrieving numeric metrics#
To retrieve numeric metrics, you submit a GET request to the
Rackspace Cloud Metrics endpoint and include the name of the metric that you
want to retrieve, for example example.metric.one
.
Note
The example.metric.one
metric set in this example was uploaded by a
request like the one shown in
Sending numeric metrics.
In the following example, the request includes
query parameters to filter the data returned by
the Rackspace Metrics service. Based on the filter criteria, the response
returns 200 data points
from data timestamped within the time period
defined by the from
and to
parameters.
Example: Retrieve a set of metrics from the database cURL request
$ curl -K $API_ENDPOINT/views/example.metric.one?from=1376509892611&to=1376509892613&points=200 \
-X GET \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "X-Auth-Token: $AUTH_TOKEN"
JSON response
{
"unit": "unknown",
"values": [
{
"numPoints": 1,
"average": 66,
"sum": 66,
"timestamp": 1376509892612,
}
],
"metadata": {
"limit": null,
"next_href": null,
"count": 1,
"marker": null
}
}
Note
The attribute sum
represents the sum of all data point values in the
given range. This attribute was released for numeric metrics on
July 5, 2016. All numeric metrics data submitted before that date will
have a sum
value of 0. All numeric metrics data submitted after that
date will have an accurate sum
value. A query which spans July 5, 2016
will have a sum
value which only represents data submitted after
July 5, 2016.
Retrieving data for a list of metrics#
You can list a subset of all metrics data for a given tenant by submitting a GET request with filter parameters to the Rackspace Metrics publicURL returned in the authentication response.
Following is the template for the request:
GET /views?field1=value1&field2=value2
The ?
and field value pairs appended to the URI are
query parameters that specify the criteria for
filtering the data returned by the Rackspace Metrics service.
The following example shows a request that returns metrics data for the time
period defined by the time stamps specified in the from
and to
values
in the request. The request also includes a points
value that specifies the
number of data points to return.
Note
For details about attributes included in the query string, see Attributes for filtering data.
Example: Retrieve a list of data from the Rackspace Metrics database cURL request
$ curl -s $API_ENDPOINT/views?from=1413337468000&to=1413397348000&points=200 \
-X GET \
-d '
['rackspace.monitoring.entities.enk7owuM6b.checks.remote.ping.chEZPLuOxp.mzdfw.available','rackspace.monitoring.entities.enk7owuM6b.checks.remote.ping.chEZPLuOxp.mzdfw.average']
' \
-H 'X-Auth-Token: $AUTH_TOKEN' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json'
If successful, the GET request returns a list of the metrics data that match the select criteria specified in the request.
JSON response
{
"metrics": [
{
"unit": "seconds",
"metric": "rackspace.monitoring.entities.enk7owuM6b.checks.remote.ping.chEZPLuOxp.mzdfw.average",
"data": [],
"type": "number"
},
{
"unit": "percent",
"metric": "rackspace.monitoring.entities.enk7owuM6b.checks.remote.ping.chEZPLuOxp.mzdfw.available",
"data": [],
"type": "number"
}
]
}
Retrieving aggregated metrics#
To retrieve aggregated metrics, you submit a GET request to the
Rackspace Metrics endpoint and include the name of the metric that you
want to retrieve, for example example.metric.one
.
Note
The example.metric.one
metric set in this example was uploaded by a
request like the one shown in
Sending aggregated metrics.
In the following example, the request includes
query parameters to filter the data returned by
the Rackspace Metrics service. Based on the filter criteria, the response
returns 20 data points
from data timestamped within the time period defined
by the from
and to
parameters.
Example: Retrieve a set of aggregated timer metrics from the database cURL request
curl -i "https://global.metrics.api.rackspacecloud.com/v2.0/$TENANT_ID/views/timer_name?from=1433435826000&to=1433781426000&points=20&select=max"
-X GET
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'X-Auth-Token: $AUTH_TOKEN'
JSON response
HTTP/1.1 200 OK
Content-Length: 225
{
"unit": "unknown",
"values": [
{
"numPoints": 32,
"timestamp": 1433606400000,
"sum": 32
}
],
"metadata": {
"limit": null,
"next_href": null,
"count": 1,
"marker": null
}
}