cloud-monitoring-list-time-series-request

---
name: cloud-monitoring-list-time-series-request
description: >-
license: Apache-2.0
---

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

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

### Choose Aggregation Structure

Select the `perSeriesAligner`, `crossSeriesReducer`, `groupByFields`, and
`alignmentPeriod` according to the metric properties and visualization goal:

1.  **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](references/basic_aggregations.md)
    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"`.
2.  **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.
3.  **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:

```json
{
  "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

*   [Cloud Monitoring ListTimeSeries Basic Aggregations Reference](references/basic_aggregations.md)
*   [Cloud Monitoring Monitored Resource Types Reference](https://docs.cloud.google.com/monitoring/api/resources.md.txt)
*   [Cloud Monitoring Filter Syntax](https://docs.cloud.google.com/monitoring/api/v3/filters.md.txt)
*   [Cloud Monitoring REST API Reference: projects.timeSeries.list](https://docs.cloud.google.com/monitoring/api/ref_v3/rest/v3/projects.timeSeries/list.md.txt)