cloud-monitoring-chart-generation

The saved excerpt is a snapshot from when this skill was listed. The external source remains the complete and most current version.

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

```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"
```

### St