cloud-monitoring-chart-generation

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.

Prerequisites: Environment Setup

Install the required dependencies in your environment or sandbox:

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:

# 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.

1. 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.

1. plotType: Default to LINE. Use STACKED_AREA if requested by the

user or for distribution queries.

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

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

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

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.

1. 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
• Prometheus Docs