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.
Permissions
Files
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.
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.
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:
Version history
gcloud config get-value project to attempt to resolve it from the
environment.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.metric.type, metricKind, valueType,
or monitoredResourceTypes) or specific resource filter values, use those
values directly instead of calling the Cloud Monitoring API.metric.type, metricKind, valueType) are missing or underspecified,
resolve the target metric type's descriptor using one of these paths:
"VM CPU usage"),
use the cloud-monitoring-metric-selection skill first to identify the
specific metric type.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.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.To filter data by a specific resource instance, apply these resource rules and discovery protocols:
Monitored Resource Filter: Always include the
monitored_resource="<type>" filter in your query to prevent collisions
across services that share metric names.
monitored_resource="gae_app"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.
Resource Identifier Mapping:
version_id, cluster_name."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.project_id and sub-resource
labels. Example: database_id="{project_id}:{instance_name}".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.
The query structure and aggregation functions (such as rate,
histogram_quantile, sum, or avg) depend on the metric type and how it is
visualized.
topk(30, avg_over_time(...)).agent.googleapis.com/memory/percent_used and
agent.googleapis.com/disk/percent_used require {state!="free"}. Do
NOT filter by {state="used"}.Before presenting any PromQL queries, validate them using the linter:
Before executing the validation script (scripts/validate_promql.py), install
the required Python dependencies:
python3 -c "import promql_parser" || pip install promql-parser
/) to separate the domain from the path.
storage.googleapis.com/network/received_bytes_count -> domain
storage.googleapis.com, path network/received_bytes_count.) in the domain with
underscores (_).
storage.googleapis.com ->
storage_googleapis_com.) and slashes (/) in
the path with underscores (_).
network/received_bytes_count ->
network_received_bytes_count:).
storage_googleapis_com:network_received_bytes_countup -> up, http_requests_total ->
http_requests_totalvalueType is
DISTRIBUTION, append _bucket to the end of the normalized name.
cloudfunctions.googleapis.com/function/execution_times ->
cloudfunctions_googleapis_com:function_execution_times_bucket# or
//). Cloud Monitoring query translation collapses whitespace and can
cause code trailing a comment to be ignored or throw parsing errors.by (label)) only follow aggregation operators (such as sum, avg,
min, max, or count). Never place a grouping clause directly after
a metric selector.
metric{...} by (label)sum(rate(metric{...}[5m])) by (label)promql code block in your final response.python3 <path_to_skill>/scripts/validate_promql.py --query '<q1>' '<q2>'In these kits
More from @google
Works with
Claude, Codex, Cursor & more