cloud-monitoring-promql-query
Generates valid PromQL queries from Cloud Monitoring metric descriptors and resource parameters.
Skill by googleOfficial
Chalk Labs
Need help deploying cloud-monitoring-promql-query?
Chalk Labs sets up agents like this inside real teams: connected to your tools, tested on your data, with a human in the loop where it matters.
Install
Works with Claude Code, Claude apps, Codex, Cursor, Gemini CLI, GitHub Copilot, VS Code, OpenCode, Goose, Windsurf. Read the repository before you give any tool access to your data.
npx agentmarket install skill/google-cloud-monitoring-promql-query
Asks which of your tools to add it to (Claude Code, Codex, Cursor, VS Code, Windsurf, Gemini CLI, Claude Desktop) and shows the change first. See https://agentmart.dev/cli.
Get the weekly diff
The weekly diff: one email a week with new agent tools, notable updates and grade changes, plus security alerts for tools you follow. Double opt-in, one-click unsubscribe.
About
Use cases: writing
Reviews
Write a reviewNo reviews yet. Installed it? Reviews come from verified installers only. How reviews work
Permissions
What this skill can do and what it asks for, from its SKILL.md. Checked Oct 25, 2026.
- Tools
- No tools found
- Secrets
- None asked for
- Install scripts
- None found
- Runs as
- Python package
Network hosts it talks to 1
codeload.github.com· found in install command
Files it touches
~/.claude/skills/cloud-monitoring-promql-query
What's inside
- Skill name
cloud-monitoring-promql-query- Description
- 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.
- License
- Apache-2.0
- Metadata
- version: 1.0.1 · category: CloudObservabilityAndMonitoring
- Instructions
- 195 lines in SKILL.md · view on GitHub
Before installing
- Ships executable scripts
- Instructions call the network
Files (6)
- SKILL.md
- attribution.md · references/
- basic_aggregations.md · references/
- promql_error_recovery.md · references/
- validate_promql.py · scripts/
- validate_promql_test.py · scripts/
SKILL.md (first lines)
# 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](references/attribution.md). 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`):
```bash
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](references/basic_aggregations.md)
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(...))`.From google/skills, Apache-2.0.
Signals
- Stars
- 21,542
- Forks
- 1,821
- Open issues
- 21
- Last commit (this folder)
- Oct 19, 2026 (29 days ago)
From GitHub (fetched Oct 24, 2026).
Details
- Version
- 1.0.1
- License
- Apache-2.0
- Repository
- github.com/google/skills
- First seen
- Oct 24, 2026
- Last checked
- Oct 24, 2026
- Source
- GitHubgithub-graphql
Done for you
Rather not set it up yourself?
Chalk Labs scopes, builds and runs agents for your team: the task audit, the eval harness, the integrations and the weekly ops report. Fixed scope, priced before we start.
See how we build AI agents →Read the case studies
Chalk Labs is a two-founder AI and growth studio. We build AI agents, CRMs and MVPs for Web3 and AI companies, and have shipped 50+ product and token launches.
- launches shipped
- 50+
- launches shipped
- media placements
- 500+
- media placements
- founders on every account
- 2
- founders on every account
Press we've placed: Forbes · CoinDesk · Decrypt · Cointelegraph · The Block
Rahil Jain, Co-founder, Chalk Labs. Ex-Goldman Sachs engineer. You talk to the person who builds it.
Get cloud-monitoring-promql-query running in your business
Tell us what you want to automate. A founder replies within one working day with a plan, not a pitch deck.
Cite this page
cloud-monitoring-promql-query skill. Agent Mart. https://agentmart.dev/skills/google-cloud-monitoring-promql-query (last updated 2026-10-24)