Generates valid Cloud Monitoring ListTimeSeries requests and aggregation specifications from metric descriptors and resource parameters. Use when asked to create, generate, format, or build ListTimeSeries requests, JSON payloads, filter expressions, or aligner/reducer aggregations for Cloud Monitoring metrics and charts. Don't use for metric discovery or metric selection.
Permissions
Files
Generates valid Cloud Monitoring ListTimeSeries requests and aggregation specifications from metric descriptors and resource parameters. Use when asked to create, generate, format, or build ListTimeSeries requests, JSON payloads, filter expressions, or aligner/reducer aggregations for Cloud Monitoring metrics and charts. Don't use for metric discovery or metric selection.
Use this skill to translate any Cloud Monitoring metric descriptor into valid,
production-ready ListTimeSeries REST API query parameters (name, filter,
interval.startTime, interval.endTime, aggregation.*, view).
Version history
gcloud config get-value project). If the Project ID is missing and
cannot be resolved, you MUST ask the user to clarify it before generating or
executing ListTimeSeries requests. Do NOT use placeholders for project
names.metric.type, metricKind, valueType,
resource types, or label keys, use those values directly instead of calling
API tools.metric.type, metricKind, and valueType are missing or underspecified,
resolve the target metric's descriptor using one of these paths:
cloud-monitoring-metric-selection skill first to
identify the specific metric type.compute.googleapis.com/instance/cpu/utilization, but need its
descriptor, call the list_metric_descriptors MCP tool. If the tool is
missing, refer to the cloud-monitoring-metric-selection skill to
configure the Cloud Monitoring MCP server.type: The Cloud Monitoring metric type string.metricKind: GAUGE, DELTA, or CUMULATIVE.valueType: INT64, DOUBLE, DISTRIBUTION, or BOOL.monitoredResourceTypes: Compatible resource.type strings, for
example ["cloudsql_database", "cloudsql_instance"]. If multiple
resource types are listed, select the specific resource.type that
matches the target granularity of the user's request.The filter parameter is a mandatory string in Cloud Monitoring syntax that
restricts the query to a single metric.type and optional resource and metric
labels:
Single Metric Type Restriction: Every filter MUST specify exactly one
metric.type clause using an equality operator. For example:
metric.type = "compute.googleapis.com/instance/cpu/utilization"Monitored Resource Type Filter: MUST include the resource.type filter
when the target resource granularity is known, preventing collisions across
services that share metric types or sub-resources. For example:
metric.type = "cloudsql.googleapis.com/database/cpu/utilization" AND resource.type = "cloudsql_database"Preserve User Literals and IDs: You MUST use literal resource names, IDs, zones, and project parameters provided by the user without alteration. Do NOT override or replace user-specified identifiers with active resources found during metric metadata discovery unless explicitly requested.
Label Type Prefixing:
resource.labels. prefix. For
example:
resource.labels.instance_id = "123456789"resource.labels.database_id = "my-project:my-instance"metric.labels. prefix. For example:
metric.labels.state != "free"metric.labels.instance_name = "instance-1"Resource Name versus ID Resolution:
"instance-1", but resource.labels.instance_id expects a numeric ID,
you MUST filter using either metric.labels.instance_name = "instance-1" or metadata.system_labels.name = "instance-1".resource.metadata.name or resource.metadata.*. This
prefix is invalid in Cloud Monitoring filter syntax.resource.labels.instance_id unless the resource type explicitly uses
string IDs.Database Identifier Labels: Database labels such as database_id for
Cloud SQL and Spanner, or dataset_id for BigQuery, use composite keys
formatted as <project_id>:<instance_name>. For example:
resource.labels.database_id = "my-project:foo".
Ops Agent Metrics State Label Filtering: For
agent.googleapis.com/memory/percent_used and
agent.googleapis.com/disk/percent_used metrics, you MUST use
metric.labels.state != "free". Do NOT filter by metric.labels.state = "used".
Select the perSeriesAligner, crossSeriesReducer, groupByFields, and
alignmentPeriod according to the metric properties and visualization goal:
perSeriesAligner and crossSeriesReducer in the aggregation query
parameters of every request. Read and follow the
Cloud Monitoring ListTimeSeries Basic Aggregations Reference
to select the exact perSeriesAligner and crossSeriesReducer combinations
for your metric's Metric Kind and Value Type pairing, and to apply mandatory
SRE rules for utilization metrics, counters, distributions, and state-based
gauges such as memory filtered by state != "free".crossSeriesReducer is
specified as anything other than REDUCE_NONE, list the exact labels to
preserve. When querying multi-instance resources like VMs, databases, or
subscriptions, include the primary resource identifier in groupByFields.
For example, use resource.labels.instance_id for VMs or
resource.labels.database_id for databases. This prevents collapsing
separate resource streams into a single global aggregate.endTime minus startTime, ensuring startTime precedes endTime.
If endTime <= startTime, flag an error before computing duration. Set
alignmentPeriod according to Cloud Console default fine granularity
standards:
alignmentPeriod = "60s".alignmentPeriod = "300s".alignmentPeriod = "3600s".alignmentPeriod = "10800s".alignmentPeriod = "21600s".alignmentPeriod = "43200s".alignmentPeriod = "86400s".alignmentPeriod = "172800s".alignmentPeriod is omitted only when
perSeriesAligner is set to ALIGN_NONE.Present the generated ListTimeSeries REST query parameters. For example:
{
"name": "projects/<project_id>",
"filter": "metric.type = \"<metric_type>\" AND resource.type = \"<resource_type>\"",
"interval": {
"startTime": "<iso_8601_start>",
"endTime": "<iso_8601_end>"
},
"aggregation": {
"alignmentPeriod": "60s",
"perSeriesAligner": "ALIGN_RATE",
"crossSeriesReducer": "REDUCE_SUM",
"groupByFields": [
"resource.labels.zone"
]
},
"view": "FULL"
}
aggregation parameters with the
perSeriesAligner, crossSeriesReducer, alignmentPeriod, and optional
groupByFields values determined during aggregation selection.startTime and endTime MUST be valid RFC 3339
and ISO 8601 timestamps such as "YYYY-MM-DDTHH:MM:SSZ". If not explicitly
provided by the user, dynamically compute a one-hour lookback interval
ending at the current time, where endTime is the present moment and
startTime is one hour prior. Do NOT hardcode static dates from examples.alignmentPeriod from the
lookback duration of endTime minus startTime using the mapping above.
For the default one-hour lookback interval, alignmentPeriod is "60s"."FULL" when time series data points
are needed, or "HEADERS" when inspecting metadata and series identities
only.You MUST validate the generated request parameters against live Cloud Monitoring
telemetry before returning the final output. Call the list_timeseries MCP tool
passing all generated query parameters (name, filter, interval,
aggregation). When validating you MUST set view="HEADERS" to minimize
latency and payload size while verifying request structure. A response without
API errors confirms that your filter and aggregation settings are valid.
If the list_timeseries tool is unavailable, fall back to a direct API call.
In these kits
More from @google
Works with
Claude, Codex, Cursor & more