5.7. Metrics

 5.7.1. Summary

When Monitoring checks run, they generate metrics. These metrics are stored as full resolution data points in the Cloud 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.

 5.7.2. Data granularity

Cloud 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]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.

Consider that you want to query data for a 48-hour time range between the timestamps from=1354647221000 and to=1358794421000 (specified in milliseconds that have elapsed since January 1, 1970). The following table shows the number of points that the API returns for a given resolution.

Table 5.5. Specifying resolution to retrieve data in 48 hour period
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:

Table 5.6. Specifying number of points to retrieve data in 48 hour period
You specify points in the range API calculates resolution
3168-∞ FULL
360-3167 MIN5
96-359 MIN20
30-95 MIN60
7-29 MIN240
0-6 MIN1440

 5.7.3. Data point expiration

Cloud Monitoring expires data points according to the following schedule:

Resolution Expiration
FULL 2 days
MIN5 7 days
MIN20 15 days
MIN60 30 days
MIN240 60 days
MIN1440 365 days

 5.7.4. List metrics

Verb URI Description
GET /entities/entityId/checks/checkId/metrics Lists the metrics associated with the specified check.

Normal Response Codes: 200

Error Response Codes: 400, 401, 403, 405, 413, 500, and 503

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, emanating from the ORD monitoring zone, will appear as mzord.tt_connect.

[Note]Note

Metrics generated by agent checks have no monitoring zone.

The following examples show an XML and JSON response for this operation:

 

Example 5.39. List metrics: response in XML.

<?xml version="1.0" encoding="utf-8"?>
<container>
  <values>
    <metricinfo>
      <name>mzdfw.available</name>
    </metricinfo>
    <metricinfo>
      <name>mzdfw.average</name>
    </metricinfo>
  </values>
  <metadata>
    <count>2</count>
    <limit />
    <marker />
    <next_marker />
    <next_href />
  </metadata>
</container>


 

Example 5.40. List metrics: response in JSON.

{
    "values": [
        {
            "name": "mzdfw.available"
        },
        {
            "name": "mzdfw.average"
        }
    ],
    "metadata": {
        "count": 2,
        "limit": null,
        "marker": null,
        "next_marker": null,
        "next_href": null
    }
}


 5.7.5. Fetch data points

Verb URI Description
GET /entities/entityId/checks/checkId/metrics/metricName/plot Queries for all data points of metricName between two points in time.

Normal Response Codes: 200

Error Response Codes: 400, 401, 403, 405, 413, 500, and 503

metricName refers to the fully concatenated metric described in Section 5.7.4, “List metrics”.

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.

[Note]Note

Cloud Monitoring currently limits to 1000 data points returned per request. If all your data is not returned, break your request into multiple requests across smaller time ranges.

To control the data points returned in the response body, specify the following required URI parameters.

 

Fetch Data Points URI Parameters

from=fromTimeStamp

The timestamp marking 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 to milliseconds.Required.

to=toTimeStamp

The timestamp marking 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 to milliseconds.Required.

points=numberPoints

The number of points you want in the results. Either points or resolution is required. If both are absent, the query will not validate and will return an error.

For more information about querying by points, see Section 5.7.2, “Data granularity”.

resolution=granularity

The granularity of data to query. Valid values include: FULL, MIN5, MIN20, MIN60, MIN240 or MIN1440. Either points or resolution is required. If both are absent, the query will not validate and will return an error.

For more information about querying by resolution, see Section 5.7.2, “Data granularity”.

select=stats

The stats that you want returned for the data. The stats available for selection are average, variance, min and max. By default, the response includes the average stat 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.

The following examples show XML and JSON responses for this operation.

The following table describes the list of default fields returned for each full resolution data point:

Table 5.7. Fetch data points: full resolution response fields.
Name Description
numPoints The number of points. This is 1 for full resolution data.
average Numerical value. This is the value of raw sample itself.
timestamp The timestamp at which the metric was collected.

 

Example 5.41. Fetch data points: full resolution response in XML.

<?xml version="1.0" encoding="utf-8"?>
<container>
    <values>
        <rollupmetric>
            <numPoints>1</numPoints>
            <average>4</average>
            <timestamp>1335744000000</timestamp>
        </rollupmetric>
        <rollupmetric>
            <numPoints>1</numPoints>
            <average>6</average>
            <timestamp>1335744000030</timestamp>
        </rollupmetric>
    </values>
    <metadata>
        <count>2</count>
        <limit />
        <marker />
        <next_marker />
        <next_href />
    </metadata>
</container>


 

Example 5.42. Fetch data points: full resolution response in JSON.

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


The following table describes the list of default fields returned for each rollup data point:

Table 5.8. Fetch data points, rollup response fields.
Name Description
numPoints The number of points the rollup represents.
average The average of all the points in the rollup.
timestamp The start timestamp of the window from where the rollup happened.

 

Example 5.43. Fetch data points: rollup response in XML.

<?xml version="1.0" encoding="utf-8"?>
<container>
    <values>
        <rollupmetric>
            <numPoints>1141</numPoints>
            <average>4.1</average>
            <timestamp>1335744000000</timestamp>
        </rollupmetric>
        <rollupmetric>
            <numPoints>2880</numPoints>
            <average>6.05</average>
            <timestamp>1335830400000</timestamp>
        </rollupmetric>
    </values>
    <metadata>
        <count>2</count>
        <limit />
        <marker />
        <next_marker />
        <next_href />
    </metadata>
</container>


 

Example 5.44. Fetch data points: rollup response in JSON.

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


The following JSON example shows the same response as above, but with user selected stats variance and max. (The XML response is intentionally skipped for brevity.)

The following table shows the list of optional fields that are displayed based on the select parameter supplied with the URI. Note that even for full resolution responses, these fields can be selected. (They won't have much meaning but the response is presented in the same format for uniformity purposes.)

Table 5.9. Fetch data points, optional response fields.
Name Description
variance The variance computed over the points in the rollup.
min The minimum value observed in the rollup.
max The maximum value observed in the rollup.

 

Example 5.45. Fetch data points: rollup response with selected stats in JSON.

        {
    "values": [
        {
            "numPoints": 1141,
            "variance": 8.43710608512335,
            "max": 9,
            "timestamp": 1335744000000
        },
        {
            "numPoints": 2880,
            "variance": 8.25,
            "max": 9,
            "timestamp": 1335830400000
        }
    ],
    "metadata": {
        "count": 2,
        "limit": null,
        "marker": null,
        "next_marker": null,
        "next_href": null
    }
}

        



loading table of contents...