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

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": "%"
}

Stage 3: Protobuf Assembly & Output

Run Stage 3 using python3 to generate and save the widget textproto. Use --promql_query for PromQL, or --lts_request_json for ListTimeSeries:

# For PromQL:
python3 scripts/assemble_widget_proto.py \
  --promql_query 'PROMQL_QUERY' \
  --spec_json 'SEMANTIC_PLOT_SPEC_JSON'

# For ListTimeSeries:
python3 scripts/assemble_widget_proto.py \
  --lts_request_json '{"filter": "...", "aggregation": {...}}' \
  --spec_json 'SEMANTIC_PLOT_SPEC_JSON'

[!IMPORTANT] MANDATORY FILE OUTPUT CONTRACT: Do not attempt to guess or enforce the output filename. The script will automatically generate a guaranteed-unique filename and print it to standard error. Search stderr for the explicit prefix "Wrote widget textproto to:" to deterministically capture this filename, and then target it in Stage 4 validation.

• Assigned Filename Feedback: Whenever an output file is saved, the script logs the file path to stderr. Read 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 {
  ...
}

Verify and auto-retry

[!CAUTION] DO NOT FINISH YOUR TURN UNTIL FILE VERIFICATION PASSES: 1. Validate Artifact: Execute the validator script against the generated file output from Stage 3:

   # For PromQL charts:
   python3 scripts/validate_chart.py --input_file "GENERATED_FILE.textproto" \
      --expected_promql_substring "SOME_IDENTIFYING_SUBSTRING_FROM_QUERY" \
      --expected_unit_override "UNIT_OVERRIDE_CANDIDATE"

   # For ListTimeSeries (LTS) charts:
   python3 scripts/validate_chart.py --input_file "GENERATED_FILE.textproto" \
      --expected_lts_filter_substring "SOME_IDENTIFYING_SUBSTRING_FROM_FILTER" \
      --expected_unit_override "UNIT_OVERRIDE_CANDIDATE"

   # ALWAYS provide an identifying substring and the Stage 1 unit override candidate to verify you didn't mutate the data.

CRITICAL: If you generated multiple charts for multiple metrics, you MUST run this validation script independently for EACH file generated to ensure every chart is correct!

2.  **Auto-Retry if Missing or Failed**: If `validate_chart` reports that the
    file is missing or invalid, verify your script parameters and immediately
    re-run Stage 3:

    ```bash
    python3 scripts/assemble_widget_proto.py \
      --promql_query 'PROMQL_QUERY' \
      --spec_json 'SEMANTIC_PLOT_SPEC_JSON'
    # Or use --lts_request_json if applicable
    ```
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, which are handled below in **Graceful Sandbox
    Fallback**.

Perform 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