signoz-explaining-dashboards

What this skill does

# Dashboard Explain

## Prerequisites

This skill calls SigNoz MCP server tools (`signoz:signoz_get_dashboard`,
`signoz:signoz_list_dashboards`). Before running the workflow, confirm the
`signoz: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 guess at a dashboard's contents from its
title alone.

## When to use

Use this skill when the user asks to:
- Understand, explain, or interpret an existing dashboard
- Get a walkthrough of what panels show and why they matter
- Know what to watch for or what healthy/unhealthy looks like on a dashboard
- Understand the variables, filters, or queries on a dashboard

Do NOT use when:
- User wants to modify an existing dashboard → `signoz-modifying-dashboards`

## Instructions

### Step 1: Identify the target dashboard

Determine which dashboard the user wants explained. If the user provides a
dashboard name, UUID, or it is clear from context (e.g., an @mention or
auto-context providing a dashboard resource), use that.

If the target dashboard is ambiguous:
1. Call `signoz:signoz_list_dashboards` to list existing dashboards. **Paginate through
   all pages** — check `pagination.hasMore` in the response. If `hasMore` is true,
   call again with `offset` set to `pagination.nextOffset` and repeat until all
   pages are exhausted. Never stop at the first page.
2. Present matching candidates to the user and ask which one to explain.

### Step 2: Fetch the full dashboard configuration

Call `signoz:signoz_get_dashboard` with the dashboard UUID. This is **mandatory** — you
need the complete JSON to explain the dashboard accurately. Never guess based on
the title alone.

Examine the response to understand:
- `title`, `description`, `tags` — the dashboard identity and author-provided context
- `variables` — dashboard-level filters (dropdowns the user can change)
- `widgets` — the panels, their types, titles, and queries
- `layout` — how panels are arranged in the 12-column grid
- `panelMap` — which panels belong to which row sections

### Step 3: Build the explanation

Structure your explanation in this order:

**1. Overview** — One paragraph summarizing the dashboard's purpose, what it
monitors, and what data sources it draws from (metrics, traces, logs). Mention
the `tags` if they provide useful context.

**2. Variables and filters** — Explain each variable:
- Name and what it filters (e.g., "The `service_name` variable filters all panels
  to a specific service")
- Type: DYNAMIC (auto-populated from telemetry), QUERY (SQL-driven dropdown), or
  TEXTBOX (free-form input)
- Whether it supports multi-select and has "ALL" option
- Note if any panels do NOT reference a variable in their filters — changing that
  variable dropdown would not affect those panels, which can be confusing

**3. Panel-by-panel walkthrough** — Group panels by their row sections using the
`panelMap` structure (row widget titles are the section headers). If the dashboard
has no rows (empty `panelMap`), walk through panels in layout order (by `y` then
`x` position) and organize by logical theme. For each panel:
- **Title** and **panel type** (graph, value, table, bar, pie, histogram, list)
- **What it shows** — interpret the query in plain language. For builder queries,
  explain the metric/data source, aggregation, filters, and groupBy. For formulas,
  explain each sub-query and how the formula combines them. For ClickHouse SQL or
  PromQL, translate the query intent into plain English.
- **What to watch for** — describe what healthy looks like and what patterns
  indicate trouble. Be specific: "sustained usage above 80% means..." not just
  "watch if it's high". Anchor advice to the actual metric being queried, not
  generic domain knowledge.
- **Unit** — mention the y-axis unit so the user knows how to read the values

For panels with complex queries:
- **Formulas** (queryFormulas): explain each sub-query (A, B, ...) separately,
  then explain what the formula computes and why
- **Multiple queries on one panel**: explain each query and how they relate
- **Functions** (rate, derivative, clampMin/Max, timeShift): explain the transform
  in plain terms (e.g., "rate converts the raw counter into a per-second value")

**4. Dashboard health observations** — After the walkthrough, note any structural
issues you spotted:
- Panels with no queries or empty/disabled queries
- Variables defined but not referenced in any panel filter
- Panels missing thresholds where they would be useful (e.g., utilization panels
  without a saturation warning line)
- Counters displayed without a rate function (raw counters produce ever-increasing
  ramps, not operational rates)
- Very wide step intervals that could hide spikes
- Panels with high-cardinality groupBy that may produce unreadable charts

**5. Coverage gaps** — Based on what the dashboard actually monitors, note
significant observability areas that are absent. Only mention gaps that are
directly related to the technology or domain the dashboard covers — do not
speculate about unrelated areas. Frame as suggestions: "You may want to consider
adding panels for X to cover Y."

### Step 4: Offer next steps

Surface up to 3 follow-up intents based on what the explanation
surfaced — things like running a specific panel's underlying query,
filling a coverage gap, or wiring an alert for an actionable threshold
the user has not yet alerted on. Use your judgment; do not pad to 3.

Skip follow-ups when the user was clearly just onboarding to the
dashboard ("what is this?") and showed no further intent. No chips
beat wrong chips.

## Guardrails

- **Fetch before explaining**: Always call `signoz:signoz_get_dashboard` to get the full
  configuration. Never explain based on the dashboard title or listing alone.
- **Interpret, don't dump**: Translate queries into plain operational language. Never
  show raw query JSON to the user unless they specifically ask.
- **Anchor to actual content**: Base "what to watch for" advice on the actual metrics
  and queries in the dashboard, not on generic domain knowledge unrelated to the
  panels present.
- **Group by sections**: Use the `panelMap` row structure to group panels, not layout
  coordinates. The row titles are the section headers the dashboard author intended.
- **No data queries by default**: Do not run live queries unless the user asks. The
  explain skill is about understanding the dashboard structure, not inspecting
  current data.
- **Paginate dashboard listing**: When searching for a dashboard by name, always
  paginate through all pages of `signoz:signoz_list_dashboards` before concluding a
  dashboard does not exist.
- **All query types**: Handle builder, ClickHouse SQL, and PromQL queries — each
  requires a different interpretation approach. For builder queries, read the
  aggregations, filter expression, and groupBy. For raw SQL/PromQL, parse the
  query string and explain the intent.
- **Scope boundary**: This skill explains dashboards. If the user wants to change
  something after your explanation, redirect to `signoz-modifying-dashboards`.

## Examples

**User:** "Explain my PostgreSQL dashboard"

**Agent:**
1. Calls `signoz:signoz_list_dashboards` (paginates all pages) — finds "PostgreSQL
   Overview" dashboard with UUID `abc-123`.
2. Calls `signoz:signoz_get_dashboard` with UUID `abc-123` — gets full configuration.
3. Provides structured explanation:
   - **Overview**: "This dashboard monitors PostgreSQL database health across
     connections, query performance, buffer cache efficiency, and replication. It
     uses metrics from the OpenTelemetry PostgreSQL receiver."
   - **Variables**: "Two variables — `host_name` (DYNAMIC, filters by
     `host.name`) and `database` (DYNAMIC, filters by `postgresql.database.name`).
     Both support multi-select."
   - **Panels by section**: Walks through each row section, explaining every panel'