IRC on Freenode #rackspace developer forum

Rackspace Developer Docs


Let’s Build Something Powerful Together!

Submit an issue

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