Signoz Creating Dashboards

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 | | Modify-or-create choice when duplicates exist | yes | ask the user (Step 2) | | 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 `` 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); only paginate when pagination.hasMore=true. Use pagination.nextOffset directly for the next page; the schema accepts integer or string limit / offset values.

Match by relevance Compare each existing dashboard's lowercased 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 name, uuid, 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, UUID, 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 UUID and the user's intent. Do not call signoz_update_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.

• No template — proceed to Step 3b-ii (custom build).

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.

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

1. 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)".

1. Customization handling If the user asks for any change to the

imported dashboard, hand off to signoz-modifying-dashboards with the new dashboard's UUID 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.

1. Resource scope — which service(s), namespace(s), cluster(s), or

environment(s).

1. Variables — what should be a dropdown vs. a hard-coded filter

(typical: service.name, deployment.environment.name, k8s.cluster.name).

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

1. 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 four core resources before authoring widget 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 widgets array for v5 widget shapes.

• signoz://dashboard/instructions — title, tags, description,

variables.

• signoz://dashboard/widgets-instructions — 7 panel types and layout

rules.

• signoz://dashboard/widgets-examples — complete widget configs with

all required fields (the most important resource — every widget must include id, panelTypes, title, query, selectedLogFields, selectedTracesFields, thresholds, contextLinks).

• signoz://dashboard/query-builder-example — query builder reference,

including operator semantics for filters.items[].op.

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 v5 schema as 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 enums and JSON types exactly. panelTypes: "graph" means time series (never Grafana timeseries); variable types are uppercase (DYNAMIC, CUSTOM). PromQL queryType is valid only for graph, value, bar, and histogram panels; table and pie accept builder or clickhouse_sql; list requires builder. softMax / softMin are numbers, contextLinks is {"linksData": [...]}, and saved having is an array of

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: SigNoz
• Source: SigNoz/agent-skills
• License: MIT
• Homepage: https://signoz.io/docs/ai/agent-skills

Install and usage instructions live in the source repository linked above.