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

{
  "title": "VM CPU Utilization us-central1-a",
  "yAxisLabel": "Utilization",
  "plotType": "LINE",
  "unitOverride": "%"
}