/cx-dashboards

name: cx-dashboards
description: >
  Build and deploy a Coralogix dashboard for a given service from its logs,
  spans, metrics, and service specs. Discovers telemetry via cx CLI commands,
  emits importable Coralogix JSON, verifies every PromQL and DataPrime query live
  through the `cx` CLI, and creates or updates dashboards via `cx dashboards create`
  and `cx dashboards replace`. Use whenever the user asks to create, build, generate,
  deploy, update, replace, or modify a Coralogix dashboard, monitoring dashboard,
  or observability dashboard for a service, app, or pipeline.
metadata:
  version: "0.2.1"

Create Coralogix Dashboard

Produces a Coralogix dashboard for a target service and deploys it via the `cx` CLI. Workflow: discover the service's telemetry, align on intent with the user, draft a plan, emit the JSON, live-verify every query through `cx`, then create the dashboard in a chosen folder.

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

---

Reference files

Load these files for domain-specific guidance:

| Task | Reference | |---|---| | DataPrime query syntax | [`references/dataprime-reference.md`](references/dataprime-reference.md) | | PromQL query syntax, counters vs gauges, histograms | [`references/promql-guidelines.md`](references/promql-guidelines.md) | | Log field discovery, query patterns, wildfind policy | [`references/logs-querying.md`](references/logs-querying.md) | | Span field discovery, latency analysis, trace queries | [`references/spans-querying.md`](references/spans-querying.md) | | Dashboard-specific query gotchas (`${__range}`, `promqlQueryType`) | [`references/query-syntax.md`](references/query-syntax.md) | | Widget JSON templates | [`references/widget-templates.md`](references/widget-templates.md) |

For choosing the right signal (metrics / logs / traces), use `cx-telemetry-querying`.

---

Dashboard Management

Beyond creating dashboards, use these commands to manage existing ones:

| Command | Purpose | |---|---| | `cx dashboards catalog -o json` | List all dashboards in the catalog | | `cx dashboards get <id> -o json` | Get a dashboard definition (useful as a template) | | `cx dashboards folders list -o json` | List dashboard folders | | `cx dashboards folders create --name "Name"` | Create a dashboard folder | | `cx dashboards folders create --name "Sub" --parent-id <id>` | Create a nested folder | | `cx dashboards replace --from-file dashboard.json` | Replace an existing dashboard with updated JSON | | `cx dashboards check --from-file dashboard.json` | Validate a dashboard definition without persisting (server-side strict check; exits non-zero on errors) | | `cx dashboards check <dashboard-id>` | Validate a stored dashboard by id |

To update an existing dashboard:

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

To duplicate a dashboard as a new copy:

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

Proceed in order. Don't jump to Phase 4 before the user approves the Phase 3 plan, and don't run Phase 8 before Phases 5–7 all pass. Phase 9 is mandatory — the workflow is not done until the user has a clickable link.

---

Phase 1: Discover telemetry & business meaning

For the target service, gather:

1. **Business purpose** - read `README.md` and the top-level entrypoint (`main.*`, `index.*`, `cmd/main.go`, etc.). Summarize in 2–3 sentences what it does, its key stages, and what can go wrong. 2. **Metrics** - for each candidate keyword (service name, subsystem, verbs like `request`, `error`, `latency`, `dlq`) run `cx metrics search --name '*<keyword>*'`. When a metric looks promising, list its labels with `cx metrics get-labels <metric>`. Only use names `cx metrics search` returns - this is what prevents invented metrics from reaching Phase 5. Cross-check the service's instrumentation (`prometheus_client`, `promauto.NewCounter/Histogram/Gauge`, OTel meters, `prom-client`, Micrometer, `metrics.py`) for semantics and histogram buckets (`_sum`, `_count`, `_bucket`). 3. **Logs** - discover custom `$d.*` fields with `cx search-fields "<description>" --dataset logs` before assuming a field exists. Sample message templates and severity with `cx logs "filter \$l.applicationname == '<app>'" --limit 5 -o json`. Standard fields (`$m.severity`, `$m.timestamp`, `$l.applicationname`, `$l.subsystemname`) don't need discovery. 4. **Spans / traces** - discover span attributes with `cx search-fields "<description>" --dataset spans`. Sample with `cx spans "filter \$l.serviceName == '<svc>'" --limit 5 -o json`. Error conventions vary (`$d.tags.error`, `$d.http.status_code`); check samples before filtering. 5. **Message buses & DLQs** - grep for Kafka, RabbitMQ, SQS, Pub/Sub clients and any `dlq`/`DLQ` references. Note topic/queue names for DLQ panels. 6. **Service configuration** - check `meta.yaml`, Helm `values.yaml`, `Deployment`, `Dockerfile`, `chart.yaml`. Extract:

• The `applicationname` / `subsystemname` label values as they appear in Coralogix.
• Tenant/account/team identifiers used as