5.8. Metrics

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.

Use the metrics API operations to create, view, and manage metrics resources

Concept: Metrics, in Monitoring key terms and concepts

Requirements: An entity and check

Next step: Learn about notification types

 5.8.1. 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 one".

The value presents cumulative statistics from the time the metric was created. The value keeps growing.

Examples

  • agent.network - rx-bytes

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:

  • agent.filesystem - used

 5.8.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.6. 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.7. 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.8.3. Data point expiration

Cloud 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

 5.8.4. Metrics API operations

MethodURIDescription
GET/entities/{entityId}/checks/{checkId}/metrics

Lists the metrics associated with the specified checkId.

GET/entities/{entityId}/checks/{checkId}/metrics/{metricName}/plot

Queries for all data points of metricName between two points in time.

 5.8.4.1. List metrics by check ID

 
MethodURIDescription
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]Note

Metrics generated by agent checks have no monitoring zone.

This table shows the possible response codes for this operation:

Response CodeNameDescription
200OK

The request completed.

400Bad request

The system received an invalid value in a request.

401Unauthorized

The system received a request from a user that is not authenticated.

403Forbidden

The system received a request that the user is not authorized to make.

405Method Not Allowed

The method specified in the request is not allowed for the resource. A list of valid methods for the requested resource is included in the response.

413Over Limit

The response body is too large.

500Internal Server Error

An unexpected condition was encountered.

503Service Unavailable

The system is experiencing heavy load or another system failure.

 5.8.4.1.1. Request

This table shows the header parameters for the list metrics by check id request:

NameTypeDescription

X-Auth-Token

​String

(Required)

A valid authentication token with administrative access. For details, see Retrieving an authentication token

This operation does not accept a request body.

 5.8.4.1.2. Response
 

Example 5.24. 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
    }
}

 5.8.4.2. Get data points by metric name

 
MethodURIDescription
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 below.

[Note]Note

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

This table shows the possible response codes for this operation:

Response CodeNameDescription
200OK

The request completed.

400Bad request

The system received an invalid value in a request.

401Unauthorized

The system received a request from a user that is not authenticated.

403Forbidden

The system received a request that the user is not authorized to make.

405Method Not Allowed

The method specified in the request is not allowed for the resource. A list of valid methods for the requested resource is included in the response.

413Over Limit

The response body is too large.

500Internal Server Error

An unexpected condition was encountered.

503Service Unavailable

The system is experiencing heavy load or another system failure.

 5.8.4.2.1. Request

This table shows the header parameters for the get data points by metric name request:

NameTypeDescription

X-Auth-Token

​String

(Required)

A valid authentication token with administrative access. For details, see Retrieving an authentication token

This table shows the URI parameters for the get data points by metric name request:

NameTypeDescription

{fromTimeStamp}

​String

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.

{toTimeStamp}

​String

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.

{numberPoints}

​String

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 Data granularity.

{granularity}

​String

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 Data granularity.

{stats}

​String

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.

This operation does not accept a request body.

 5.8.4.2.2. Response
 

Example 5.25. 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 5.26. 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
    }
}

This operation does not return a response body.



Contents Search
loading table of contents...