cx-dashboards

创建 Coralogix 仪表板

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

只能使用可从服务代码、README、配置或返回结果的实时查询中引用的指标名称、日志字段和跨度属性。不得臆造。

---

参考文件

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

任务	参考文件
DataPrime 查询语法	references/dataprime-reference.md
PromQL 查询语法、计数器与仪表盘、直方图	references/promql-guidelines.md
日志字段发现、查询模式、wildfind 策略	references/logs-querying.md
跨度字段发现、延迟分析、跟踪查询	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 replace --from-file dashboard.json	使用更新后的 JSON 替换现有仪表板
cx dashboards check --from-file dashboard.json	验证仪表板定义但不持久化（服务器端严格检查；出错时返回非零退出码）
cx dashboards check <dashboard-id>	按 ID 验证已存储的仪表板

更新现有仪表板：

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

将仪表板复制为新副本：

cx dashboards get <dashboard-id> -o json > dashboard.json
# Remove the "id" field, then create as new:
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: Server-side validation via `cx dashboards check`
- [ ] Phase 8: Deploy via `cx dashboards create`
- [ ] Phase 9: Share the dashboard link with the user

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

---

阶段 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. 跨度 / 追踪 - 使用 cx search-fields "<description>" --dataset spans 发现跨度属性。使用 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 阶段：起草内部计划

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

## 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 表格和列表，来自任何查询（包括 PromQL topk）	使用 table 可视化的 dynamic（绝不使用旧版 dataTable）
查询日志、跨度或 DataPrime	dynamic，按形状表选择可视化

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

日志、跨度和 DataPrime 小组件使用 dynamic，并且必须设置可视化。 对任何查询都绝不能生成旧版 dataTable 小组件：PromQL Top-N 表格应使用带 metrics 查询和 table 可视化的 dynamic 小组件。使用 definition.dynamic，并将其 visualization 设置为符合查询形状的图表；只有用户需要查看原始行时才使用 table。形状与可视化的对应关系和模板见：references/widget-templates.md → Widget: dynamic。

生成 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 查询都必须在进入第 8 阶段前通过 cx 成功运行。这样可以发现虚构的指标名称、拼写错误的字段路径和格式错误的管道。

常用 vs 归档（JSON 中的内容 / 时机 / 位置）

内容：

• 常用（TIER_FREQUENT_SEARCH）：用于快速搜索近期日志 / span 的热层。
• 归档（TIER_ARCHIVE）：用于存储较早日志 / span 的冷层（长期保存）。

选择时机：

• 值班排查和近期调查（几小时 / 几天）时选择常用。
• 需要回溯较长时间（几周 / 几个月），或时间范围超出热层保留期时选择归档。

两种语言的验证使用不同的时间窗口：

• PromQL：将 relativeTimeFrame 映射为 $RANGE 令牌（例如，将 172800s 映射为 48h），在 CLI 调用中将 ${__range} 替换为 [$RANGE]，然后在 Phase 6 之前将 ${__range} 还原到 JSON 中。范围向量与窗口有关，因此检查时必须匹配仪表板实际评估的时间范围。
• DataPrime：使用固定的短时间窗口（now-15m → now，--limit 1）进行验证。目标是验证语法 / 字段 / 管道，而不是确认仪表板时间窗口内是否有数据——短窗口速度更快，也能更清晰地反馈失败。

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

如果在重试预算内无法使查询通过，请将 CLI 错误原样反馈给用户——不要交付有问题的组件。

---

Phase 6：自检结构

根据此清单检查最终 JSON。如果有任何项目未通过，请在进入 Phase 7 之前修复并重新检查。

查询语法（特定于仪表板）

• 指标组件中的每个 PromQL 范围向量都使用 [${__range}]——绝不使用 [$__range]，也不使用 [5m]（除非面板有意使用滑动窗口）。
• 单值组件（仪表、饼图、动态表格）的 promqlQueryType 为 PROM_QL_QUERY_TYPE_INSTANT。lineChart 不设置该值。
• DataPrime 日志查询使用 $d.<field> / $l.applicationname / 不带引号的严重性枚举（完整规则：references/dataprime-reference.md）。
• 每个 DataPrime 组件查询都以 source logs 或 source spans 开头（仪表板组件需要 source 前缀；Phase 5 验证会在将管道传给 cx logs / cx spans 之前移除该前缀）。
• 成功率的分母使用 clamp_min(..., 1) 包裹。
• 直方图查询使用正确的后缀（_sum、_count、_bucket）。
• 不带仪表板级别的 filters 时，组件查询仍然有效——Coralogix 会在渲染时注入这些过滤器。

结构

• 每个分区都有 id.value、rows 和 options.custom。
• 每一行都有 id.value、appearance.height 和 widgets。
• 每个组件都有唯一的 id.value，且 definition 中恰好包含 gauge / pieChart / lineChart / dynamic 之一。
• 每个仪表都有数值型的 min 和 max，且 min < max。
• 成功率仪表使用 thresholdType: "THRESHOLD_TYPE_ABSOLUTE"，且高值显示为绿色；错误 / DLQ 仪表的高值显示为红色。
• 指标类“Total” / “stat”组件编码为 gauge。日志、span 或 DataPrime 的总数应为带 stat 可视化的 dynamic 组件。
• 顶层 filters 包含 Phase 2 中的每个切片维度。
• 所有 ID 都是新生成的 UUID，且在文档中唯一。
• 每个 queryDisplaySettings[].queryId 都与同一组件中某个 queryDefinitions[] 条目的 id 相等。cx dashboards check 即使检测到不匹配也会通过，但组件随后会渲染为空。

内容

• 仪表板名称应具有描述性（"<Service> - <Purpose>"）。
• 组件标题应简短、易懂，并与查询计算的内容一致。
• 除非用户另有要求，否则日志 / 错误分区应设置为 collapsed: true。

---

阶段 7：通过 cx dashboards check 进行服务端验证

阶段 6 手动发现了结构问题。本阶段会使用 Coralogix Dashboard Service 的严格验证器（CheckDashboard）检查整个仪表板——这与 create/replace 写入时执行的验证相同，另外还会编译所有 PromQL/DataPrime 查询，并强制要求变量和筛选器具有必需的 ID。

1. 运行 cx dashboards check --from-file /tmp/cx-dashboard-<slug>.json。
2. 如果命令以非零状态退出，输出会列出问题及其 severity、location（指向仪表板的 RFC 6901 JSON Pointer，例如 /sections/0/rows/1/widgets/2）和 message。在 JSON 中修复每个问题（返回阶段 4），如果查询有更改，则重新运行阶段 5，然后重新运行本阶段。
3. 当 check 以 0 状态退出（文本输出：Dashboard is valid (no issues)）时，继续阶段 8。

check 是只读操作——不会持久化仪表板。警告（SEVERITY_WARNING）会打印出来，但不会导致门禁失败；只有错误（SEVERITY_ERROR）才会导致非零退出。在多配置文件分发模式下，任何配置文件返回错误都会导致命令失败。

---

阶段 8：通过 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 错误，并返回阶段 5。最常见的原因是查询在本地解析成功，但被在线 API 拒绝。

---

阶段 9：分享仪表板链接

在用户获得可点击的仪表板链接之前，工作流尚未完成。仅打印 ID 会迫使用户手动在 Coralogix UI 中导航，这就失去了自动化部署的意义。

阶段 8 成功后，捕获 cx dashboards create 打印到 stderr 的 View in Coralogix: <url> 行（链接省略时的情况请参阅 references/deploy.md §“分享链接”），并输出下方的模板。将仪表板名称作为链接文本——用户会点击这个名称。

链接到通过 cx dashboards catalog 找到的仪表板（而不是刚创建的仪表板）时，方式有所不同：catalog 只会打印一个指向目录页面的链接，而不会提供指向单个仪表板的链接。要链接到列表中的某个特定仪表板，请构造 <base>/dashboards/<dashboard_id>，其中 <base> 是本会话中任意 cx dashboards 命令打印的 View in Coralogix: <base>/... 行里已有的控制台 URL——绝不要自行编造 <base>，如果尚未打印过此类行，也绝不要臆造。

---

面向用户的输出格式

当 cx dashboards create 打印了 View in Coralogix: 链接时：

## Plan
<the approved Phase 3 plan>

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

## Deployed
- Dashboard: **[<Name>](<url from the View in Coralogix line>)**
- ID: `<id>`
- Folder: `<folder name or "root">`
- Profile: `<cx profile>`

Open it: [<Name>](<url from the View in Coralogix line>)

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

当 cx dashboards create 未打印 View in Coralogix: 行时（无法为该配置文件解析控制台链接，且未配置 console_url 覆盖项），请完全省略链接——不要编造 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
• Widget 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-slos - 在仪表板上展示与 SLO 关联的可靠性目标
• cx-cases - 对仪表板监控的服务所引发的问题进行分诊
• cx-telemetry-querying - 在构建仪表板前找到合适的遥测信号