cloud-monitoring-chart-generation

Cloud Monitoring Chart Generation 技能（cloud-monitoring-chart-generation）

将 PromQL 或 ListTimeSeries JSON 请求负载和指标元数据转换为有效的 Server-Driven UI（SDUI）google.monitoring.dashboard.v1.Widget Protocol Buffer textproto。这些生成的 textproto 专为 Cloud Monitoring Dashboards API、gcloud CLI 或声明式仪表板配置流水线摄取而设计。

重要

首选 API 和互斥查询：

• API 优先级：对于 Widget，始终优先生成 ListTimeSeries（time_series_filter）配置，而不是 PromQL，除非用户明确要求使用 PromQL，或指标数学运算严格要求使用 PromQL。
• 互斥：Widget 数据集的 time_series_query 必须包含 二者之一：time_series_filter 或 prometheus_query。同一数据集中绝不能同时填充这两个字段。
• 严格透传：必须逐字符原样复制提供的 PromQL 查询或 ListTimeSeries JSON 精确筛选字符串。任何情况下都不得编造、重写或修改查询。

注意

关键执行与工作目录规则：

• 不得更改工作目录：将工作目录保持在工作区根目录。不要 cd 进入技能子目录。
• 不得发现或搜索：指标描述符、PromQL 查询、ListTimeSeries JSON 负载、单位和资源类型始终都在对话上下文中。绝不要运行文件或代码库搜索工具（如 grep、find、目录列表或代码库查询）来发现指标元数据或检查仓库结构。
• 脚本执行：直接使用 python3 执行随附的 Python 脚本。
• 输出生成：assemble_widget_proto 脚本会自动生成基于唯一 UUID 的文件名，以防并行执行时发生冲突。它会在标准错误中打印生成的文件名，并以 "Wrote widget textproto to:" 作为醒目前缀。必须从日志中解析此精确前缀，提取生成的路径，并在阶段 4 中使用该路径进行验证。

归属信息

必须阅读：执行任何 gcloud、REST API 或 MCP 命令之前，必须阅读 Usage Attribution。对于直接在终端中执行的命令（绝不要用于生成的脚本、Terraform 或用户代码），在 gcloud 前添加 CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:cloud-monitoring-chart-generation)" ，并将 agent-skills/1.0 (skill:cloud-monitoring-chart-generation) 附加到 User-Agent 请求头。

先决条件：环境设置

在环境或沙盒中安装所需依赖项：

pip install -r scripts/requirements.txt

按工作流流水线执行

[ Stage 1: compute_labels ]  --->  [ Stage 2: LLM Synthesis ]  --->  [ Stage 3: assemble_widget_proto ]
  Generates candidate labels         Formulates SemanticPlotSpec       Emits validated widget textproto

阶段 1：合成基准候选项

使用 python3 运行阶段 1：

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

阶段 2：预测 SemanticPlotSpec（LLM）

查看用户提示词、PromQL 或 LTS 查询结构，以及阶段 1 的基准候选项，以构造包含 4 个键的 SemanticPlotSpec JSON 对象：

1. title：润色 titleCandidate，确保其简洁、易于理解且少于 80 个字符。
2. yAxisLabel：将其设为简洁、易于理解的定量描述或指标概念，例如 "Utilization"、"Bytes" 或 "Bytes Rate"。不要在标签后追加单位符号或后缀，例如 "(%)"、"(/s)" 或 "(By)"，因为单位会通过 unitOverride 自动呈现。
3. plotType：默认设为 LINE。如果用户要求，或用于分布查询，则使用 STACKED_AREA。
4. unitOverride：设为统一代码计量单位（UCUM）字符串，按照以下对应规则推导：

列出时间序列（LTS）单位策略：

• 信任候选值：对于列出时间序列流程，直接将其设为第 1 阶段生成的 unitOverrideCandidate。第 1 阶段会以数学方式处理 ALIGN_RATE，例如生成 By/s；对 ALIGN_PERCENT_CHANGE 强制使用 %，并始终正确输出原生归一化值。

PromQL 单位策略（LLM 手动覆盖）：

由于 PromQL 表达式可以进行几何组合，例如 histogram_quantile(..., rate(...))，请依靠自己的语义推理来确定最终单位：

• 速率函数（rate(...)、irate(...)）：将累积计数器转换为每秒速率。在原始指标单位后附加 /s。例如，原始指标单位为 By 时，使用 rate(...) 会得到 unitOverride: "By/s"。

  • 例外：如果在 histogram_quantile() 内计算 rate()，输出单位是原始桶单位，例如 "s"，而不是速率。

• 比值和百分比（100 * (A / B)）：单位相同的指标相除通常表示百分比，因此 unitOverride: "%"。

• 归一化：将 10^2.% 归一化为 "%"。

• 保留单位：对于 avg_over_time(...) 或 sum by (...) 等简单聚合函数，保留并输出底层指标单位，不作修改。

• 图例模板：请勿配置 legend_template 字段。这里有意省略该字段，以便 Cloud Monitoring 前端在运行时动态呈现多列图例。

SemanticPlotSpec 示例：

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

第 3 阶段：Protobuf 组装与输出

使用 python3 运行第 3 阶段，生成并保存 widget textproto。PromQL 使用 --promql_query，ListTimeSeries 使用 --lts_request_json：

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

重要

强制文件输出约定：请勿尝试猜测或强制指定输出文件名。脚本会自动生成一个保证唯一的文件名，并将其打印到标准错误流。请在标准错误流中查找明确前缀“Wrote widget textproto to:”，以确定性地获取此文件名，然后在第 4 阶段验证时使用该文件名。

• 分配的文件名反馈：每当保存输出文件时，脚本都会将文件路径记录到标准错误流。请查看命令执行日志，获取创建的确切文件名，以便在第 4 阶段验证时使用。
• 文本聊天输出：在回复中，使用 ```textproto 代码块包裹生成的 SDUI widget textproto：

title: "..."
xy_chart {
  ...
}

验证并自动重试

注意

在文件验证通过前，切勿结束当前轮次：1. 验证产物：针对第 3 阶段生成的文件运行验证脚本 输出：

   # 对于 PromQL 图表：
   python3 scripts/validate_chart.py --input_file "GENERATED_FILE.textproto" \
      --expected_promql_substring "SOME_IDENTIFYING_SUBSTRING_FROM_QUERY" \
      --expected_unit_override "UNIT_OVERRIDE_CANDIDATE"

   # 对于 ListTimeSeries（LTS）图表：
   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"

   # 务必提供用于识别的子字符串和第 1 阶段的单位覆盖候选值，以验证数据未被修改。
   
   # 关键：如果你为多个指标生成了多个图表，则必须对生成的每个文件分别运行此验证脚本，以确保每个图表都正确！

2. 缺失或失败时自动重试：如果 validate_chart 报告文件缺失或无效，请检查脚本参数，并立即重新运行第 3 阶段：

   python3 scripts/assemble_widget_proto.py \
     --promql_query 'PROMQL_QUERY' \
     --spec_json 'SEMANTIC_PLOT_SPEC_JSON'
   # 或者在适用时使用 --lts_request_json
   

3. 验证与重试：运行 validate_chart 验证生成的 textproto。如果验证因架构或语法错误而失败，请修正 参数并重试，最多 2 次。如果重试 2 次后仍然失败， 请停止重试，告知用户验证错误，并提供尽力生成的 textproto。

4. 执行错误与验证错误：请注意，来自 validate_chart.py 的架构／语法验证 错误不同于操作系统或环境执行限制；后者将在下文的沙箱受限时的优雅回退 中处理。

执行沙箱受限时的优雅回退

如果由于环境或沙箱限制而无法执行 compute_labels.py、assemble_widget_proto.py 或 validate_chart.py， 请执行以下操作：

1. 告知用户无法执行哪个脚本以及原因。
2. 直接在回复中合成并输出完整的 widget textproto，并遵循所有格式和单位规则。
3. 提供一个 “本地验证” 部分，其中包含独立的 python3 命令，以便用户按需在本地运行并验证架构。

相关链接

• Dashboards API
• Prometheus 文档