google.monitoring.dashboard.v1.Widget

[!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 GENERATION: The

  assemble_widget_proto

  script automatically generates deterministic sequential filenames like

  chart.textproto

  and

  chart_2.textproto

  and saves them to the active workspace. The script will handle naming and saving automatically, and will print the generated filename to the console.

SemanticPlotSpec

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.

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

SemanticPlotSpec

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

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

[!IMPORTANT] MANDATORY FILE OUTPUT CONTRACT: The script automatically names and saves output files like

chart.textproto

and

chart_2.textproto

directly in your workspace root without subdirectories.

• Assigned Filename Feedback: Whenever an output file is saved, the script logs the file path to stderr, for example:

  Wrote widget textproto to: .../chart.textproto

  . 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 {
  ...
}

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

   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, 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'

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.

compute_labels.py

assemble_widget_proto.py

validate_chart.py

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.

• Dashboards API
• Prometheus Docs