cloud-monitoring-chart-generation

Files (11)

• SKILL.md
• attribution.md · references/
• assemble_widget_proto.py · scripts/
• assemble_widget_proto_test.py · scripts/
• compute_labels.py · scripts/
• compute_labels_test.py · scripts/
• requirements.txt · scripts/
• textproto_util.py · scripts/
• textproto_util_test.py · scripts/
• validate_chart.py · scripts/
• validate_chart_test.py · scripts/

SKILL.md (first lines)

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

From google/skills, Apache-2.0.

More from google/skills