/cloud-monitoring-list-time-series-request

name: cloud-monitoring-list-time-series-request
metadata:
  category: CloudObservabilityAndMonitoring
description: >-
  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.

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`).

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

1. **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. 2. **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. 3. **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:

1. **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"`

2. **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"` 3. **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.

4. **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"`

5. **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.

6. **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"`.

7. **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"`.

---------------------------------------------------