/cloud-monitoring-chart-generation

name: cloud-monitoring-chart-generation
metadata:
  category: CloudObservabilityAndMonitoring
description: >-
  Generates Google Cloud Monitoring Server-Driven UI (SDUI) Widget and
  XyChart Protocol Buffer textprotos 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.

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. 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: "%"`. -