Cloud Monitoring Chart Generation
Generates Cloud Monitoring Server-Driven UI (SDUI) Widget and XyChart Protocol Buffer textprotos on Google Cloud from resolved PromQL or ListTimeSeries queries. Use when: - Generating valid google.monitoring.dashboard.v1.Widget textprotos, containing PrometheusQuery or TimeSeriesFilter datasets, for use with the Cloud Monitoring Dashboards API, gcloud CLI, or declarative dashboard definitions. - Synthesizing Server-Driven UI (SDUI) widget titles, axis labels, and plot types for Prometheus or ListTimeSeries queries. Don't use for: - Metric discovery or PromQL query generation. For those tasks, use the cloud-monitoring-metric-selection or cloud-monitoring-promql-query skills.
Get the complete skill folder, including its scripts and reference files.
When to use this skill
Use Cloud Monitoring Chart Generation when an AI agent needs a reusable SKILL.md workflow for this job: Generates Cloud Monitoring Server-Driven UI (SDUI) Widget and XyChart Protocol Buffer textprotos on Google Cloud from resolved PromQL or ListTimeSeries queries. Use when: - Generating valid google.monitoring.dashboard.v1.Widget textprotos, containing PrometheusQuery or TimeSeriesFilter datasets, for use with the Cloud Monitoring Dashboards API, gcloud CLI, or declarative dashboard definitions. - Synthesizing Server-Driven UI (SDUI) widget titles, axis labels, and plot types for Prometheus or ListTimeSeries queries. Don't use for: - Metric discovery or PromQL query generation. For those tasks, use the cloud-monitoring-metric-selection or cloud-monitoring-promql-query skills.
When not to use it
Skip Cloud Monitoring Chart Generation when the task is outside the coding category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.
How to install
Where will you use it?
mkdir -p ~/.claude/skills/cloud-monitoring-chart-generation # Save SKILL.md to ~/.claude/skills/cloud-monitoring-chart-generation/SKILL.md
- Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/cloud-monitoring-chart-generation/SKILL.md. For a shared project, commit the folder at .claude/skills/cloud-monitoring-chart-generation/ instead.
- Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
- For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.
Full install guide for Claude, Cursor, and Codex →
Try a starter prompt
After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.
Use the Cloud Monitoring Chart Generation skill for this task: Use Cloud Monitoring Chart Generation when this documented workflow matches the task. Confirm any required inputs or files before making changes.
What supports this recommendation?
71/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.
- Documentation
- 77/100
- Practical detail
- 68/100
- Source evidence
- 63/100
- Source signals
- 72/100
Model compatibility evidence
- claudeinferred
The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.
- chatgptinferred
The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.
- geminiinferred
The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.
- copilotinferred
The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.
- llamainferred
The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.
- perplexityinferred
The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.
- mistralinferred
The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.
- grokinferred
The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.
Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.
What this skill does
# Cloud Monitoring Chart Generation Skill (`cloud-monitoring-chart-generation`)
Transforms PromQL or ListTimeSeries JSON request payloads and metric metadata into valid Server-Driven UI (SDUI) `google.monitoring.dashboard.v1.Widget` Protocol Buffer textprotos. These generated textprotos are designed to be ingested by the Cloud Monitoring Dashboards API, gcloud CLI, or declarative dashboard provisioning pipelines.
> [!IMPORTANT] **Preferred API & Mutually Exclusive Queries**: > - **API Preference**: Always prefer generating `ListTimeSeries` (`time_series_filter`) configurations for widgets over PromQL, unless the user explicitly requested PromQL or the metric math strictly requires it. > - **Mutually Exclusive**: A widget dataset `time_series_query` must contain **EITHER** a `time_series_filter` OR a `prometheus_query`. You must never populate both fields in the same dataset simultaneously. > - **Strict Passthrough**: You MUST copy the provided PromQL query or ListTimeSeries JSON exact filter string character-for-character. DO NOT invent, rewrite, or modify the queries under any circumstances.
> [!CAUTION] **CRITICAL EXECUTION & WORKING DIRECTORY RULES**: > > - **DO NOT CHANGE WORKING DIRECTORY**: Keep your working directory at your > workspace root. Do NOT `cd` into skill subdirectories. > - **NO DISCOVERY OR SEARCH RULE**: The metric descriptor, PromQL query, > ListTimeSeries JSON payload, unit, and resource type are ALWAYS present in > the conversation context. **NEVER** run file or codebase search tools, > like grep, find, directory listings, or codebase queries, to discover > metric metadata or inspect repository structures. > - **SCRIPT EXECUTION**: Execute the bundled Python scripts directly using > python3. > - **OUTPUT GENERATION**: The `assemble_widget_proto` script automatically > generates a unique UUID-based filename to prevent parallel execution > collisions. It will print the generated filename to standard error > strongly prefixed with "Wrote widget textproto to:". You MUST parse this > exact prefix from the logs to extract the generated path and use it for > validation in Stage 4.
## 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-chart-generation)"` and append `agent-skills/1.0 (skill:cloud-monitoring-chart-generation)` to `User-Agent` headers.
## Prerequisites: Environment Setup
Install the required dependencies in your environment or sandbox:
```bash pip install -r scripts/requirements.txt ```
## Follow the workflow pipeline
``` [ Stage 1: compute_labels ] ---> [ Stage 2: LLM Synthesis ] ---> [ Stage 3: assemble_widget_proto ] Generates candidate labels Formulates SemanticPlotSpec Emits validated widget textproto ```
### Stage 1: Baseline Candidate Synthesis
Run Stage 1 using python3:
```bash # For PromQL: python3 scripts/compute_labels.py \ --metric_display_name "METRIC_DISPLAY_NAME" \ --resource_type "RESOURCE_TYPE" \ --metric_unit "UNIT" \ --promql_query 'PROMQL_QUERY'
# For ListTimeSeries: python3 scripts/compute_labels.py \ --metric_display_name "METRIC_DISPLAY_NAME" \ --resource_type "RESOURCE_TYPE" \ --metric_unit "UNIT" \ --filter_string 'metric.type="m"...' \ --per_series_aligner "ALIGN_RATE" \ --cross_series_reducer "REDUCE_SUM" ```
### Stage 2: SemanticPlotSpec Prediction (LLM)
Review the user prompt, PromQL or LTS query structure, and Stage 1 baseline candidates to formulate a 4-key `SemanticPlotSpec` JSON object:
1. **`title`**: Polish `titleCandidate` to ensure it is concise, human-readable, and under 80 characters. 2. **`yAxisLabel`**: Set this to a concise, human-readable quantitative descriptor or metric concept, like `"Utilization"`, `"Bytes"`, or `"Bytes Rate"`. Do NOT append unit symbols or suffixes like `"(%)"`, `"(/s)"`, or `"(By)"` to the label, because units are rendered automatically via `unitOverride`. 3. **`plotType`**: Default to `LINE`. Use `STACKED_AREA` if requested by the user or for distribution queries. 4. **`unitOverride`**: Set this to the Unified Code for Units of Measure (UCUM) unit string, derived by applying the corresponding rules below:
#### List Time Series (LTS) Unit Strategy:
- **Trust the Candidate**: For List Time Series flows, set this directly to the `unitOverrideCandidate` produced by Stage 1. Stage 1 mathematically processes `ALIGN_RATE`, for example producing `By/s`, forces `%` for `ALIGN_PERCENT_CHANGE`, and correctly outputs native normalizations unconditionally.
#### PromQL Unit Strategy (LLM Manual Override):
Because PromQL expressions can geometrically compose, for example `histogram_quantile(..., rate(...))`, rely on your own semantic reasoning to govern the final unit:
- **Rate Functions (`rate(...)`, `irate(...)`)**: Convert cumulative counters into per-second rates. Append `/s` to the raw metric unit. For example, a raw metric unit of `By` with `rate(...)` results in `unitOverride: "By/s"`. - **Exception**: If `rate()` is evaluated inside a `histogram_quantile()`, the output is the raw bucket unit like `"s"`, not a rate. - **Ratios & Percentages (`100 * (A / B)`)**: Ratios of identical metric units typically represent percentages, resulting in `unitOverride: "%"`. - **Normalizations**: Normalize `10^2.%` to `"%"`. - **Preserved Units**: For simple aggregation functions like `avg_over_time(...)` or `sum by (...)`, retain and output the underlying metric unit without modification.
- **Legend Template**: Do NOT configure the `legend_template` field. It is intentionally omitted so that the Cloud Monitoring frontend dynamically renders its multi-column table legend at runtime.
Example `SemanticPlotSpec`:
```json { "title": "VM CPU Utilization us-central1-a", "yAxisLabel": "Utilization", "plotType": "LINE", "unitOverride": "%" } ```
### Stage 3: Protobuf Assembly & Output
Run Stage 3 using python3 to generate and save the widget textproto. Use `--promql_query` for PromQL, or `--lts_request_json` for ListTimeSeries:
```bash # For PromQL: python3 scripts/assemble_widget_proto.py \ --promql_query 'PROMQL_QUERY' \ --spec_json 'SEMANTIC_PLOT_SPEC_JSON'
# For ListTimeSeries: python3 scripts/assemble_widget_proto.py \ --lts_request_json '{"filter": "...", "aggregation": {...}}' \ --spec_json 'SEMANTIC_PLOT_SPEC_JSON' ```
> [!IMPORTANT] **MANDATORY FILE OUTPUT CONTRACT**: Do not attempt to guess or > enforce the output filename. The script will automatically generate a > guaranteed-unique filename and print it to standard error. Search stderr for > the explicit prefix "Wrote widget textproto to:" to deterministically capture > this filename, and then target it in Stage 4 validation.
- **Assigned Filename Feedback**: Whenever an output file is saved, the script logs the file path to stderr. Read your command execution logs for the exact filename created so you can target it in Stage 4 validation. - **Text Chat Output**: Enclose the generated SDUI widget textproto inside a ```` ```textproto```` code block in your response:
```textproto title: "..." xy_chart { ... } ```
### Verify and auto-retry
> [!CAUTION] **DO NOT FINISH YOUR TURN UNTIL FILE VERIFICATION PASSES**: 1. > **Validate Artifact**: Execute the validator script against the generated file > output from Stage 3: > > ```bash > # For PromQL charts: > python3 scripts/validate_chart.py --input_file "GENERATED_FILE.textproto" \ > --expected_promql_substring "SOME_IDENTIFYING_SUBSTRING_FROM_QUERY" \ > --expected_unit_override "UNIT_OVERRIDE_CANDIDATE" > > # For ListTimeSeries (LTS) charts: > python3 scripts/validate_chart.py --input_file "GENERATED_FILE.textproto" \ > --expected_lts_filter_substring "SOME_IDENTIFYING_SUBSTRING_FROM_FILTER" \ > --expected_unit_override "UNIT_OVERRIDE_CANDIDATE" > > # ALWAYS provide an identifying substring and the Stage 1 unit override candidate to verify you didn't mutate the data. > # CRITICAL: If you generated multiple charts for multiple metrics, you MUST run this validation script independently for EACH file generated to ensure every chart is correct! > ``` > > 2. **Auto-Retry if Missing or Failed**: If `validate_chart` reports that the > file is missing or invalid, verify your script parameters and immediately > re-run Stage 3: > > ```bash > python3 scripts/assemble_widget_proto.py \ > --promql_query 'PROMQL_QUERY' \ > --spec_json 'SEMANTIC_PLOT_SPEC_JSON' > # Or use --lts_request_json if applicable > ``` > 3. **Validation & Retries**: Run `validate_chart` to verify the generated > textproto. If validation fails due to a schema or syntax error, correct > the parameters and retry up to 2 times. If validation still fails after 2 > retries, stop retrying, notify the user of the validation error, and > present the best-effort textproto. > 4. **Execution vs. Validation Errors**: Note that schema/syntax validation > errors from `validate_chart.py` are distinct from OS or environment > execution restrictions, which are handled below in **Graceful Sandbox > Fallback**.
#### Perform graceful sandbox fallback
If `compute_labels.py`, `assemble_widget_proto.py`, or `validate_chart.py` cannot be executed due to environment or sandbox restrictions, do the following:
1. Notify the user which script cannot be executed and why. 2. **Synthesize and output the complete widget textproto directly in your response**, following all formatting and unit rules. 3. Provide a **"Local Verification"** section containing the standalone python3 commands so the user can run and validate the schema locally if desired.
## Supporting Links
- [Dashboards API](https://docs.cloud.google.com/monitoring/dashboards/api-dashboard) - [Prometheus Docs](https://prometheus.io/docs/prometheus/latest/querying/)
Intended uses
- Use Cloud Monitoring Chart Generation when this documented workflow matches the task.
Implementation notes
- Review the source instructions and adapt inputs before running the workflow.
Try it, then tell us how it went
A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.