AutoGineer
Generated banner for Cloud Monitoring Promql Query
Generated logo for Cloud Monitoring Promql Query

Cloud Monitoring Promql Query

GoogleOfficialPublished by Google

  • Skill
  • Tool integration
  • Cloud and DevOps
  • Apache-2.0
  • Low risk
  • Has scripts
Download ZIP

From the author

Generates valid PromQL queries from Cloud Monitoring metric descriptors and resource parameters. Use when asked to create, generate, write, or format PromQL queries, PromQL strings, or PromQL aggregations for Cloud Monitoring metrics and resources. Don't use for raw metric discovery or metric selection.
— the description by Google

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

This skill provides a structured workflow for translating Google Cloud Monitoring metric types into valid PromQL queries. It handles the normalization of metric names, selection of appropriate aggregation functions based on metric kind and value type, and ensures queries adhere to Cloud Monitoring's specific resource filtering requirements. The skill includes a validation step using a dedicated linter to ensure query correctness before output.

What it does

  • Normalizes Cloud Monitoring metric types into PromQL-compatible naming conventions.
  • Maps metric descriptors (GAUGE, DELTA, CUMULATIVE) to correct PromQL aggregation structures.
  • Enforces mandatory resource filtering to prevent cross-service metric collisions.
  • Validates generated queries using a local Python-based PromQL linter.
  • Handles complex distribution metrics by correctly appending bucket suffixes and applying quantile functions.
  • Provides a structured process for resolving project IDs and resource labels.

When to use it

  • When you need to write a PromQL query for a specific Google Cloud Monitoring metric.
  • When you need to aggregate Cloud Monitoring data (e.g., sum, average, or percentiles) using PromQL.
  • When you are unsure of the correct PromQL syntax for a specific Cloud Monitoring metric type.
  • When you need to ensure your PromQL query is syntactically valid before deployment.

Advantages

  • Ensures syntactic correctness through automated linter validation.
  • Standardizes the translation of Cloud Monitoring metric paths to PromQL names.
  • Prevents common errors like incorrect aggregation grouping or missing resource filters.
  • Provides clear guidance on handling complex metric types like distributions.

Usage examples

“Generate a PromQL query for compute.googleapis.com/instance/cpu/utilization for my project.”
The agent resolves the project ID, identifies the metric as a GAUGE, and returns a formatted PromQL query like 'compute_googleapis_com:instance_cpu_utilization' wrapped in a code block.
“Write a PromQL query to get the 95th percentile of execution times for my Cloud Function.”
The agent identifies the metric as a DISTRIBUTION type, applies the necessary rate and histogram_quantile functions, and returns the validated PromQL query.

Install

  1. Download the skill as a ZIP:

    https://mp-staging.autogineer.com/agent-skills/google/cloud-monitoring-promql-query/download

  2. Unzip it into the cross-client skills folder of your project:

    mkdir -p .agents/skills && unzip cloud-monitoring-promql-query.zip -d .agents/skills

Documentation by Google

Cloud Monitoring PromQL Generator

Use this skill to generate a valid PromQL query from any Cloud Monitoring metric type. This guide applies to all Cloud Monitoring metric types by mapping Cloud Monitoring metric and resource descriptors to PromQL structures.

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-promql-query)" and append agent-skills/1.0 (skill:cloud-monitoring-promql-query) to User-Agent headers.

Workflow

Resolve Project ID (CRITICAL & BLOCKING)

Before performing any other actions (such as searching code, reading references, or running validation), you MUST verify whether the Google Cloud Project ID is available:

  1. Check Prompt/Payload: Look for the Project ID in the user's prompt or input.

  2. Check Environment: If the Project ID is not present in the prompt, you MUST run gcloud config get-value project to attempt to resolve it from the environment.

  3. Ask for Clarification (BLOCKING): If the Project ID is not in the prompt AND the gcloud command fails, returns an empty string, or is unavailable, you MUST immediately stop. Do NOT generate a PromQL query, do not run the validation script, and do not use placeholders (like YOUR_PROJECT_ID). You must refuse to proceed and ask the user to provide the Project ID.

Inspect Metric and Resource Descriptors

  1. Use Provided Descriptors First: If the user's prompt already includes metric descriptor details (such as metric.type, metricKind, valueType, or monitoredResourceTypes) or specific resource filter values, use those values directly instead of calling the Cloud Monitoring API.

  2. Discover Missing Descriptors: If exact metric descriptors (metric.type, metricKind, valueType) are missing or underspecified, resolve the target metric type's descriptor using one of these paths:

    • Vague Query: If the prompt is vague (for example, "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 (for example, compute.googleapis.com/instance/cpu/utilization) but need its descriptor, call the google-cloud-monitoring: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 four 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 required for resource scoping and grouping.

Resolve Resource Filters & Discovery Protocol

To filter data by a specific resource instance, apply these resource rules and discovery protocols:

  1. Monitored Resource Filter: Always include the monitored_resource="<type>" filter in your query to prevent collisions across services that share metric names.

    • Example: monitored_resource="gae_app"

  2. Preserve User Literals (CRITICAL): ALWAYS use the literal resource names, namespaces, and IDs provided in the user's prompt. Do NOT override or replace these values with active resource names found during Cloud Monitoring discovery unless the user explicitly asked you to find active resources. Telemetry discovery must only be used to identify metric type names and label keys, not to override user input.

  3. Resource Identifier Mapping:

    • Direct & Specific Keys: Use the most specific resource identifier available. Example: version_id, cluster_name.

    • Name-to-ID Resolution: If the user filters by a resource name (such as "instance-1"), but the resource schema uses numeric IDs (like instance_id), use PromQL string name labels instead of numeric ID labels. Example: instance_name, metadata_system_name.

    • Composite Identifiers: For resources with hierarchical identifiers (such as Cloud SQL databases), format the filter as a single composite key. Do NOT split them into separate project_id and sub-resource labels. Example: database_id="{project_id}:{instance_name}".

  4. Resource Label Discovery: The google-cloud-monitoring:list_metric_descriptors tool only returns metric-specific labels. If the label schema for a monitored resource is unknown, fetch the resource descriptor directly from the Cloud Monitoring v3 REST API (projects.monitoredResourceDescriptors.get):

    TOKEN=$(gcloud auth application-default print-access-token 2>/dev/null || gcloud auth print-access-token)
curl -s -H "Authorization: Bearer ${TOKEN}" \
"https://monitoring.googleapis.com/v3/projects/{project_id}/monitoredResourceDescriptors/{monitored_resource_type}"

    An HTTP 200 OK response returns the MonitoredResourceDescriptor object containing the labels array with the exact resource label keys for that resource.

Choose Aggregation Structure & Defaults

The query structure and aggregation functions (such as rate, histogram_quantile, sum, or avg) depend on the metric type and how it is visualized.

  1. Consult the Reference: Consult the Cloud Monitoring to PromQL Basic Aggregations Reference as the single source of truth to map Cloud Monitoring properties (Metric Kind, Value Type, Aligner, Reducer) to their PromQL structures.

  2. SRE Aggregation & Visualization Rules:

    • Do NOT sum or average ratio/percentage utilization metrics (like CPU % or Memory limit utilization) across resource instances. Instead, keep them unaggregated (raw metric), group by instance, or wrap in topk(30, avg_over_time(...)).

    • State Label Filtering (CRITICAL): Only the metrics agent.googleapis.com/memory/percent_used and agent.googleapis.com/disk/percent_used require {state!="free"}. Do NOT filter by {state="used"}.

Format & Validate Query

Before presenting any PromQL queries, validate them using the linter:

Python Dependencies

Before executing the validation script (scripts/validate_promql.py), install the required Python dependencies:

python3 -c "import promql_parser" || pip install promql-parser
Validation Procedure

  1. Format Constraints:

    • Metric Name Normalization: Convert Cloud Monitoring metric types to PromQL metric names using this recipe:

      1. Split Domain and Path: Split the Cloud Monitoring metric type by the first slash (/) to separate the domain from the path.

        • Example: storage.googleapis.com/network/received_bytes_count -> domain storage.googleapis.com, path network/received_bytes_count

      2. Normalize Domain: Replace all periods (.) in the domain with underscores (_).

        • Example: storage.googleapis.com -> storage_googleapis_com

      3. Normalize Path: Replace all periods (.) and slashes (/) in the path with underscores (_).

        • Example: network/received_bytes_count -> network_received_bytes_count

      4. Join with Colon: Join the normalized domain and normalized path with a colon (:).

        • Example: storage_googleapis_com:network_received_bytes_count

      5. Native Prometheus Metrics: If the metric type has no slash, keep it as-is.

        • Example: up -> up, http_requests_total -> http_requests_total

      6. Distribution Suffix: If the metric's valueType is DISTRIBUTION, append _bucket to the end of the normalized name.

        • Example: cloudfunctions.googleapis.com/function/execution_times -> cloudfunctions_googleapis_com:function_execution_times_bucket

    • Ensure the final query is a single line with no comments (no # or //). Cloud Monitoring query translation collapses whitespace and can cause code trailing a comment to be ignored or throw parsing errors.

    • Grouping Clause Syntax: Ensure grouping clauses (such as by (label)) only follow aggregation operators (such as sum, avg, min, max, or count). Never place a grouping clause directly after a metric selector.

      • Incorrect: metric{...} by (label)

      • Correct: sum(rate(metric{...}[5m])) by (label)

    • Fenced Output Code Block: ALWAYS wrap the final verified PromQL query in a fenced promql code block in your final response.

  2. Linter Verification:

    • Validate all generated queries in a single batch: python3 <path_to_skill>/scripts/validate_promql.py --query '<q1>' '<q2>'

    • If validation fails, read PromQL Error Recovery Guide to diagnose and fix common type mismatches and syntax errors before repeating the loop.

References

Files

scripts/validate_promql_test.py

#!/usr/bin/env python3
"""Unit tests and stress tests for validate_promql.py."""

import unittest
import validate_promql


class ValidatePromqlTest(unittest.TestCase):

  # --- Valid PromQL Query Tests ---

  def test_valid_counter_query(self):
    query = (
        'sum(rate(compute_googleapis_com:instance_disk_read_bytes_count'
        '{monitored_resource="gce_instance"}[5m]))'
    )
    self.assertEqual(validate_promql.validate_promql_query(query), ([], []))

  def test_valid_increase_counter_query(self):
    query = (
        'sum(increase(spanner_googleapis_com:api_request_count'
        '{monitored_resource="spanner_instance"}[1h]))'
    )
    self.assertEqual(validate_promql.validate_promql_query(query), ([], []))

  def test_valid_irate_counter_query(self):
    query = (
        'sum(irate(loadbalancing_googleapis_com:https_request_count'
        '{monitored_resource="https_lb_rule"}[5m]))'
    )
    self.assertEqual(validate_promql.validate_promql_query(query), ([], []))

  def test_valid_histogram_query(self):
    query = (
        'histogram_quantile(0.95,'
        ' sum(rate(spanner_googleapis_com:query_latency_bucket'
        '{monitored_resource="spanner_instance"}[5m])) by (le, instance_id))'
    )
    self.assertEqual(validate_promql.validate_promql_query(query), ([], []))

  def test_valid_binary_expression(self):
    query = (
        'sum(rate(compute_googleapis_com:instance_disk_read_bytes_count'
        '{monitored_resource="gce_instance"}[5m])) /'
        ' sum(rate(compute_googleapis_com:instance_disk_write_bytes_count'
        '{monitored_resource="gce_instance"}[5m]))'
    )
    self.assertEqual(validate_promql.validate_promql_query(query), ([], []))

  def test_valid_subquery(self):
    query = (
        'rate(compute_googleapis_com:instance_disk_read_bytes_count'
        '{monitored_resource="gce_instance"}[5m])[30m:1m]'
    )
    self.assertEqual(validate_promql.validate_promql_query(query), ([], []))

  def test_valid_boolean_query(self):
    query = (
        'pubsub_googleapis_com:subscription_delivery_latency_health_score{monitored_resource="pubsub_subscription",'
        ' subscription_id="sub-1"} == 0'
    )
    self.assertEqual(validate_promql.validate_promql_query(query), ([], []))

  def test_valid_topk_aggregation(self):
    query = (
        'topk(10,'
        ' avg_over_time(agent_googleapis_com:memory_percent_used'
        '{monitored_resource="gce_instance", state!="free"}[5m]))'
    )
    self.assertEqual(validate_promql.validate_promql_query(query), ([], []))

  def test_valid_bottomk_aggregation(self):
    query = (
        'bottomk(5,'
        ' sum(rate(compute_googleapis_com:instance_disk_read_bytes_count'
        '{monitored_resource="gce_instance"}[5m])) by (instance_id))'
    )
    self.assertEqual(validate_promql.validate_promql_query(query), ([], []))

  def test_valid_regex_label_matcher(self):
    query = (
        'sum(rate(compute_googleapis_com:instance_cpu_utilization_count'
        '{monitored_resource="gce_instance", instance_name=~"web-.*"}[5m]))'
    )
    self.assertEqual(validate_promql.validate_promql_query(query), ([], []))

  def test_valid_offset_modifier(self):
    query = (
        'sum(rate(compute_googleapis_com:instance_disk_read_bytes_count'
        '{monitored_resource="gce_instance"}[5m] offset 1d))'
    )
    self.assertEqual(validate_promql.validate_promql_query(query), ([], []))

  def test_valid_group_left_matching(self):
    query = (
        'sum(rate(error_count{monitored_resource="k8s_container"}[5m])) by'
        ' (method, service) / on (service) group_left(method)'
        ' sum(rate(total_requests{monitored_resource="k8s_container"}[5m]))'
        ' by (service)'
    )
    self.assertEqual(validate_promql.validate_promql_query(query), ([], []))

  # --- Invalid & Edge Case Tests ---

  def test_missing_monitored_resource(self):
    query = (
        'sum(rate(compute_googleapis_com:instance_disk_read_bytes_count'
        '{instance_id="123"}[5m]))'
    )
    errors, _ = validate_promql.validate_promql_query(query)
    self.assertTrue(
        any('monitored_resource' in err for err in errors),
        f'Expected monitored_resource error, got: {errors}',
    )

  def test_counter_not_wrapped(self):
    query = (
        'compute_googleapis_com:instance_disk_read_bytes_count'
        '{monitored_resource="gce_instance"}'
    )
    errors, warnings = validate_promql.validate_promql_query(query)
    self.assertFalse(errors, f'Expected no errors, got: {errors}')
    self.assertTrue(
        any('wrapped in rate() or increase()' in warn for warn in warnings),
        f'Expected counter wrapping warning, got: {warnings}',
    )

  def test_histogram_bucket_not_wrapped(self):
    query = (
        'spanner_googleapis_com:query_latency_bucket'
        '{monitored_resource="spanner_instance"}'
    )
    errors, _ = validate_promql.validate_promql_query(query)
    self.assertTrue(
        any('wrapped in histogram_quantile()' in err for err in errors),
        f'Expected histogram wrapping error, got: {errors}',
    )

  def test_invalid_grouping_clause(self):
    query = (
        'compute_googleapis_com:instance_cpu_utilization'
        '{monitored_resource="gce_instance"} by (instance_id)'
    )
    errors, _ = validate_promql.validate_promql_query(query)
    self.assertTrue(
        any('Syntax Error' in err for err in errors),
        f'Expected syntax error, got: {errors}',
    )

  def test_unclosed_bracket_syntax_error(self):
    query = (
        'compute_googleapis_com:instance_cpu_utilization'
        '{monitored_resource="gce_instance"'
    )
    errors, _ = validate_promql.validate_promql_query(query)
    self.assertTrue(
        any('Syntax Error' in err for err in errors),
        f'Expected syntax error, got: {errors}',
    )

  def test_multiple_selectors_one_missing_monitored_resource(self):
    query = (
        'sum(rate(compute_googleapis_com:instance_disk_read_bytes_count'
        '{monitored_resource="gce_instance"}[5m])) + '
        'sum(rate(compute_googleapis_com:instance_disk_write_bytes_count[5m]))'
    )
    errors, _ = validate_promql.validate_promql_query(query)
    self.assertTrue(
        any('monitored_resource' in err for err in errors),
        f'Expected monitored_resource error, got: {errors}',
    )

  def test_state_filtered_metric_missing_state_filter(self):
    # Test memory metric missing state filter
    query = (
        'avg(agent_googleapis_com:memory_percent_used'
        '{monitored_resource="gce_instance"})'
    )
    errors, _ = validate_promql.validate_promql_query(query)
    self.assertTrue(
        any('missing the \'state!="free"\'' in err for err in errors),
        f'Expected state filter missing error, got: {errors}',
    )

    # Test disk metric missing state filter
    query = (
        'avg(agent_googleapis_com:disk_percent_used'
        '{monitored_resource="gce_instance"})'
    )
    errors, _ = validate_promql.validate_promql_query(query)
    self.assertTrue(
        any('missing the \'state!="free"\'' in err for err in errors),
        f'Expected state filter missing error, got: {errors}',
    )

  def test_state_filtered_metric_using_state_used(self):
    # Test memory metric using state="used"
    query = (
        'avg(agent_googleapis_com:memory_percent_used'
        '{monitored_resource="gce_instance", state="used"})'
    )
    errors, _ = validate_promql.validate_promql_query(query)
    self.assertTrue(
        any('must not use \'state="used"\'' in err for err in errors),
        f'Expected state="used" error, got: {errors}',
    )

    # Test disk metric using state="used"
    query = (
        'avg(agent_googleapis_com:disk_percent_used'
        '{monitored_resource="gce_instance", state="used"})'
    )
    errors, _ = validate_promql.validate_promql_query(query)
    self.assertTrue(
        any('must not use \'state="used"\'' in err for err in errors),
        f'Expected state="used" error, got: {errors}',
    )

  def test_state_filtered_metric_valid_disk(self):
    query = (
        'avg(agent_googleapis_com:disk_percent_used'
        '{monitored_resource="gce_instance", state!="free"})'
    )
    self.assertEqual(validate_promql.validate_promql_query(query), ([], []))

  # --- Query Extractor Markdown & Macro Parsing Tests ---

  def test_extract_query(self):
    markdown = (
        'Here is the query:\n'
        '```promql\n'
        'sum(rate(compute_googleapis_com:instance_disk_read_bytes_count'
        '{monitored_resource="gce_instance"}[5m]))\n'
        '```\n'
        'Hope this helps!'
    )
    expected = (
        'sum(rate(compute_googleapis_com:instance_disk_read_bytes_count'
        '{monitored_resource="gce_instance"}[5m]))'
    )
    self.assertEqual(validate_promql.extract_query(markdown), expected)

  def test_extract_query_with_interval_macro(self):
    raw_query = (
        'sum(rate(compute_googleapis_com:instance_disk_read_bytes_count'
        '{monitored_resource="gce_instance"}[${__interval}]))'
    )
    expected = (
        'sum(rate(compute_googleapis_com:instance_disk_read_bytes_count'
        '{monitored_resource="gce_instance"}[5m]))'
    )
    extracted = validate_promql.extract_query(raw_query)
    self.assertEqual(extracted, expected)
    self.assertEqual(validate_promql.validate_promql_query(extracted), ([], []))

  def test_multi_query_validation(self):
    queries = [
        'compute_googleapis_com:instance_cpu_utilization{monitored_resource="gce_instance"}',
        'sum(rate(compute_googleapis_com:instance_disk_read_bytes_count{monitored_resource="gce_instance"}[5m]))',
    ]
    for q in queries:
      self.assertEqual(validate_promql.validate_promql_query(q), ([], []))


if __name__ == '__main__':
  unittest.main()

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs an MCP server, Needs Python

Security

What our scanner noticed· Low risk

  • Instructions that use the network
  • Scripts that your agent may run

This skill includes scripts that your agent may run. Read them before you use it.

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Published by
Google
Publisher
Google (Official)
Source
google/skills · skills/cloud/cloud-monitoring-promql-query · commit 2194d3b
Licence
Apache License 2.0 (redistribution allowed)
  • LICENSE (added by AutoGineer from LICENSE)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by Google.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download cloud-monitoring-promql-query.zip