---
name: signoz-creating-dashboards
description: >
  Create a new SigNoz dashboard from a natural-language intent — import a
  curated template (PostgreSQL, Redis, JVM, k8s, hostmetrics, APM, LLM,
  etc.) when one fits, or build a custom dashboard from scratch with
  metric / trace / log panels. Make sure to use this skill whenever the
  user says "create a dashboard for…", "set up monitoring for…",
  "build me a dashboard…", "I need observability for…", "import a
  dashboard template", or asks to track / visualize a service, database,
  cluster, or AI/LLM platform — even if they don't explicitly say
  "dashboard". Also use it when someone wants to "monitor", "watch", or
  "see metrics for" a technology and the natural answer is a dashboard.
argument-hint: <natural-language dashboard intent>
---

# Dashboard Create

Build a SigNoz dashboard from a user's natural-language intent. The skill
targets two consumers: an autonomous AI SRE agent that runs without a
human in the loop, and a human at a Claude Code / Codex / Cursor prompt.
Both go through the same flow.

## Prerequisites

This skill calls SigNoz MCP server tools (`signoz_create_dashboard`,
`signoz_list_dashboards`, `signoz_list_dashboard_templates`,
`signoz_import_dashboard`, `signoz_get_dashboard`,
`signoz_update_dashboard`, `signoz_list_metrics`,
`signoz_get_field_keys`, `signoz_get_field_values`,
`signoz_aggregate_logs`, `signoz_aggregate_traces`, etc.).
Before running the workflow, confirm the `signoz_*` tools are
available. If they are not, the SigNoz MCP server is not installed or
configured — run `signoz-mcp-setup` first to initialize or repair the MCP
connection. Do not fall back to raw HTTP calls or fabricate dashboard JSON
without the MCP tools.

## When to use

Use this skill when the user wants to:
- Create, set up, or build a new dashboard.
- "Monitor" or "set up observability" for a service, database,
  infrastructure component, or AI/LLM platform.
- Import a curated dashboard template.
- Visualize a set of metrics / traces / logs together on one screen.

Do NOT use when the user wants to:
- Modify an existing dashboard → `signoz-modifying-dashboards`.
- Understand what an existing dashboard shows → `signoz-explaining-dashboards`.
- Run a one-off query without persisting it → `signoz-generating-queries`.

## Required inputs (strict)

Dashboard creation is a write operation. Guessing here clutters the
shared workspace with empty or wrongly-scoped dashboards someone else has
to clean up. The skill enforces a soft input contract — most fields have
sensible defaults, but a few cannot be guessed:

| Input | Required | Source if missing |
|---|---|---|
| Dashboard intent (NL goal) | yes | `$ARGUMENTS` or recent user turn |
| Technology / domain (e.g. PostgreSQL, Redis, "payment pipeline") | yes | parse from intent; otherwise ask |
| Confirmation to create (plus the modify-or-create choice when duplicates exist) | yes | ask the user (Step 2); still required with zero duplicates and under stated urgency |
| Resource scope for custom builds (service / namespace / cluster) | yes for custom builds | discover via `signoz_get_field_keys` + `signoz_get_field_values`; fall back to a dashboard variable |
| Specific metrics / signals for custom builds | inferred | derive from technology + MCP `signoz://dashboard/*` resources; surface in preview |
| Layout | inferred | apply defaults (see "Defaults" below) |

If a required input is missing and cannot be discovered, **stop before
calling any write tool** and ask the user. The host application decides
how the question is surfaced (a structured clarification tool, inline
`<assistant_question>` tags, an interactive prompt, etc.) — follow the
host's UI rendering rules.

What to include in the question:

- **What is missing** — name the input concretely (e.g. "no service or
  cluster specified for the custom build").
- **Candidate lists** populated from your discovery calls — concrete
  values per attribute the user can pick from. Example shape:
  `service.name` → `frontend`, `checkout`, `payments`, `inventory`;
  `k8s.cluster.name` → `prod-us-east-1`, `staging`.
- **Allow free-form input** so the user can name a value you didn't
  surface.

In autonomous mode (no human), escalate to the caller or fill the gap
from upstream context. Either way, do not proceed to
`signoz_create_dashboard` / `signoz_import_dashboard` with
a guessed value.

## Workflow

The create path starts **duplicate check → modify-or-create choice → template
lookup**. A matching template uses **no-data probe → preview → import**;
a custom build uses **no-data probe → build → per-panel dry-run → preview →
create**. Template lookup is internal; the user's only upfront choices are
modify or create.

### Step 1: Check for duplicates

Call `signoz_list_dashboards`. Most installs fit in the default
page (`limit=50`); narrow with the `filter` argument when the wording is
distinctive (see `signoz://dashboard/list-filter-guide`), and page by `offset`
until you have covered `total`; the schema accepts
integer or string `limit` / `offset` values.

**Match by relevance** Compare each existing
dashboard's lowercased `spec.display.name`, `.description`, and `tags` against the
user's technology/domain. Surface only matches a human would recognize
as the same thing — a "redis" dashboard does not match a "postgresql"
request just because both have a `database` tag. Collect each match's
`spec.display.name`, `id`, and `createdAt` for the next step.

### Step 2: Ask the user — modify or create

Present exactly two options (no template-import as a separate top-level
choice — that's an internal decision in Step 3b):

- **Duplicates found:** "There are already these similar dashboards:
  [list with name, id, created-at]. Want me to (a) modify one of
  these, (b) create a new dashboard anyway, or (c) stop?"
- **No duplicates:** "I'll create a new dashboard for this. Proceed?"
  (No "modify" option when there's nothing to modify.)

Wait for the user's choice. "modify" → Step 3a. "create new" / confirm
→ Step 3b. "stop" → stop.

### Step 3: Create or modify

#### Step 3a: Modify an existing dashboard

Hand off immediately to `signoz-modifying-dashboards` with the chosen
dashboard id and the user's intent. Do not call
`signoz_update_dashboard` or `signoz_patch_dashboard` from this skill —
modification is out of scope. (See "Scope boundary" in Guardrails.)

#### Step 3b: Create a new dashboard

Run the template lookup first. The user has already agreed to create
new — the lookup decides *how* we build it.

Call `signoz_list_dashboard_templates` once with no arguments.
The full catalog (~95 entries) returns in a single call — read it
in-context and pick the best match for the user's intent. When several
entries plausibly fit, present the top 3–5 and let the user choose.

Branch on the result:
- **Single clear template match** — proceed to Step 3b-i (template
  import). Briefly tell the user "I found a pre-built [title] template
  and will use it" so they know what's being created; do not block on
  yes/no.
- **Multiple plausible matches** — present them and ask the user to
  pick. Once picked, proceed to Step 3b-i.
- **Template matches the technology but not the requested signals** —
  common for any specific ask ("Kafka, but I want consumer fetch rate by
  client"). Not "no template": import it, then hand the extra panels to
  `signoz-modifying-dashboards` with the new id. Building from scratch
  discards the curated baseline for no gain.
- **No template** — proceed to Step 3b-ii (custom build). That means no
  catalog entry for the technology, not an entry that looks imperfect or
  aimed at a different metric family. Template bodies are not readable
  before import, so a suspected mismatch is only a hypothesis — and the
  Step 3b-i.1 probe sits *inside* the import path, so it cannot justify
  leaving that path. Probe first, then decide.

#### Step 3b-i: Import the template

> **Tool guardrail** The only template tools are
> `signoz_list_dashboard_templates` and
> `signoz_import_dashboard`. Do not shell out, fetch raw GitHub
> URLs, or invent other tool names.
> `signoz_import_dashboard` takes the template `path` from the
> catalog entry and creates the dashboard in one call — you do not need
> to fetch the JSON yourself or call `signoz_create_dashboard`
> afterwards.

##### Step 3b-i.1: Pre-flight no-data probe (fail fast)

Before calling `signoz_import_dashboard`, confirm the template's
signals are actually being ingested. The most common silent failure for
template imports is "the template imports cleanly but every panel reads
'No data' because the technology isn't being scraped" — the user only
discovers it after clicking through to a useless dashboard.

Since we don't fetch the template body up front, base the probe on the
catalog entry's `category`, `title`, and `keywords` plus the user's
stated technology. Pick up to ~5 representative signals and check them
— keep the total small:

- **Metric-based templates** (most infra/runtime templates): call
  `signoz_list_metrics` with `searchText` set to the technology
  prefix (e.g. `searchText="postgresql"`). Empty result → metric family
  is not being ingested. *Early out:* if this returns empty, declare
  "None present" and skip the rest of the metric probes — they will all
  return zero. Use `timeRange` for a relative window, or pass
  `start`/`end` (unix-ms strings) when you need an exact window instead
  of the server default.
- **Trace-based templates** (APM-style): call
  `signoz_aggregate_traces` with `aggregation=count`,
  `timeRange=1h`. No filter is needed for the "is anything flowing"
  probe — adding `filter="service.name EXISTS"` is fragile and
  unnecessary. Zero count → no traces flowing.
- **Log-based templates**: call `signoz_aggregate_logs` with
  `aggregation=count`, `timeRange=1h`, no filter. Zero count → no logs.
- **Variable values** (when the template clearly relies on a resource
  attribute, e.g. `service.name`, `k8s.cluster.name`): call
  `signoz_get_field_values` to confirm there are values to pick
  from. A dashboard whose top-level dropdown is empty is barely
  better than one full of empty panels.

Branch on the probe result:

- **All signals present** → proceed silently to Step 3b-i.2.
- **Some present, some missing** → list which are missing and ask the
  user to confirm before continuing. Many templates are useful even with
  partial coverage; let them decide.
- **None present** → tell the user no data was found for this
  technology in the probe window, explain the dashboard will show "No
  data" until ingestion is set up, and offer to create it anyway or
  stop. Wait for the user's choice.

This probe is cheap (a handful of queries, ~hundreds of ms total), and
catching the no-data case early avoids the worst UX failure mode of the
template path.

##### Step 3b-i.2: Preview, import, report

1. **Preview** Tell the user what's about to happen in one short
   paragraph: which template (`title`, `path`), what category, what the
   probe found. In autonomous mode the consumer proceeds; in interactive
   mode the human can intervene.
2. **Import** Call `signoz_import_dashboard` with the `path`
   from the chosen catalog entry (e.g. `postgresql/postgresql.json`).
   The server fetches the JSON, validates it, and creates the dashboard
   in one call.
3. **Report** Read the response and tell the user the dashboard's
   title, panel count, and section breakdown. Surface the dashboard's
   variables ("filter by `service.name`", "filter by
   `k8s.cluster.name`") so the user knows what knobs they have. Offer
   two follow-ups: "Want me to adjust panels, layout, or variables?"
   and "Want me to wire alerts for any of these signals?
   (`signoz-creating-alerts`)".
4. **Customization handling** If the user asks for any change to the
   imported dashboard, hand off to `signoz-modifying-dashboards` with
   the new dashboard's id and the requested changes. Do not call
   `signoz_update_dashboard` from this skill.

#### Step 3b-ii: Custom build (no template, or import failed)

Run this path when the Step 3b template lookup found no match, the user
explicitly rejected the suggested template, or
`signoz_import_dashboard` failed.

##### Step 3b-ii.1: Gather requirements

Ask the user (skip questions whose answer is already clear from intent):

1. **Signals** — metrics, traces, logs, or a combination.
2. **Specific signals** — which metrics, which span attributes, which
   log severities matter most.
3. **Resource scope** — which service(s), namespace(s), cluster(s), or
   environment(s).
4. **Variables** — what should be a dropdown vs. a hard-coded filter
   (typical: `service.name`, `deployment.environment.name`,
   `k8s.cluster.name`).
5. **Sections** — group panels into Overview / Latency / Errors /
   Saturation, or another structure that fits the domain.

If the user is non-specific ("just make me something useful for X"),
apply the defaults table below and surface them in the preview.

##### Step 3b-ii.2: Discover names and probe data

The MCP guideline applies: **always prefer resource-attribute filters**.
Before authoring panels, confirm the names you'll use exist and emit
data:

1. **Metrics** — call `signoz_list_metrics` with `searchText`
   tied to the technology (e.g. `searchText="postgresql"`) to get the
   *exact* OTel metric names. Catalog presence ≠ data flowing — for
   any metric you intend to use, follow up with `signoz_query_metrics`
   on a representative window to confirm it actually has datapoints.
2. **Resource attributes** — call `signoz_get_field_keys` with
   `fieldContext=resource` for the relevant signal to enumerate
   available attributes; call `signoz_get_field_values` on the
   ones you'll use as variables to confirm concrete values exist. Note
   that the live data may use older OTel semconv (e.g.
   `deployment.environment` rather than `deployment.environment.name`)
   — always trust the discovered key over the one in the defaults
   table.

If **none** of the discovered signals return data, tell the user the
dashboard's data isn't being ingested yet, explain the panels will
show "No data" until ingestion is set up, and offer to build anyway
or stop. Wait for the user's choice before building.

##### Step 3b-ii.3: Read the dashboard MCP resources

These are the source of truth for the JSON schema, panel types, query
builder shape, and layout rules — do not transcribe schema text into
this skill, it will rot out of sync with the server. Read the core
resources before authoring panel JSON.

> **Fallback when the MCP resource-reader is unavailable** Some MCP
> client harnesses do not expose a resource-reading tool. If you
> cannot read `signoz://...` URIs in this session, fall back to
> `signoz_list_dashboards` + `signoz_get_dashboard` on
> an existing dashboard of the same signal type (metrics / traces /
> logs) and read its `spec.panels` map for worked panel shapes.

- `signoz://dashboard/instructions` — title, tags, description,
  layout, variables.
- `signoz://dashboard/widgets-instructions` — 7 panel types and layout
  rules.
- `signoz://dashboard/widgets-examples` — complete panel configs with
  all required fields (the most important resource — every panel must
  include `kind`, `spec.display`, `spec.plugin`, and exactly one query).
- `signoz://dashboard/examples` — whole create payloads with panels,
  layouts, and variables assembled.
- `signoz://dashboard/query-builder-example` — query builder reference.

Add signal-specific resources as needed:

- Metrics (PromQL): `signoz://promql/instructions`.
  Saved PromQL may reference declared dashboard `$var` variables, but
  `signoz_execute_builder_query` does not expand them: substitute representative
  literals only for dry-runs, never in saved panels. Grafana-only
  `$__rate_interval` / `$__interval` are invalid. Dotted OTel metric names use
  Prometheus 3.x UTF-8 selectors such as `{"metric.name.with.dots"}`.
- Metrics (ClickHouse): `signoz://dashboard/clickhouse-schema-for-metrics`
  + `signoz://dashboard/clickhouse-metrics-example`.
- Metrics (Query Builder aggregation rules):
  `signoz://metrics-aggregation-guide` — required for picking valid
  `timeAggregation` / `spaceAggregation` per metric type.
- Traces (Query Builder): `signoz://traces/query-builder-guide`.
- Logs (Query Builder): `signoz://logs/query-builder-guide`.
- Traces (ClickHouse): `signoz://dashboard/clickhouse-schema-for-traces`
  + `signoz://dashboard/clickhouse-traces-example`.
- Logs (ClickHouse): `signoz://dashboard/clickhouse-schema-for-logs`
  + `signoz://dashboard/clickhouse-logs-example`.

##### Step 3b-ii.4: Build the dashboard JSON

Follow the schema documented in the resources above. Use OTel
semantic attribute names (not shorthand) in filters, groupBy, and
variables. Apply the defaults below unless the user specified otherwise.

Dashboard create/update payloads do not persist a default time range or
refresh interval. Panels follow the viewer-selected global range. If the user
asks for a specific window, mention that range in the final handoff instead of
inventing `timeRange`, `defaultTimeRange`, or `refresh` fields. Do not encode a
PromQL range selector inside a Builder query.

Use SigNoz kinds and JSON types exactly. `signoz/TimeSeriesPanel` means time series
(never Grafana `timeseries`); variables are `ListVariable` / `TextVariable` carrying a
`signoz/DynamicVariable`, `signoz/CustomVariable`, or `signoz/QueryVariable` plugin.
The envelope is `schemaVersion: "v6"` plus `spec`, with no top-level `name` on create —
the server derives that immutable machine label from `spec.display.name`. Tags are
`{key, value}` objects; defer full shapes to the resources.

Keep panel ids and grid items bijective; create/remove both entries together.
`spec.panels` is a map keyed by panel id, and `spec.layouts` positions those ids
through `content.$ref`. During import or rebuild, drop any grid item whose
`$ref` names a panel you did not carry over.

**Defaults the skill applies (and surfaces in the preview):**

| Field | Default | When to override |
|---|---|---|
| Section structure (APM/services) | Overview / Latency / Errors / Throughput | domain-specific (e.g. DB: Overview / Connections / Throughput / Slow Queries) |
| Section structure (infra/runtime) | Overview / Saturation / Errors / Latency | domain-specific |
| Headline panels (services) | request rate, error rate, p50/p95/p99 latency, throughput | omit those that don't apply |
| Headline panels (infra) | resource utilization (CPU, mem), saturation, error/restart counts, throughput | tailor to the technology |
| Counter render unit (rate vs. count) | per-second rate | per-interval **increase** count over a wider window (24h–7d) for any low-volume / bursty / human-paced counter — requests, **error counts**, restarts, OOM kills — where `/sec` renders as tiny decimals (e.g. `0.03/s`); gauges (CPU/mem/queue depth) are already absolute and unaffected; note `increase` rescales its y-axis with the selected range, so prefer it deliberately, not by reflex |
| Variables (services) | `service.name`, `deployment.environment` (or `deployment.environment.name` — verify which exists via `signoz_get_field_keys`) | add `k8s.cluster.name` / `k8s.namespace.name` when k8s-flavored |
| Variables (k8s/infra) | `k8s.cluster.name`, `k8s.namespace.name` (or `host.name` for hostmetrics) | drop `service.name` — it is rarely populated on infra signals |
| Layout | 2-column grid (`width: 6`), 12 columns wide; every item has `0 <= x < 12`, `1 <= width <= 12`, `x + width <= 12` | full-width (`x: 0, width: 12`) for tables and time-series with many series |
| GroupBy on per-service panels | `service.name` resource attribute | drop when filtering to a single service |

**Sections** A section is one Grid entry in `spec.layouts`, with its own
`spec.display.title` and its own `spec.items`. One Grid per section, in display
order; a panel belongs to a section by having its grid item in that Grid. Item
coordinates are per-Grid, so adding to an earlier section leaves later
sections untouched.

**Title and description** The dashboard title (`spec.display.name`) should name the
technology and the scope clearly: "PostgreSQL — prod-us-east-1", not
just "PostgreSQL". `spec.display.description` should answer "what is this for" in one
sentence. Tags are `{key, value}`: technology + signal types + environment when known.

##### Step 3b-ii.5: Shape check before save

`signoz://dashboard/widgets-examples` is the source of truth for panel
required fields, panel-type-specific shapes, plugin `kind` names, and
common write-shape errors. Re-skim it before serialising any custom panel
JSON.

Every builder query and formula entry must carry a positive `limit` and non-empty
`order`. Raw list and trace-request panels default to 100 with timestamp-desc ordering
(raw logs add id); a deliberately smaller list page may lower `limit`. Aggregate panels use 100 with
the primary aggregation desc. Formula outputs use 100 with `__result desc`; every referenced base query uses 10000
because base limits apply before formula evaluation. Find those inputs from every formula expression, including
formulas with `disabled: true`, following references until every base `builder_query` leaf is reached. This dependency
walk chooses bounds only; it does not establish deterministic formula-to-formula evaluation order, so dry-run the
complete composite payload. A metrics `order` key is the composed `spaceAggregation(timeAggregation(metricName))`
expression; the bare metric name is rejected, while `__result` and groupBy keys are accepted.
Time-series top-N ranks groups over the whole window and can omit a short-lived local spike. Narrow filters/grouping
if formula-input cardinality can exceed 10000.

Two rules `widgets-examples` does not call out, but
`signoz_create_dashboard` enforces: **no `JSON.stringify` on
arrays/objects** — `spec`, `panels`, `layouts`, `tags`, and `variables`
are native JSON — and **one query per panel**, so a panel plotting two
series carries a single `signoz/CompositeQuery` envelope holding both.

##### Step 3b-ii.6: Dry-run before save (mandatory)

For every query-bearing panel, read the compact
[`dashboard-to-query-builder-v5` reference](./references/dashboard-to-query-builder-v5.md).
The panel already stores the execution spec, so lift it into the outer envelope
and call `signoz_execute_builder_query` with that payload, never panel JSON.
Dry-run over a short absolute Unix-ms window — usually the last 30-60 minutes,
never the panel's display range by reflex; apply the reference's dry-run hygiene
rules before widening or retrying after a timeout. Use representative variable
values in the dry-run copy and keep `$var` in `signoz_create_dashboard`.

If the reference's safety gate finds an unsupported execution field, report the
panel as unvalidated and continue only after explicit user acceptance. Server or
validation errors block. Unexpected empty results block unless the user already
accepted absent telemetry.

##### Step 3b-ii.7: Preview, save, report

1. **Preview** Emit a one-paragraph plain-language summary of what
   will be created — no JSON dump. A 20–30 panel payload is hundreds
   of lines the user cannot meaningfully review in chat. Call out any
   validation gap the user explicitly accepted.

   > **Summary**: This dashboard tracks [signals] for [scope], with
   > sections [list]. Variables: [list].
   > Dry-run: [N] panels passed. Unvalidated: [none / accepted gaps].
   > Data: [confirmed / pending ingestion by explicit user choice].

2. **Save** Call `signoz_create_dashboard` with the payload.

3. **Report** Tell the user:
   - The created dashboard's id and title.
   - Panel count and section breakdown.
   - Which variables are wired.
   - Two follow-up offers: "Want me to adjust panels, layout, or
     variables?" and "Want me to wire alerts for any of these signals?
     (`signoz-creating-alerts`)".

## Guardrails

- **Strict inputs over guessing** Resource scope is required for custom
  builds. If missing, stop and ask the user (see *Required inputs*
  above). A guessed scope on a shared dashboard is harder to clean up
  than asking.
- **Always paginate `signoz_list_dashboards`** Stopping at page
  1 misses duplicates and produces clutter.
- **Duplicate check first** The user's only two upfront options are
  "modify an existing one" or "create a new one" — never offer
  template-import as a separate top-level choice.
- **Template-first on the create path** Once the user has chosen to
  create, always run `signoz_list_dashboard_templates` before any
  `signoz_create_dashboard` call. If a matching template exists,
  import it via `signoz_import_dashboard` (just inform the user);
  only build from scratch when no template matches.
- **No-data probe is mandatory before save** Run the pre-flight probe
  (Step 3b-i.1 / Step 3b-ii.2) before `signoz_import_dashboard`
  / `signoz_create_dashboard`. A "No data" dashboard is a worse
  outcome than one extra confirmation prompt. Skip only if the user has
  explicitly opted out for this request.
- **Validate custom builds before save** Follow Step 3b-ii.6; never treat a
  dry-run that omits active query semantics as validated.
- **Preview before save on custom builds** Emit the plain-language
  summary before `signoz_create_dashboard` so the human can
  intervene on intent.
- **Prefer OTel attribute names** `service.name` not `service`,
  `host.name` not `host`. Wrong names produce empty panels. Verify the
  exact key (`deployment.environment` vs `deployment.environment.name`,
  for instance) against `signoz_get_field_keys` rather than guessing —
  installs running classic OTel semconv emit the no-`.name` form.
- **No metric guessing** For custom builds, verify metric names with
  `signoz_list_metrics` before authoring. Wrong names produce
  empty panels and the user only finds out later.
- **Valid JSON shapes only** Follow the schema documented in
  `signoz://dashboard/*` MCP resources. Required panel and query
  fields are listed in `signoz://dashboard/widgets-instructions` and
  `signoz://dashboard/widgets-examples`. Never wrap arrays/objects in
  `JSON.stringify`; enforce the panel/grid-item bijection, field types, and
  plugin kinds from Step 3b-ii.4.
- **Scope boundary** This skill creates dashboards. The moment the
  user asks to modify, edit, rearrange, or extend an existing dashboard
  — including immediately after import — hand off to
  `signoz-modifying-dashboards`. Do not call
  `signoz_update_dashboard` or `signoz_patch_dashboard` from this skill.

## Examples

Four canonical flows — template happy path, template choice, duplicate
found, custom build — live in [`references/examples.md`](references/examples.md).