Cloud Monitoring ListTimeSeries Request Generator
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).
Attribution
MUST READ: Before executing any gcloud, REST API, or MCP command, you
MUST read Usage Attribution. For commands executed
directly in the terminal (never in generated scripts, Terraform, or user code),
prefix gcloud with
CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:cloud-monitoring-list-time-series-request)"
and append agent-skills/1.0 (skill:cloud-monitoring-list-time-series-request) to User-Agent headers.
CRITICAL RULES
- Mandatory Project ID Clarification: You MUST ensure the GCP Project ID
is present in the user prompt, input payload, or environment context (such
as via
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.
Workflow
Inspect Metric Metadata
- Use Provided Metric Metadata First: If the user's prompt already
includes metric metadata such as
metric.type, metricKind, valueType,
resource types, or label keys, use those values directly instead of calling
API tools.
- Discover Missing Metadata: If exact metric descriptors including
metric.type, metricKind, and valueType are missing or underspecified,
resolve the target metric's descriptor using one of these paths:
- Vague Query: If the prompt is vague, such as asking for VM CPU
usage, use the
cloud-monitoring-metric-selection skill first to
identify the specific metric type.
- Known Metric Type: If you already have the specific metric type name
such as
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.
- Fallback: If the MCP tool cannot be configured, fall back to making
a direct Cloud Monitoring API call.
- Identify Key Fields: From the retrieved descriptor, identify key schema
attributes:
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.
Construct Monitoring Filter
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:
- Prefix resource-level dimensions, such as instance ID, zone, project,
database ID, or subscription ID, with the
resource.labels. prefix. For
example:
resource.labels.instance_id = "123456789"
resource.labels.database_id = "my-project:my-instance"
- Prefix metric-level dimensions, such as state, command, response code,
or instance name metadata when stored on the metric, with the
metric.labels. prefix. For example:
metric.labels.state != "free"
metric.labels.instance_name = "instance-1"
Resource Name versus ID Resolution:
- If the user specifies a human-readable GCE VM instance name such as
"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".
- Do NOT use
resource.metadata.name or resource.metadata.*. This
prefix is invalid in Cloud Monitoring filter syntax.
- Do NOT assign a string instance name directly to
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".
Choose Aggregation Structure
Select the perSeriesAligner, crossSeriesReducer, groupByFields, and
alignmentPeriod according to the metric properties and visualization goal:
- Consult the Aggregations Reference: You MUST include both
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".
- Grouping Fields and Resource Granularity: When
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.
- Alignment Period Determination: Calculate the query lookback duration
from
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:
- Duration <= 110 minutes: Set
alignmentPeriod = "60s".
- Duration <= 23 hours: Set
alignmentPeriod = "300s".
- Duration <= 6 days: Set
alignmentPeriod = "3600s".
- Duration <= 23 days: Set
alignmentPeriod = "10800s".
- Duration <= 80 days: Set
alignmentPeriod = "21600s".
- Duration <= 180 days: Set
alignmentPeriod = "43200s".
- Duration <= 350 days: Set
alignmentPeriod = "86400s".
- Duration <= 500 days: Set
alignmentPeriod = "172800s".
- Omission Rule:
alignmentPeriod is omitted only when
perSeriesAligner is set to ALIGN_NONE.
Format Valid Request
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 Requirements: Populate the
aggregation parameters with the
perSeriesAligner, crossSeriesReducer, alignmentPeriod, and optional
groupByFields values determined during aggregation selection.
- Interval Requirements:
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.
- Alignment Period Requirement: Determine
alignmentPeriod from the
lookback duration of endTime minus startTime using the mapping above.
For the default one-hour lookback interval, alignmentPeriod is "60s".
- View Requirement: MUST default to
"FULL" when time series data points
are needed, or "HEADERS" when inspecting metadata and series identities
only.
Validate Request via list_timeseries MCP Tool
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.
References
1---2description: 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.3metadata:4 source: https://skillmd.com/skills/h3y6e/cloud-monitoring-list-time-series-request5 category: CloudObservabilityAndMonitoring6 github-path: skills/cloud/cloud-monitoring-list-time-series-request7 github-ref: refs/heads/main8 github-repo: https://github.com/google/skills9 github-tree-sha: 0cd56e66ebce2ad1c58723a384ee02a0edba164410 version: 1.0.111name: cloud-monitoring-list-time-series-request12---1314# Cloud Monitoring ListTimeSeries Request Generator1516Use this skill to translate any Cloud Monitoring metric descriptor into valid,17production-ready `ListTimeSeries` REST API query parameters (`name`, `filter`,18`interval.startTime`, `interval.endTime`, `aggregation.*`, `view`).1920## Attribution2122**MUST READ**: Before executing any `gcloud`, REST API, or MCP command, you23MUST read [Usage Attribution](references/attribution.md). For commands executed24directly in the terminal (never in generated scripts, Terraform, or user code),25prefix `gcloud` with26`CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:cloud-monitoring-list-time-series-request)"`27and append `agent-skills/1.0 (skill:cloud-monitoring-list-time-series-request)` to `User-Agent` headers.2829## CRITICAL RULES3031* **Mandatory Project ID Clarification**: You MUST ensure the GCP Project ID32 is present in the user prompt, input payload, or environment context (such33 as via `gcloud config get-value project`). If the Project ID is missing and34 cannot be resolved, you MUST ask the user to clarify it before generating or35 executing `ListTimeSeries` requests. Do NOT use placeholders for project36 names.3738## Workflow3940### Inspect Metric Metadata41421. **Use Provided Metric Metadata First**: If the user's prompt already43 includes metric metadata such as `metric.type`, `metricKind`, `valueType`,44 resource types, or label keys, use those values directly instead of calling45 API tools.462. **Discover Missing Metadata**: If exact metric descriptors including47 `metric.type`, `metricKind`, and `valueType` are missing or underspecified,48 resolve the target metric's descriptor using one of these paths:49 * **Vague Query**: If the prompt is vague, such as asking for VM CPU50 usage, use the `cloud-monitoring-metric-selection` skill first to51 identify the specific metric type.52 * **Known Metric Type**: If you already have the specific metric type name53 such as `compute.googleapis.com/instance/cpu/utilization`, but need its54 descriptor, call the `list_metric_descriptors` MCP tool. If the tool is55 missing, refer to the `cloud-monitoring-metric-selection` skill to56 configure the Cloud Monitoring MCP server.57 * **Fallback**: If the MCP tool cannot be configured, fall back to making58 a direct Cloud Monitoring API call.593. **Identify Key Fields**: From the retrieved descriptor, identify key schema60 attributes:61 * **`type`**: The Cloud Monitoring metric type string.62 * **`metricKind`**: `GAUGE`, `DELTA`, or `CUMULATIVE`.63 * **`valueType`**: `INT64`, `DOUBLE`, `DISTRIBUTION`, or `BOOL`.64 * **`monitoredResourceTypes`**: Compatible `resource.type` strings, for65 example `["cloudsql_database", "cloudsql_instance"]`. If multiple66 resource types are listed, select the specific `resource.type` that67 matches the target granularity of the user's request.6869--------------------------------------------------------------------------------7071### Construct Monitoring Filter7273The `filter` parameter is a mandatory string in Cloud Monitoring syntax that74restricts the query to a single `metric.type` and optional resource and metric75labels:76771. **Single Metric Type Restriction**: Every `filter` MUST specify exactly one78 `metric.type` clause using an equality operator. For example:79 * `metric.type = "compute.googleapis.com/instance/cpu/utilization"`802. **Monitored Resource Type Filter**: MUST include the `resource.type` filter81 when the target resource granularity is known, preventing collisions across82 services that share metric types or sub-resources. For example:83 * `metric.type = "cloudsql.googleapis.com/database/cpu/utilization" AND84 resource.type = "cloudsql_database"`853. **Preserve User Literals and IDs**: You MUST use literal resource names,86 IDs, zones, and project parameters provided by the user without alteration.87 Do NOT override or replace user-specified identifiers with active resources88 found during metric metadata discovery unless explicitly requested.89904. **Label Type Prefixing**:9192 * Prefix resource-level dimensions, such as instance ID, zone, project,93 database ID, or subscription ID, with the `resource.labels.` prefix. For94 example:95 * `resource.labels.instance_id = "123456789"`96 * `resource.labels.database_id = "my-project:my-instance"`97 * Prefix metric-level dimensions, such as state, command, response code,98 or instance name metadata when stored on the metric, with the99 `metric.labels.` prefix. For example:100 * `metric.labels.state != "free"`101 * `metric.labels.instance_name = "instance-1"`1021035. **Resource Name versus ID Resolution**:104105 * If the user specifies a human-readable GCE VM instance name such as106 `"instance-1"`, but `resource.labels.instance_id` expects a numeric ID,107 you MUST filter using either `metric.labels.instance_name =108 "instance-1"` or `metadata.system_labels.name = "instance-1"`.109 * Do NOT use `resource.metadata.name` or `resource.metadata.*`. This110 prefix is invalid in Cloud Monitoring filter syntax.111 * Do NOT assign a string instance name directly to112 `resource.labels.instance_id` unless the resource type explicitly uses113 string IDs.1141156. **Database Identifier Labels**: Database labels such as `database_id` for116 Cloud SQL and Spanner, or `dataset_id` for BigQuery, use composite keys117 formatted as `<project_id>:<instance_name>`. For example:118 `resource.labels.database_id = "my-project:foo"`.1191207. **Ops Agent Metrics State Label Filtering**: For121 `agent.googleapis.com/memory/percent_used` and122 `agent.googleapis.com/disk/percent_used` metrics, you MUST use123 `metric.labels.state != "free"`. Do NOT filter by `metric.labels.state =124 "used"`.125126--------------------------------------------------------------------------------127128### Choose Aggregation Structure129130Select the `perSeriesAligner`, `crossSeriesReducer`, `groupByFields`, and131`alignmentPeriod` according to the metric properties and visualization goal:1321331. **Consult the Aggregations Reference**: You MUST include both134 `perSeriesAligner` and `crossSeriesReducer` in the `aggregation` query135 parameters of every request. Read and follow the136 [Cloud Monitoring ListTimeSeries Basic Aggregations Reference](references/basic_aggregations.md)137 to select the exact `perSeriesAligner` and `crossSeriesReducer` combinations138 for your metric's Metric Kind and Value Type pairing, and to apply mandatory139 SRE rules for utilization metrics, counters, distributions, and state-based140 gauges such as memory filtered by `state != "free"`.1412. **Grouping Fields and Resource Granularity**: When `crossSeriesReducer` is142 specified as anything other than `REDUCE_NONE`, list the exact labels to143 preserve. When querying multi-instance resources like VMs, databases, or144 subscriptions, include the primary resource identifier in `groupByFields`.145 For example, use `resource.labels.instance_id` for VMs or146 `resource.labels.database_id` for databases. This prevents collapsing147 separate resource streams into a single global aggregate.1483. **Alignment Period Determination**: Calculate the query lookback duration149 from `endTime` minus `startTime`, ensuring `startTime` precedes `endTime`.150 If `endTime <= startTime`, flag an error before computing duration. Set151 `alignmentPeriod` according to Cloud Console default fine granularity152 standards:153 * **Duration <= 110 minutes**: Set `alignmentPeriod = "60s"`.154 * **Duration <= 23 hours**: Set `alignmentPeriod = "300s"`.155 * **Duration <= 6 days**: Set `alignmentPeriod = "3600s"`.156 * **Duration <= 23 days**: Set `alignmentPeriod = "10800s"`.157 * **Duration <= 80 days**: Set `alignmentPeriod = "21600s"`.158 * **Duration <= 180 days**: Set `alignmentPeriod = "43200s"`.159 * **Duration <= 350 days**: Set `alignmentPeriod = "86400s"`.160 * **Duration <= 500 days**: Set `alignmentPeriod = "172800s"`.161 * **Omission Rule**: `alignmentPeriod` is omitted only when162 `perSeriesAligner` is set to `ALIGN_NONE`.163164--------------------------------------------------------------------------------165166### Format Valid Request167168Present the generated `ListTimeSeries` REST query parameters. For example:169170```json171{172 "name": "projects/<project_id>",173 "filter": "metric.type = \"<metric_type>\" AND resource.type = \"<resource_type>\"",174 "interval": {175 "startTime": "<iso_8601_start>",176 "endTime": "<iso_8601_end>"177 },178 "aggregation": {179 "alignmentPeriod": "60s",180 "perSeriesAligner": "ALIGN_RATE",181 "crossSeriesReducer": "REDUCE_SUM",182 "groupByFields": [183 "resource.labels.zone"184 ]185 },186 "view": "FULL"187}188```189190* **Aggregation Requirements**: Populate the `aggregation` parameters with the191 `perSeriesAligner`, `crossSeriesReducer`, `alignmentPeriod`, and optional192 `groupByFields` values determined during aggregation selection.193* **Interval Requirements**: `startTime` and `endTime` MUST be valid RFC 3339194 and ISO 8601 timestamps such as `"YYYY-MM-DDTHH:MM:SSZ"`. If not explicitly195 provided by the user, dynamically compute a one-hour lookback interval196 ending at the current time, where `endTime` is the present moment and197 `startTime` is one hour prior. Do NOT hardcode static dates from examples.198* **Alignment Period Requirement**: Determine `alignmentPeriod` from the199 lookback duration of `endTime` minus `startTime` using the mapping above.200 For the default one-hour lookback interval, `alignmentPeriod` is `"60s"`.201* **View Requirement**: MUST default to `"FULL"` when time series data points202 are needed, or `"HEADERS"` when inspecting metadata and series identities203 only.204205--------------------------------------------------------------------------------206207### Validate Request via list_timeseries MCP Tool208209You MUST validate the generated request parameters against live Cloud Monitoring210telemetry before returning the final output. Call the `list_timeseries` MCP tool211passing all generated query parameters (`name`, `filter`, `interval`,212`aggregation`). When validating you MUST set `view="HEADERS"` to minimize213latency and payload size while verifying request structure. A response without214API errors confirms that your filter and aggregation settings are valid.215216If the `list_timeseries` tool is unavailable, fall back to a direct API call.217218--------------------------------------------------------------------------------219220## References221222* [Cloud Monitoring ListTimeSeries Basic Aggregations Reference](references/basic_aggregations.md)223* [Cloud Monitoring Monitored Resource Types Reference](https://docs.cloud.google.com/monitoring/api/resources.md.txt)224* [Cloud Monitoring Filter Syntax](https://docs.cloud.google.com/monitoring/api/v3/filters.md.txt)225* [Cloud Monitoring REST API Reference: projects.timeSeries.list](https://docs.cloud.google.com/monitoring/api/ref_v3/rest/v3/projects.timeSeries/list.md.txt)