banshee/cloud-collection/cloud/google/https/monitoring-metric

One Cloud Monitoring metric

Returns the newest value of the one time series a filter picks in Cloud Monitoring, over the last thirty minutes, aligned as chosen, and how old that value is, read through the Cloud Monitoring API with a service account that may only read. The generic form: any metric of any resource, picked by a filter set on the probe (the CPU of a Compute Engine instance, the connections of a Cloud SQL database, the requests of a load balancer). Three watches are offered, each one set on the probe.

Versions

Generic: the Cloud Monitoring API is one service, the same for every project. The collector reads its version v3.

How it works

google.token('https://www.googleapis.com/auth/monitoring.read'): an access token for the service account of protocol:google, kept fifty minutes in the probe's cache, encrypted on the poller. A token Google no longer takes answers 401, and the collector asks for a new one, once.
GET https://monitoring.googleapis.com/v3/projects/<google:project>/timeSeries?aggregation.alignmentPeriod=<google:alignment-period>s&aggregation.perSeriesAligner=<google:aligner>&filter=<google:filter>&interval.endTime=<now>&interval.startTime=<now − 30 min>&view=FULL, the token as Authorization: Bearer.

{"timeSeries": [{"metric": {"type": "compute.googleapis.com/instance/cpu/utilization", "labels": {"instance_name": "web-1"}}, "resource": {…}, "points": [{"interval": {"startTime": "2026-10-28T08:04:00Z", "endTime": "2026-10-28T08:05:00Z"}, "value": {"doubleValue": 0.125}}, …]}], "unit": "10^2.%"}

The filter picks one time series, in the syntax of Cloud Monitoring: metric.type = "compute.googleapis.com/instance/cpu/utilization" AND metric.labels.instance_name = "web-1". A filter that picks several stops the collector misconfigured, with a message that says to add the labels that pick one.
value is the newest point of the series, which Cloud Monitoring gives first: its doubleValue, or its int64Value, which JSON carries as a text. A boolean, a text or a distribution stops the collector misconfigured.
age is the time from the end of that point's period to now, in minutes, against the poller's clock: a value that stops coming in shows by its age.
The times are written in UTC from the poller's clock, 2026-10-28T07:35:00Z and 2026-10-28T08:05:00Z.
No series in the thirty minutes stops the collector unreachable: Cloud Monitoring answers a metric or a label it does not know with no series rather than with an error, and the message says so.
An alignment period under 60 seconds stops the collector misconfigured before anything leaves. A code 403 (the role missing, or the Cloud Monitoring API not enabled) stops it misconfigured; a code 400 (a filter Cloud Monitoring does not read) or 404 (the project unknown) too; any other code but 200 stops it unreachable. A key or a scope that Google refuses stops it misconfigured (access_denied, from google.token).

The key comes from protocol:google, a secret variable: google.token signs an assertion with it and sends only the assertion, to Google only. The token is a secret too, kept in the cache and sent in a header. The series is not secret.

Prerequisites

A service account of the project, with a key in JSON, the file Google gives, set in protocol:google:service-account-key.
The role Monitoring Viewer (roles/monitoring.viewer) given to it on the project: it reads the metrics and the settings of Cloud Monitoring, and nothing else. With the Google Cloud CLI: gcloud projects add-iam-policy-binding <project> --member=serviceAccount:<account e-mail> --role=roles/monitoring.viewer.
The poller reaches oauth2.googleapis.com and monitoring.googleapis.com in HTTPS, and its clock is right within a few minutes: Google refuses an assertion signed away from its own time. The certificates of Google are issued by public authorities: the profile "Standard" trusts them.
The types of the metrics and their labels are in Google's list "Google Cloud metrics", by service.

Variables

Name	Label	Says	Default
`google:project`	Project	the ID of the project, `my-project-123456`	—
`google:filter`	Filter	the monitoring filter that picks one time series	—
`google:aligner`	Aligner	`ALIGN_MEAN`, `ALIGN_MIN`, `ALIGN_MAX`, `ALIGN_SUM`, `ALIGN_RATE`, `ALIGN_DELTA` or `ALIGN_COUNT`	`ALIGN_MEAN`
`google:alignment-period`	Alignment period	the length of each period, in seconds, 60 at least	`60`

Outputs

Name	Label	Unit	Per instance
`value`	Value	that of the metric, which Cloud Monitoring gives with the answer and the collector does not declare	no
`age`	Age of the value	min	no

Watches

Name	Title	Kind	Defaults	Checked by default
`high`	Value too high	above a threshold, on `value`	no threshold: it raises nothing until thresholds are set on the probe	yes
`low`	Value too low	below a threshold, on `value`	no threshold	no
`stale`	Value not fresh	above a threshold, on `age`	warning above 15 min	yes

Limits

One time series per probe; the series are not reduced across labels (crossSeriesReducer).
The unit of the value is the metric's own: a utilization of Compute Engine is a fraction, 0.125 for 12.5 %; the screen shows none.
Not checked against a Google Cloud project: the route, its parameters, the aligners, the fields, and the order of the points (newest first) are those of the Cloud Monitoring API (projects.timeSeries.list, the schemas ListTimeSeriesResponse, TimeSeries, Point and TypedValue), read in its discovery document as Google publishes it with its client libraries; the role is that of "Cloud Monitoring IAM roles".