cloud-monitoring-list-time-series-request

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
   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:

{
  "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
• Cloud Monitoring Monitored Resource Types Reference
• Cloud Monitoring Filter Syntax
• Cloud Monitoring REST API Reference: projects.timeSeries.list