cx-create-dashboard
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseCreate Coralogix Dashboard
创建Coralogix仪表盘
Produces a Coralogix dashboard for a target service and deploys it via the CLI. Workflow: discover the service's telemetry, align on intent with the user, draft a plan, emit the JSON, live-verify every query through , then create the dashboard in a chosen folder.
cxcxOnly use metric names, log fields, and span attributes you can cite from the service's code, README, configuration, or a live query that returned a result. Do not invent them.
为目标服务生成Coralogix仪表盘,并通过 CLI完成部署。工作流程:发现服务的遥测数据,与用户确认需求意图,草拟计划,生成JSON文件,通过实时验证每一条查询,最后在选定文件夹中创建仪表盘。
cxcx仅可使用能从服务代码、README文档、配置文件或返回结果的实时查询中找到的指标名称、日志字段和链路追踪属性。不得自行编造。
Sibling skills
关联技能
This skill orchestrates; the skills below own their domain.
| Task | Skill |
|---|---|
| Write / understand a DataPrime query | |
| Write / understand a PromQL query, find a metric, list labels | |
| Run a DataPrime query against logs | |
| Run a DataPrime query against spans | |
| Choose the right signal (metrics / logs / traces) | |
Semantic field search ( | |
Coralogix-dashboard-specific pitfalls (, , widget-filter syntax, threshold types) live in ; widget JSON templates live in .
${__range}promqlQueryTypereferences/query-syntax.mdreferences/widget-templates.md本技能负责编排协调;以下技能各自负责对应的领域。
| 任务 | 技能 |
|---|---|
| 编写/理解DataPrime查询 | |
| 编写/理解PromQL查询、查找指标、列出标签 | |
| 针对日志运行DataPrime查询 | |
| 针对链路追踪(spans)运行DataPrime查询 | |
| 选择合适的信号类型(指标/日志/链路追踪) | |
语义字段搜索( | |
Coralogix仪表盘特有的注意事项(、、组件过滤语法、阈值类型)请查看;组件JSON模板请查看。
${__range}promqlQueryTypereferences/query-syntax.mdreferences/widget-templates.mdDashboard Management
仪表盘管理
Beyond creating dashboards, use these commands to manage existing ones:
| Command | Purpose |
|---|---|
| List all dashboards in the catalog |
| Get a dashboard definition (useful as a template) |
| List dashboard folders |
| Create a dashboard folder |
| Create a nested folder |
To duplicate or modify an existing dashboard:
bash
cx dashboards get <dashboard-id> -o json > dashboard.json除创建仪表盘外,可使用以下命令管理现有仪表盘:
| 命令 | 用途 |
|---|---|
| 列出目录中的所有仪表盘 |
| 获取仪表盘定义(可用作模板) |
| 列出仪表盘文件夹 |
| 创建仪表盘文件夹 |
| 创建嵌套文件夹 |
如需复制或修改现有仪表盘:
bash
cx dashboards get <dashboard-id> -o json > dashboard.jsonEdit dashboard.json (change name, modify widgets, etc.)
编辑dashboard.json(修改名称、调整组件等)
cx dashboards create --from-file dashboard.json
---cx dashboards create --from-file dashboard.json
---Workflow
工作流程
Track progress through this checklist:
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`Proceed in order. Don't jump to Phase 4 before the user approves the Phase 3 plan, and don't run Phase 7 before Phases 5 and 6 both pass.
通过以下检查清单跟踪进度:
仪表盘进度:
- [ ] 阶段1:发现遥测数据及业务意义
- [ ] 阶段2:收集用户的仪表盘规格需求
- [ ] 阶段3:草拟内部仪表盘计划(板块/行/组件)
- [ ] 阶段4:生成Coralogix JSON文件
- [ ] 阶段5:通过cx CLI实时验证每一条查询
- [ ] 阶段6:对照检查清单自行验证结构
- [ ] 阶段7:通过`cx dashboards create`命令部署请按顺序执行。在用户批准阶段3的计划前,不要进入阶段4;在阶段5和阶段6均通过前,不要执行阶段7。
Phase 1: Discover telemetry & business meaning
阶段1:发现遥测数据及业务意义
For the target service, gather:
- Business purpose - read and the top-level entrypoint (
README.md,main.*,index.*, etc.). Summarize in 2–3 sentences what it does, its key stages, and what can go wrong.cmd/main.go - Metrics - for each candidate keyword (service name, subsystem, verbs like ,
request,error,latency) rundlq. When a metric looks promising, list its labels withcx metrics search --name '*<keyword>*'. Only use namescx metrics get-labels <metric>returns - this is what prevents invented metrics from reaching Phase 5. Cross-check the service's instrumentation (cx metrics search,prometheus_client, OTel meters,promauto.NewCounter/Histogram/Gauge, Micrometer,prom-client) for semantics and histogram buckets (metrics.py,_sum,_count)._bucket - Logs - discover custom fields with
$d.*before assuming a field exists. Sample message templates and severity withcx search-fields "<description>" --dataset logs. Standard fields (cx logs "filter \$l.applicationname == '<app>'" --limit 5 -o json,$m.severity,$m.timestamp,$l.applicationname) don't need discovery.$l.subsystemname - Spans / traces - discover span attributes with . Sample with
cx search-fields "<description>" --dataset spans. Error conventions vary (cx spans "filter \$l.serviceName == '<svc>'" --limit 5 -o json,$d.tags.error); check samples before filtering.$d.http.status_code - Message buses & DLQs - grep for Kafka, RabbitMQ, SQS, Pub/Sub clients and any /
dlqreferences. Note topic/queue names for DLQ panels.DLQ - Service configuration - check , Helm
meta.yaml,values.yaml,Deployment,Dockerfile. Extract:chart.yaml- The /
applicationnamelabel values as they appear in Coralogix.subsystemname - Tenant/account/team identifiers used as metric or log labels.
- Deployment environments (,
prod,staging, …).dev
- The
If the signal for a question is ambiguous (e.g. "how much revenue last week"), delegate to first.
cx-telemetry-queryingProduce a short internal summary before moving on. If critical telemetry is missing (e.g. no metrics), surface that to the user and ask whether they want a log-only or trace-only dashboard.
针对目标服务,收集以下信息:
- 业务用途 - 阅读和顶层入口文件(
README.md、main.*、index.*等)。用2-3句话总结其功能、关键阶段及可能出现的问题。cmd/main.go - 指标 - 针对每个候选关键词(服务名称、子系统、、
request、error、latency等动词)运行dlq。当某个指标看起来有价值时,使用cx metrics search --name '*<keyword>*'列出其标签。仅使用cx metrics get-labels <metric>返回的名称——这能防止自行编造的指标进入阶段5。交叉检查服务的埋点工具(cx metrics search、prometheus_client、OTel meters、promauto.NewCounter/Histogram/Gauge、Micrometer、prom-client)以确认语义和直方图桶(metrics.py、_sum、_count)。_bucket - 日志 - 在假设字段存在前,使用发现自定义
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 - 链路追踪(spans/traces) - 使用发现链路追踪属性。使用
cx search-fields "<description>" --dataset spans获取示例。错误约定各不相同(cx spans "filter \$l.serviceName == '<svc>'" --limit 5 -o json、$d.tags.error);过滤前请先检查示例。$d.http.status_code - 消息总线与死信队列(DLQs) - 搜索Kafka、RabbitMQ、SQS、Pub/Sub客户端及任何/
dlq相关引用。记录死信队列面板所需的主题/队列名称。DLQ - 服务配置 - 检查、Helm的
meta.yaml、values.yaml、Deployment、Dockerfile。提取:chart.yaml- 在Coralogix中显示的/
applicationname标签值。subsystemname - 用作指标或日志标签的租户/账户/团队标识符。
- 部署环境(、
prod、staging等)。dev
- 在Coralogix中显示的
如果某个问题的信号不明确(例如“上周收入多少”),请先委托技能处理。
cx-telemetry-querying进入下一阶段前,请生成一份简短的内部总结。如果缺少关键遥测数据(例如无指标),请告知用户并询问是否需要仅基于日志或仅基于链路追踪的仪表盘。
Phase 2: Gather dashboard specifications
阶段2:收集仪表盘规格需求
Ask the user a focused set (≤6). Prefer :
AskQuestion- Audience & use - on-call triage, product/business tracking, capacity planning, customer success?
- Default time range - typical viewing window (e.g. 24h, 7d). Queries still use so users can zoom.
${__range} - Slicing dimensions - top-level filters (,
tenant_id,account_id,subsystem_name,region, …).env - Environment scope - which environments to include/exclude (common default: exclude ,
dev,staging).test - SLO-ish signals - success-rate, latency, or throughput targets to highlight?
- Priorities - what to see first (drives row ordering and which section is ).
collapsed: true
Don't block on answers you can reasonably infer - state the inference and continue.
向用户提出一组聚焦的问题(≤6个)。优先使用:
AskQuestion- 受众与用途 - 值班排查、产品/业务跟踪、容量规划、客户成功?
- 默认时间范围 - 典型查看窗口(例如24小时、7天)。查询仍会使用,以便用户可以缩放时间范围。
${__range} - 切片维度 - 顶层过滤器(、
tenant_id、account_id、subsystem_name、region等)。env - 环境范围 - 包含/排除哪些环境(常见默认:排除、
dev、staging)。test - 类SLO信号 - 是否需要突出显示成功率、延迟或吞吐量目标?
- 优先级 - 希望首先看到哪些内容(决定行的顺序及哪个板块设置为)。
collapsed: true
对于可合理推断的答案,无需等待用户回复——说明推断结果并继续执行。
Phase 3: Draft the internal plan
阶段3:草拟内部计划
Write a markdown plan the user can approve before JSON generation:
undefined编写一份Markdown格式的计划,待用户批准后再生成JSON:
undefinedDashboard: <Service> - <Purpose>
仪表盘:<服务名称> - <用途>
Section 1: <Overview> (collapsed: false)
板块1:<概览>(collapsed: false)
- Row 1: [widget type] <title> - <what it shows> - source: metrics|logs|spans
- Row 2: ...
- 行1:[组件类型] <标题> - <展示内容> - 数据源:指标|日志|链路追踪
- 行2:...
Section 2: <Deep dive> (collapsed: false)
板块2:<深度分析>(collapsed: false)
...
...
Section N: <Logs & errors> (collapsed: true)
板块N:<日志与错误>(collapsed: true)
...
...
Top-level filters
顶层过滤器
- <label> (<source>)
- <标签>(<数据源>)
Assumptions / gaps
假设/缺口
- ...
**Section design**:
- First section: at-a-glance health (gauges + key rates), always expanded.
- Pair related time-series in the same row (rate + latency).
- Final section (raw logs, rare breakdowns): `collapsed: true`.
- Aim for 3–5 sections, 6–20 widgets total.
**Widget-type selection**:
| Signal | Widget type |
|---|---|
| Single headline number (count, % success, totals) | `gauge` (Coralogix calls this "stat") |
| Breakdown across ≤8 categories | `pieChart` |
| Change over time (rate, latency, count per bucket) | `lineChart` |
| Top-N tables, last errors, per-entity listings | `dataTable` |
Don't use other widget types unless the user asks.
Wait for the user to approve or adjust the plan before emitting JSON.
---- ...
**板块设计**:
- 第一个板块:一目了然的健康状态(仪表盘+关键比率),始终展开。
- 将相关时间序列放在同一行(比率+延迟)。
- 最后一个板块(原始日志、罕见细分):设置为`collapsed: true`。
- 目标为3-5个板块,总计6-20个组件。
**组件类型选择**:
| 信号类型 | 组件类型 |
|---|---|
| 单个 headline 数值(计数、成功率、总计) | `gauge`(Coralogix称为“stat”) |
| 最多8个类别的细分 | `pieChart` |
| 随时间变化的数据(比率、延迟、按桶计数) | `lineChart` |
| Top-N表格、最新错误、按实体列表 | `dataTable` |
除非用户要求,否则不要使用其他组件类型。
在生成JSON前,请等待用户批准或调整计划。
---Phase 4: Generate the Coralogix JSON
阶段4:生成Coralogix JSON文件
Produce a single JSON document following . Key rules:
references/widget-templates.md- Top-level shape:
{ "id": "<21-char-nanoid>", "name": "<Dashboard Name>", "layout": { "sections": [ ... ] }, "variables": [], "variablesV2": [], "filters": [ ... ], "relativeTimeFrame": "<seconds>s", "annotations": [], "off": {}, "actions": [] } - IDs - fresh UUIDs for every ,
section,row, and querywidget.id - Row height - unless there's a reason to change.
"appearance": { "height": 19 } - Section options - include ,
options.custom.name, andcollapsed.color.predefined: "SECTION_PREDEFINED_COLOR_UNSPECIFIED" - Filters - one entry per slicing dimension from Phase 2. Default operator with empty
equalsso users can fill in. Usevaluesfor environment exclusions (seenotEquals).references/widget-templates.md - relativeTimeFrame - default (48h) unless the user specified otherwise.
"172800s"
For query syntax follow ; for the full query languages delegate to the and skills.
references/query-syntax.mdcx-dataprimecx-metrics-query遵循生成单个JSON文档。核心规则:
references/widget-templates.md- 顶层结构:
{ "id": "<21位nanoid>", "name": "<仪表盘名称>", "layout": { "sections": [ ... ] }, "variables": [], "variablesV2": [], "filters": [ ... ], "relativeTimeFrame": "<秒数>s", "annotations": [], "off": {}, "actions": [] } - ID - 为每个、
section、row和查询widget生成新的UUID。id - 行高 - 除非有特殊原因,否则设置为。
"appearance": { "height": 19 } - 板块选项 - 包含、
options.custom.name和collapsed。color.predefined: "SECTION_PREDEFINED_COLOR_UNSPECIFIED" - 过滤器 - 为阶段2中的每个切片维度添加一个条目。默认操作符为,
equals为空以便用户填写。对于环境排除,使用values(详见notEquals)。references/widget-templates.md - relativeTimeFrame - 默认设置为(48小时),除非用户指定其他值。
"172800s"
查询语法请遵循;完整查询语言请委托和技能处理。
references/query-syntax.mdcx-dataprimecx-metrics-queryPhase 5: Live-verify every query through the cx CLI
阶段5:通过cx CLI实时验证每一条查询
Every PromQL and DataPrime query in the draft has to successfully run through before Phase 7. This catches invented metric names, typoed field paths, and malformed pipelines.
cxMap to a token (e.g. for ), substitute with for the CLI call, verify, then restore in the JSON before Phase 6.
relativeTimeFrame$RANGE48h172800s${__range}[$RANGE]${__range}Full procedure (CLI invocations, mapping table, retry budget, failure modes): .
$RANGEreferences/verification.mdIf a query can't be made to pass within the retry budget, surface it to the user with the CLI error verbatim - don't ship a broken widget.
进入阶段7前,草稿中的每一条PromQL和DataPrime查询都必须通过成功运行。这能捕获自行编造的指标名称、字段路径拼写错误和格式错误的流水线。
cx将映射为令牌(例如对应),在CLI调用中将替换为进行验证,然后在阶段6前将JSON中的恢复原样。
relativeTimeFrame$RANGE172800s48h${__range}[$RANGE]${__range}完整流程(CLI调用、映射表、重试次数、失败模式):。
$RANGEreferences/verification.md如果查询在重试次数内无法通过,请将CLI错误原封不动地告知用户——不要部署有问题的组件。
Phase 6: Self-verify structure
阶段6:自行验证结构
Run this checklist against the final JSON. Fix and re-check if any item fails before Phase 7.
对照以下检查清单验证最终JSON。在进入阶段7前,修复所有不通过的项并重新检查。
Query syntax (dashboard-specific)
查询语法(仪表盘专用)
- Every PromQL range vector in a metrics widget uses - never
[${__range}], never[$__range](unless the panel is intentionally a sliding window).[5m] - is
promqlQueryTypefor single-value widgets (gauge, pieChart, dataTable). Omitted forPROM_QL_QUERY_TYPE_INSTANT.lineChart - DataPrime log queries use /
$d.message/ unquoted severity enums (full rules:$l.applicationnameskill).cx-dataprime - Every DataPrime widget query starts with or
source logs(dashboard widgets require the source prefix; Phase 5 verification strips it before handing the pipeline tosource spans/cx logs).cx spans - Success-rate denominators wrapped in .
clamp_min(..., 1) - Histogram queries use the correct suffix (,
_sum,_count)._bucket - Widget queries are valid without the dashboard-level - Coralogix injects them at render time.
filters
- 指标组件中的每一条PromQL范围向量均使用——绝不要使用
[${__range}]或[$__range](除非面板是有意设置为滑动窗口)。[5m] - 单值组件(gauge、pieChart、dataTable)的设置为
promqlQueryType。PROM_QL_QUERY_TYPE_INSTANT组件无需设置。lineChart - DataPrime日志查询使用/
$d.message/未加引号的日志级别枚举(完整规则:$l.applicationname技能)。cx-dataprime - 每个DataPrime组件查询均以或
source logs开头(仪表盘组件需要源前缀;阶段5验证时会将其剥离后交给source spans/cx logs处理)。cx spans - 成功率分母使用包裹。
clamp_min(..., 1) - 直方图查询使用正确的后缀(、
_sum、_count)。_bucket - 组件查询无需依赖仪表盘级别的即可生效——Coralogix会在渲染时自动注入过滤器。
filters
Structure
结构
- Each section has ,
id.value, androws.options.custom - Each row has ,
id.value, andappearance.height.widgets - Each widget has a unique and a
id.valuewith exactly one ofdefinition/gauge/pieChart/lineChart.dataTable - Success-rate gauges use with green at high values; error/DLQ gauges use red at high values.
thresholdType: "THRESHOLD_TYPE_ABSOLUTE" - "Total" / "stat" widgets are encoded as , not as a stat type.
gauge - Top-level includes each slicing dimension from Phase 2.
filters - All IDs are freshly generated UUIDs, unique within the document.
- 每个板块均包含、
id.value和rows。options.custom - 每一行均包含、
id.value和appearance.height。widgets - 每个组件均有唯一的,且
id.value中恰好包含definition/gauge/pieChart/lineChart中的一种。dataTable - 成功率仪表盘使用,高值显示绿色;错误/死信队列仪表盘高值显示红色。
thresholdType: "THRESHOLD_TYPE_ABSOLUTE" - “总计”/“统计”组件编码为类型,而非stat类型。
gauge - 顶层包含阶段2中的每个切片维度。
filters - 所有ID均为新生成的UUID,且在文档内唯一。
Content
内容
- Dashboard name is descriptive ().
"<Service> - <Purpose>" - Widget titles are short, human-readable, and match what the query computes.
- The logs/errors section is unless the user said otherwise.
collapsed: true
- 仪表盘名称具有描述性()。
"<服务名称> - <用途>" - 组件标题简短、易读,且与查询计算内容一致。
- 日志/错误板块设置为,除非用户另有要求。
collapsed: true
Phase 7: Deploy via cx dashboards create
cx dashboards create阶段7:通过cx dashboards create
命令部署
cx dashboards createDon't tell the user to paste JSON into the Coralogix UI - deploy it directly.
- List folders: .
cx dashboards folders list -o json - Suggest the best folder match (team, product area, or a folder named after the service). Default to root (omit ) if nothing fits.
--folder - Write the verified JSON to a temp file and run . The CLI generates the
cx dashboards create --from-file /tmp/cx-dashboard-<slug>.json --folder <id>envelope and prints the created dashboard ID.requestId
Full procedure (folder-picking UX, command templates, idempotency note): .
references/deploy.mdOn failure: show the CLI error verbatim and return to Phase 5. The most common cause is a query that parses locally but the live API rejects.
不要让用户将JSON粘贴到Coralogix UI中——直接完成部署。
- 列出文件夹:。
cx dashboards folders list -o json - 建议最合适的文件夹(团队、产品领域或以服务命名的文件夹)。如果没有合适的文件夹,默认部署到根目录(省略参数)。
--folder - 将验证后的JSON写入临时文件,运行。CLI会生成
cx dashboards create --from-file /tmp/cx-dashboard-<slug>.json --folder <id>信封并打印创建的仪表盘ID。requestId
完整流程(文件夹选择体验、命令模板、幂等性说明):。
references/deploy.md如果部署失败:显示CLI错误原文并返回阶段5。最常见的原因是本地解析通过但实时API拒绝的查询。
Output format for the user
向用户输出的格式
undefinedundefinedPlan
计划
<the approved Phase 3 plan>
<已批准的阶段3计划>
Verification
验证情况
- PromQL queries verified: <N>/<N>
- DataPrime queries verified: <N>/<N>
- PromQL查询验证通过:<N>/<N>
- DataPrime查询验证通过:<N>/<N>
Deployed
已部署
- Dashboard: <Name>
- ID:
<id> - Folder:
<folder name or "root"> - Profile:
<cx profile>
The dashboard is live in Coralogix. Adjust filter values (e.g. ) after opening it.
account_id
---- 仪表盘:<名称>
- ID:
<id> - 文件夹:
<文件夹名称或"根目录"> - 配置文件:
<cx profile>
仪表盘已在Coralogix中上线。打开后可调整过滤器值(例如)。
account_id
---References
参考资料
- Coralogix dashboard query gotchas & cross-references:
references/query-syntax.md - Widget JSON templates:
references/widget-templates.md - Live-verification procedure:
references/verification.md - Deploy procedure:
references/deploy.md - Coralogix Custom Dashboards docs: https://www.coralogix.com/docs/user-guides/custom-dashboards/introduction/
- Full DataPrime language: skill →
cx-dataprimeskills/cx-dataprime/references/dataprime-reference.md - Full PromQL reference: skill →
cx-metrics-queryskills/cx-metrics-query/references/promql-guidelines.md - Inline DataPrime help: ,
cx dataprime listcx dataprime show <command>
- Coralogix仪表盘查询注意事项及交叉引用:
references/query-syntax.md - 组件JSON模板:
references/widget-templates.md - 实时验证流程:
references/verification.md - 部署流程:
references/deploy.md - Coralogix自定义仪表盘文档:https://www.coralogix.com/docs/user-guides/custom-dashboards/introduction/
- 完整DataPrime语言:技能 →
cx-dataprimeskills/cx-dataprime/references/dataprime-reference.md - 完整PromQL参考:技能 →
cx-metrics-queryskills/cx-metrics-query/references/promql-guidelines.md - 内置DataPrime帮助:,
cx dataprime listcx dataprime show <command>
Related Skills
相关技能
- - full monitoring setup workflow (views, webhooks, notifications, integrations)
cx-observability-setup - - SLO and alert-connected dashboards, incident triage
cx-incident-management - - discover the right telemetry signal before building dashboards
cx-telemetry-querying
- - 完整监控设置工作流程(视图、webhook、通知、集成)
cx-observability-setup - - 与SLO和告警关联的仪表盘、事件排查
cx-incident-management - - 构建仪表盘前发现合适的遥测信号
cx-telemetry-querying