Cloud Monitoring Chart Generation Skill (cloud-monitoring-chart-generation)

Transforms PromQL queries 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.

[!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, unit, and resource type are ALWAYS present in the conversation context. NEVER run file or codebase search tools, such as 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, for example: python3 scripts/assemble_widget_proto.py ....
• OUTPUT FILE CONTRACT: Pass --output "chart.textproto" to assemble_widget_proto to create the file ./chart.textproto directly in your active workspace root. If generating multiple charts in a workflow, pass --output auto to let the script programmatically assign deterministic sequential filenames (chart.textproto, chart_2.textproto, etc.) and prevent overwrites.

Prerequisites: Environment Setup

Install the required dependencies in your environment or sandbox:

pip install -r scripts/requirements.txt

3-Stage Pipeline Workflow

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

python3 scripts/compute_labels.py \
  --metric_display_name "METRIC_DISPLAY_NAME" \
  --resource_type "RESOURCE_TYPE" \
  --metric_unit "UNIT" \
  --promql_query "PROMQL_QUERY"

Stage 2: SemanticPlotSpec Prediction (LLM)

Review the user prompt, PromQL 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, such as "Utilization", "Bytes", or "Bytes Rate". Do NOT append unit symbols or suffixes such as "(%)", "(/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 from the PromQL query by applying the Unit Override Computation Rules below.

Unit Override Computation Rules:

• 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".

• Ratios & Percentages (100 * ... / ...): Ratios of identical metric units multiplied by 100 represent percentages, resulting in unitOverride: "%".

• Normalizations: Normalize 10^2.% to "%", per the Unified Code for Units of Measure (UCUM) standard.

• Preserved Units: For aggregation functions like avg_over_time(...) or sum by (...), retain and output the underlying metric unit without modification. For example, output "%", "By", or "s" unchanged.

• 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, selecting the output flag based on your workflow:

Example A: Single-Chart Task (Default)

For standard tasks or automated evaluations generating a single chart, pass --output "chart.textproto":

python3 scripts/assemble_widget_proto.py \
  --promql_query "PROMQL_QUERY" \
  --spec_json 'SEMANTIC_PLOT_SPEC_JSON' \
  --output "chart.textproto"

Example B: Multi-Chart Workflow (Automatic Sequential Naming)

When generating multiple charts in a single workflow (such as creating a 4-chart dashboard), pass --output auto so the script programmatically assigns deterministic sequential filenames (chart.textproto, chart_2.textproto, chart_3.textproto) and prevents overwrites:

python3 scripts/assemble_widget_proto.py \
  --promql_query "PROMQL_QUERY" \
  --spec_json 'SEMANTIC_PLOT_SPEC_JSON' \
  --output auto

[!IMPORTANT] MANDATORY FILE OUTPUT CONTRACT: Always save output files directly in your workspace root without subdirectories or absolute paths.

• Output File: Saves ./chart.textproto (or sequential filenames like ./chart_2.textproto) directly in the active workspace root.
• Assigned Filename Feedback: Whenever an output file is saved, the script logs the file path to stderr, for example: Wrote widget textproto to: .../chart_2.textproto. Check 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 {
  ...
}

Stage 4: Mandatory Self-Verification & Auto-Retry Loop

[!CAUTION] DO NOT FINISH YOUR TURN UNTIL FILE VERIFICATION PASSES:

1. Run Validation Check: Execute the validator script against the generated file, such as chart.textproto or the sequential filename like chart_2.textproto output from Stage 3 when using --output auto:

   python3 scripts/validate_chart.py --input_file "GENERATED_FILE.textproto"
   

2. Auto-Retry if Missing or Failed: If validate_chart reports that the file is missing or invalid, immediately re-run Stage 3 targeting that exact filename. Do NOT pass auto when retrying; pass the specific filename like --output "chart_2.textproto" so it overwrites the broken file:

   python3 scripts/assemble_widget_proto.py \
     --promql_query "PROMQL_QUERY" \
     --spec_json 'SEMANTIC_PLOT_SPEC_JSON' \
     --output "GENERATED_FILE.textproto"
   

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, such as Permission denied or Command not found, which are handled below in Graceful Sandbox Fallback.

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