signoz-modifying-dashboards

What this skill does

# Dashboard Modify

## Prerequisites

This skill calls SigNoz MCP server tools (`signoz:signoz_get_dashboard`,
`signoz:signoz_update_dashboard`, `signoz:signoz_list_dashboards`, `signoz:signoz_list_metrics`).
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
fall back to raw HTTP calls or hand-edit dashboard JSON without the MCP tools.

## When to use

Use this skill when the user asks to:
- Add, remove, or edit panels/widgets on an existing dashboard
- Change a panel's query, title, type, or display settings
- Add, remove, or edit dashboard variables
- Rename or re-describe a dashboard
- Rearrange panel layout or resize panels
- Change a panel type (e.g., graph to table, value to graph)
- Add or modify thresholds on a panel
- Update tags on a dashboard

Do NOT use when:
- User wants to understand what a dashboard shows → `signoz-explaining-dashboards`

## Instructions

### Step 1: Identify the target dashboard

Determine which dashboard the user wants to modify. 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 modify.

### Step 2: Fetch the current dashboard state

Call `signoz:signoz_get_dashboard` with the dashboard UUID to retrieve its full
configuration. This is **mandatory** — `signoz:signoz_update_dashboard` requires the
complete post-update state, not a partial patch. Never skip this step.

Examine the response to understand:
- Current widgets and their IDs
- Current layout positions (x, y, w, h in the 12-column grid)
- Current variables
- Current queries on each panel
- The `panelMap` structure (row-to-child mappings)

### Step 3: Plan the modification

Based on the user's request, plan the changes.

**Confirm with the user before applying if:**
- The modification is **destructive** — removing panels, deleting variables,
  replacing an entire query with a different one, changing a panel's `dataSource`
  (e.g., traces → logs), or fundamentally altering what data is shown (changing
  aggregation from p99 to avg, removing groupBy dimensions)
- The request is **ambiguous** — multiple panels could match "the latency panel"
- The change is **large** — restructuring sections, adding many panels at once

**Destructive means data loss or silent behavior change.** Even if the user says
"just do it quickly," a brief confirmation ("I'll remove 'Memory Fragmentation'
permanently — OK?") takes seconds and prevents irreversible mistakes. User urgency
does not override this guardrail.

**Non-destructive changes proceed directly:** renaming, adding a single panel,
changing a unit, adding a variable, changing panel type (the query is preserved),
adjusting layout, adding thresholds.

**Compound modifications:** When a request involves multiple changes (e.g., remove a
panel + add a panel + rename), plan all changes against the fetched state and apply
them as a single update. Do not apply and re-fetch between changes.

### Step 4: Apply the modification

Merge the planned changes into the full dashboard JSON from Step 2.

**Modification rules:**

- **Preserve everything you are not changing.** Copy the entire dashboard object
  and only modify the specific fields the user asked about. Do not drop widgets,
  variables, layout items, or panelMap entries that are not part of the change.

- **Adding a panel:**
  1. Create a new widget with a UUID for its `id` (use `crypto.randomUUID()` format).
  2. Include **all** required widget fields: `id`, `title`, `description`,
     `panelTypes`, `query`, `opacity` ("1"), `nullZeroValues` ("zero"),
     `timePreferance` ("GLOBAL_TIME" — note the deliberate misspelling),
     `stepSize` (60), `yAxisUnit`, `isStacked` (false), `fillSpans` (false),
     `isLogScale` (false), `mergeAllActiveQueries` (false), `thresholds` ([]),
     `softMin` (0), `softMax` (0), `legendPosition` ("bottom"), `columnUnits` ({}),
     `customLegendColors` ({}), `selectedLogFields` ([]), `selectedTracesFields`
     ([]), `contextLinks` ({"linksData": []}).
  3. Add a layout entry with `i` matching the widget ID, and appropriate `x`, `y`,
     `w`, `h` values in the 12-column grid.
  4. If the dashboard uses rows, add the panel's layout to the appropriate row's
     `panelMap[rowId].widgets` array. If the dashboard has no rows (empty
     `panelMap`), skip panelMap — the panel lives at the top level.
  5. For query construction, read the `signoz://dashboard/query-builder-example`
     MCP resource for the v5 builder query format. Use the signal-specific
     resources as needed (`signoz://dashboard/promql-example`,
     `signoz://dashboard/clickhouse-*`, `signoz://traces/query-builder-guide`).
  6. All modified panels are validated below as a hard requirement —
     see the "Dry-run modified panels" step before
     `signoz:signoz_update_dashboard` and the "Mandatory dry-run
     before update" guardrail. Author the JSON here as you intend to
     save it — the dry-run uses the exact shape from `queryData`.

- **Removing a panel:** Remove the widget from `widgets`, its entry from `layout`,
  and its entry from the parent row's `panelMap.widgets` (if it exists in panelMap).
  **Do not** try to auto-compact or shift `y` positions of remaining panels — the
  SigNoz frontend grid engine handles gap-closing automatically. Simply remove the
  three references (widget, layout, panelMap entry) and leave all other positions
  unchanged.

- **Editing a panel's query:** Replace the query object on the target widget. Keep
  all other widget fields intact. If the user is changing *what* the panel
  measures (not just renaming a label), the new query is validated by the
  mandatory dry-run step below (and the "Mandatory dry-run before update"
  guardrail) — replacing a working query with a broken one is a destructive
  change the user will only notice after the panel goes empty.

- **Changing panel type:** Update `panelTypes` and handle type-specific fields:
  - `graph` → `table`: add `columnUnits` ({}) and `columnWidths` ({}) if missing.
    Graph-only fields like `isStacked`, `fillSpans`, `isLogScale` become inert but
    are harmless to leave.
  - `graph`/`table` → `histogram`: add `bucketCount` (30) and `bucketWidth` (0).
  - Any → `list` (logs): add `selectedLogFields` array.
  - Any → `list` (traces): add `selectedTracesFields` array.
  - Keep the existing query intact — the data source and query are independent of
    the visualization type.

- **Adding/editing variables:** Add or update entries in the `variables` map. Use
  OTel attribute names for the underlying attribute (e.g., `service.name`,
  `deployment.environment.name`). Use DYNAMIC type when the values come from a
  standard telemetry attribute. Each variable needs a UUID for `id` and `key`.

- **Rearranging layout / side-by-side placement:**
  - Dashboard uses a **12-column grid**. `x` ranges 0–11, `w` ranges 1–12.
  - Two panels side-by-side: each gets `w: 6`, first at `x: 0`, second at `x: 6`,
    same `y` and `h`.
  - Three panels in a row: `w: 4` at `x: 0`, `x: 4`, `x: 8`.
  - When resizing an existing panel to make room, update its `w` and `x`, then
    place the new panel in the freed space at the same `y`.
  - Common heights: `h: 6` for graphs/tables, `h: 2`–`h: 3` for value panels,
    `h: 1` for row headers.
  - **Keep panelMap in sync**: whenever you change `x`, `y`, `w`, or `h` in the
    top-level `layout