cx-create-dashboard

创建 Coralogix 仪表板

为目标服务生成 Coralogix 仪表板，并通过 cx CLI 部署。工作流：发现服务的遥测数据，与用户确认意图，拟定计划，生成 JSON，通过 cx 实时验证每个查询，然后在选定的文件夹中创建仪表板。

只能使用能够通过服务的代码、README、配置或返回结果的实时查询佐证的指标名称、日志字段和 Span 属性。不要臆造。

---

参考文件

加载以下文件以获取特定领域的指导：

任务	参考文件
DataPrime 查询语法	references/dataprime-reference.md
PromQL 查询语法、计数器与仪表盘、直方图	references/promql-guidelines.md
日志字段发现、查询模式、wildfind 策略	references/logs-querying.md
Span 字段发现、延迟分析、追踪查询	references/spans-querying.md
仪表板专用查询注意事项（${__range}、promqlQueryType）	references/query-syntax.md
小组件 JSON 模板	references/widget-templates.md

要选择合适的信号（指标／日志／追踪），请使用 cx-telemetry-querying。

---

仪表板管理

除了创建仪表板外，还可以使用以下命令管理现有仪表板：

命令	用途
cx dashboards catalog -o json	列出目录中的所有仪表板
cx dashboards get <id> -o json	获取仪表板定义（可用作模板）
cx dashboards folders list -o json	列出仪表板文件夹
cx dashboards folders create --name "Name"	创建仪表板文件夹
cx dashboards folders create --name "Sub" --parent-id <id>	创建嵌套文件夹

要复制或修改现有仪表板：

cx dashboards get <dashboard-id> -o json > dashboard.json
# Edit dashboard.json (change name, modify widgets, etc.)
cx dashboards create --from-file dashboard.json

---

工作流

通过以下清单跟踪进度：

Dashboard Progress:
- [ ] Phase 1: Discover telemetry & business meaning
- [ ] Phase 2: Gather dashboard specifications from user
- [ ] Phase 3: Draft internal dashboard plan (sections/rows/widgets)
- [ ] Phase 4: Generate the Coralogix JSON
- [ ] Phase 5: Live-verify every query through the cx CLI
- [ ] Phase 6: Self-verify structure against the checklist
- [ ] Phase 7: Deploy via `cx dashboards create`
- [ ] Phase 8: Share the dashboard link with the user

按顺序进行。用户批准第 3 阶段的计划前，不要跳到第 4 阶段；第 5 阶段和第 6 阶段都通过前，不要运行第 7 阶段。第 8 阶段为必需步骤——在用户获得可点击链接之前，工作流尚未完成。

阶段 1：发现遥测数据及其业务含义

对于目标服务，请收集：

1. 业务目的 - 阅读 README.md 和顶层入口文件（main.*、index.*、cmd/main.go 等）。用 2–3 句话概述其功能、关键阶段以及可能出错的环节。
2. 指标 - 针对每个候选关键词（服务名称、子系统，以及 request、error、latency、dlq 等动词），运行 cx metrics search --name '*<keyword>*'。发现有希望的指标时，使用 cx metrics get-labels <metric> 列出其标签。只使用 cx metrics search 返回的名称——这样可以防止虚构的指标进入阶段 5。核对服务的埋点实现（prometheus_client、promauto.NewCounter/Histogram/Gauge、OTel meters、prom-client、Micrometer、metrics.py），确认其语义和直方图桶（_sum、_count、_bucket）。
3. 日志 - 在假定字段存在之前，先使用 cx search-fields "<description>" --dataset logs 发现自定义 $d.* 字段。使用 cx logs "filter \$l.applicationname == '<app>'" --limit 5 -o json 查看消息模板和严重性样例。标准字段（$m.severity、$m.timestamp、$l.applicationname、$l.subsystemname）无需发现。
4. Span / 跟踪 - 使用 cx search-fields "<description>" --dataset spans 发现 span 属性。使用 cx spans "filter \$l.serviceName == '<svc>'" --limit 5 -o json 查看样例。错误约定各不相同（$d.tags.error、$d.http.status_code）；筛选前请检查样例。
5. 消息总线和 DLQ - 搜索 Kafka、RabbitMQ、SQS、Pub/Sub 客户端，以及任何 dlq / DLQ 引用。记录 DLQ 面板所需的主题 / 队列名称。
6. 服务配置 - 检查 meta.yaml、Helm values.yaml、Deployment、Dockerfile、chart.yaml。提取：
   • Coralogix 中显示的 applicationname / subsystemname 标签值。
   • 用作指标或日志标签的租户 / 账户 / 团队标识符。
   • 部署环境（prod、staging、dev 等）。

如果某个问题对应的信号不明确（例如“上周的收入是多少”），请先委派给 cx-telemetry-querying。

继续之前，先生成一份简短的内部摘要。如果缺少关键遥测数据（例如没有指标），请告知用户，并询问他们是否需要仅基于日志或仅基于跟踪的仪表板。

---

阶段 2：收集仪表板规格

向用户提出一组聚焦的问题（≤6 个）。优先使用 AskQuestion：

1. 受众与用途 - 值班故障排查、产品 / 业务追踪、容量规划、客户成功？
2. 默认时间范围 - 常用查看窗口（例如 24h、7d）。查询仍使用 ${__range}，因此用户可以缩放。
3. 切分维度 - 顶层筛选器（tenant_id、account_id、subsystem_name、region、env 等）。
4. 环境范围 - 要包含 / 排除哪些环境（常见默认设置：排除 dev、staging、test）。
5. 类似 SLO 的信号 - 是否要突出显示成功率、延迟或吞吐量目标？
6. 优先级 - 希望先看到什么（决定行顺序以及哪个分区设置为 collapsed: true）。

对于可合理推断的答案，不要因此阻塞流程——说明推断并继续。

---

阶段 3：起草内部计划

编写一份供用户在生成 JSON 前审核的 Markdown 计划：

## Dashboard: <Service> - <Purpose>

### Section 1: <Overview> (collapsed: false)
- Row 1: [widget type] <title> - <what it shows> - source: metrics|logs|spans
- Row 2: ...

### Section 2: <Deep dive> (collapsed: false)
...

### Section N: <Logs & errors> (collapsed: true)
...

### Top-level filters
- <label> (<source>)

### Assumptions / gaps
- ...

分区设计：

• 第一个分区：概览式健康状况（仪表盘 + 关键速率），始终展开。
• 将相关时序图配对放在同一行（速率 + 延迟）。
• 最后一个分区（原始日志、少见的细分）：collapsed: true。
• 目标为 3–5 个分区，共 6–20 个小组件。

小组件类型选择：

信号	小组件类型
单个核心数字（数量、成功率、总计）	gauge（Coralogix 称之为“stat”）
最多 8 个类别的细分	pieChart
随时间变化（速率、延迟、每个桶的数量）	lineChart
Top-N 表格、最近错误、按实体列出的清单	dataTable

除非用户提出要求，否则不要使用其他小组件类型。

在输出 JSON 前，等待用户批准或调整计划。

阶段 4：生成 Coralogix JSON

按照 references/widget-templates.md 生成单个 JSON 文档。关键规则：

1. 顶层结构：

   {
     "id": "<21-char-nanoid>",
     "name": "<Dashboard Name>",
     "layout": { "sections": [ ... ] },
     "variables": [],
     "variablesV2": [],
     "filters": [ ... ],
     "relativeTimeFrame": "<seconds>s",
     "annotations": [],
     "off": {},
     "actions": []
   }
   

2. ID——为每个 section、row、widget 和查询 id 生成全新的 UUID。
3. 行高——除非有理由调整，否则使用 "appearance": { "height": 19 }。
4. 分区选项——包含 options.custom.name、collapsed 和 color.predefined: "SECTION_PREDEFINED_COLOR_UNSPECIFIED"。
5. 筛选器——为阶段 2 中的每个切片维度添加一个条目。默认运算符为 equals，values 留空，供用户填写。排除环境时使用 notEquals（参见 references/widget-templates.md）。
6. relativeTimeFrame——默认为 "172800s"（48 小时），除非用户另有指定。

查询语法请参阅 references/query-syntax.md；完整查询语言请加载 references/dataprime-reference.md 和 references/promql-guidelines.md。

---

阶段 5：通过 cx CLI 实时验证每个查询

草稿中的每个 PromQL 和 DataPrime 查询都必须在进入阶段 7 前通过 cx 成功运行。这可以发现虚构的指标名称、拼写错误的字段路径和格式错误的管道。

Frequent 与 Archive（含义、适用时机及其在 JSON 中的位置）

含义：

• Frequent（TIER_FREQUENT_SEARCH）：用于快速搜索近期日志／跨度数据的热层。
• Archive（TIER_ARCHIVE）：用于长期存储较早日志／跨度数据的冷层。

选择时机：

• 值班排查和近期调查（数小时／数天）请选择 Frequent。
• 需要较长回溯时间（数周／数月），或时间范围超出热层保留期限时，请选择 Archive。

这两种语言需针对不同的时间窗口进行验证：

• PromQL：将 relativeTimeFrame 映射为 $RANGE 标记（例如，172800s 对应 48h），在 CLI 调用中将 ${__range} 替换为 [$RANGE]，然后在阶段 6 前将 ${__range} 恢复到 JSON 中。范围向量受窗口影响，因此检查时必须匹配仪表板实际评估的窗口。
• DataPrime：针对固定的短时间窗口（now-15m → now，--limit 1）进行验证。目的是验证语法／字段／管道，而非检查仪表板时间窗口内是否存在数据——短窗口更快，失败信号也更明确。

完整流程（CLI 调用、$RANGE 映射表、重试次数上限和失败模式）：references/verification.md。

如果查询在重试次数上限内仍无法通过，请将 CLI 错误原样告知用户，不要提交有问题的 widget。

---

阶段 6：自行验证结构

对最终 JSON 执行以下检查清单。在进入阶段 7 前，修复并重新检查所有未通过的项目。

查询语法（仪表板专用）

• 指标 widget 中的每个 PromQL 范围向量都使用 [${__range}]——不得使用 [$__range] 或 [5m]（面板有意使用滑动窗口时除外）。
• 单值 widget（gauge、pieChart、dataTable）的 promqlQueryType 为 PROM_QL_QUERY_TYPE_INSTANT。lineChart 不设置此字段。
• DataPrime 日志查询使用 $d.message／$l.applicationname／不加引号的严重性枚举（完整规则见：references/dataprime-reference.md）。
• 每个 DataPrime widget 查询都以 source logs 或 source spans 开头（仪表板 widget 必须包含 source 前缀；阶段 5 验证时，会先移除此此前缀，再将管道传给 cx logs／cx spans）。
• 成功率分母须用 clamp_min(..., 1) 包裹。
• 直方图查询使用正确的后缀（_sum、_count、_bucket）。
• 即使没有仪表板级别的 filters，widget 查询也必须有效——Coralogix 会在渲染时注入这些筛选器。

结构

• 每个分区都有 id.value、rows 和 options.custom。
• 每一行都有 id.value、appearance.height 和 widgets。
• 每个工具都有唯一的 id.value，并且 definition 中恰好包含 gauge / pieChart / lineChart / dataTable 之一。
• 成功率仪表使用 thresholdType: "THRESHOLD_TYPE_ABSOLUTE"，高值显示为绿色；错误/DLQ 仪表在高值时显示为红色。
• “总计”/“统计”工具编码为 gauge，而非统计类型。
• 顶层 filters 包含 Phase 2 中的每个切片维度。
• 所有 ID 都是新生成的 UUID，在文档内唯一。

内容

• 仪表板名称具有描述性（"<Service> - <Purpose>"）。
• 工具标题简短易懂，并与查询计算的内容相符。
• 除非用户另有说明，日志/错误分区设置为 collapsed: true。

---

Phase 7：通过 cx dashboards create 部署

不要让用户将 JSON 粘贴到 Coralogix UI 中——直接部署。

1. 列出文件夹：cx dashboards folders list -o json。
2. 建议最合适的文件夹（团队、产品领域，或以服务命名的文件夹）。如果没有合适的文件夹，则默认放到根目录（省略 --folder）。
3. 将已验证的 JSON 写入临时文件，并运行 cx dashboards create --from-file /tmp/cx-dashboard-<slug>.json --folder <id>。CLI 会生成 requestId 信封，并打印创建的仪表板 ID。

完整流程（选择文件夹的用户体验、命令模板、幂等性说明）：references/deploy.md。

失败时：逐字显示 CLI 错误，并返回 Phase 5。最常见的原因是查询在本地解析成功，但实时 API 拒绝了它。

---

Phase 8：分享仪表板链接

在用户获得可点击的仪表板链接之前，工作流都尚未完成。仅打印 ID 会迫使用户手动前往 Coralogix UI，违背了自动化部署的初衷。

Phase 7 成功后，获取 cx dashboards create 返回的仪表板 id，使用 references/deploy.md §“分享链接”中的区域 → Web 应用主机映射来构建 URL，并输出下方模板。将仪表板名称显示为链接文本——用户会点击该名称。

---

面向用户的输出格式

当 Web 应用主机可以确定时（任何内置区域，或遵循 api.<host> 约定的 Custom 端点）：

## Plan
<the approved Phase 3 plan>

## Verification
- PromQL queries verified: <N>/<N>
- DataPrime queries verified: <N>/<N>

## Deployed
- Dashboard: **[<Name>](https://<region>.app.coralogix.com/#/dashboards/<id>)**
- ID: `<id>`
- Folder: `<folder name or "root">`
- Profile: `<cx profile>`

Open it: [<Name>](https://<region>.app.coralogix.com/#/dashboards/<id>)

Adjust filter values (e.g. `account_id`) after opening it.

当无法确定 Web 应用主机时（不符合 api.<host> 格式的自定义端点），完全省略链接——不要编造 URL。改用此模板：

## Plan
<the approved Phase 3 plan>

## Verification
- PromQL queries verified: <N>/<N>
- DataPrime queries verified: <N>/<N>

## Deployed
- Dashboard: **<Name>** (open via the Coralogix UI; ID `<id>`)
- ID: `<id>`
- Folder: `<folder name or "root">`
- Profile: `<cx profile>`

Adjust filter values (e.g. `account_id`) after opening it.

---

参考资料

• 仪表板查询注意事项和交叉引用：references/query-syntax.md
• 工具 JSON 模板：references/widget-templates.md
• 实时验证流程：references/verification.md
• 部署流程：references/deploy.md
• DataPrime 语言参考：references/dataprime-reference.md
• PromQL 参考：references/promql-guidelines.md
• 日志查询模式：references/logs-querying.md
• Span 查询模式：references/spans-querying.md
• DataPrime 内联帮助：cx dataprime list、cx dataprime show <command>
• Coralogix 自定义仪表板文档：https://www.coralogix.com/docs/user-guides/custom-dashboards/introduction/

相关技能

• cx-observability-setup - 完整的监控设置工作流（视图、Webhook、通知、集成）
• cx-incident-management - SLO 和告警关联的仪表板、事件分诊
• cx-telemetry-querying - 在构建仪表板之前，找到合适的遥测信号