signoz-managing-views

What this skill does

# Managing Saved Views

Create, read, update, and delete SigNoz **saved Explorer views** via the
SigNoz MCP server. A saved view is a reusable snapshot of an Explorer query
on the Logs, Traces, or Metrics page — name + filters + panel type, scoped
to one `sourcePage`. They are not dashboards and not alerts.

This skill covers the full CRUD surface in one place because the operations
share the same schema, the same identity model (UUID per view), and the same
prerequisite resources. The only operation with real blast radius is delete,
and update has a sharp edge (full-body replace) — both get explicit guards
below.

## Prerequisites

This skill calls SigNoz MCP server tools (`signoz:signoz_create_view`,
`signoz:signoz_list_views`, `signoz:signoz_get_view`,
`signoz:signoz_update_view`, `signoz:signoz_delete_view`,
`signoz:signoz_get_field_keys`, `signoz:signoz_get_field_values`). Before
running the workflow, confirm the `signoz:signoz_*` tools are available. If
they are not, run `signoz-mcp-setup` first to initialize or repair the MCP
connection. Do not fall back to raw HTTP calls or fabricate view payloads
without the MCP tools.

## When to use

Use this skill when the user wants to:

- **Create** a saved view from a current or described Explorer query.
- **List / find** existing views (by `sourcePage`, name, or category).
- **Inspect** a single view's filter or panel type.
- **Update** a view — rename, recategorize, or change its filter,
  panel type, or aggregations.
- **Delete** a view that is no longer useful.

Do NOT use when the user wants to:

- Build a dashboard panel → `signoz-creating-dashboards` /
  `signoz-modifying-dashboards`.
- Run an ad-hoc Explorer query without saving it → `signoz-generating-queries`.
- Create or change an alert rule → `signoz-creating-alerts`.

## Schema reference

**Read both resources BEFORE composing any create or update payload.** Do not
hand-compose a `compositeQuery` from memory — the correct schema is not the
legacy `builder.queryData` format; it is the v5 spec described in these
resources. Sending a legacy payload causes a silent HTTP 400.

Read both MCP resources by URI using your client's resource-read mechanism:

- `signoz://view/instructions` — SavedView field reference, `sourcePage`
  rules, the GET-then-PUT update flow, the minimal create body.
- `signoz://view/examples` — three round-tripped payloads (traces list, logs
  list, metrics graph) you can adapt verbatim.

The server returns HTTP 400 on legacy v3/v4 fields (`builder`, `promql`,
`unit`, top-level `id`, `queryFormulas`, `queryTraceOperator`) — the failure
mode is silent for the user, so reading the resources first is mandatory, not
optional.

## Operation flows

### Create a view

1. **Resolve `sourcePage`** — must be exactly one of `traces`, `logs`,
   `metrics`. If the user's intent is ambiguous ("save this query"), ask
   which Explorer they mean. It cannot be inferred from filter strings alone.
2. **Read the schema resources.** Read both `signoz://view/instructions`
   and `signoz://view/examples` using your client's resource-read mechanism
   before composing any payload. Do not skip this step even if you think
   you know the schema — the legacy `builder.queryData` format is rejected
   with HTTP 400.
3. **Build the query using `signoz-generating-queries` — mandatory.** Use
   the `Skill` tool to invoke `signoz-generating-queries`. The sub-skill
   handles field discovery, type checking, and live-data validation in one
   pass — adapting an example payload from `signoz://view/examples` or
   running a bare `signoz:signoz_search_traces` call skips the field-type
   checks and service-name resolution that catch silent 400s before they
   become permanent bad views. Skipping it means a malformed filter becomes
   a saved view that must be deleted and recreated.
4. **Enforce `signal == sourcePage`** in every `builder_query` spec. A
   `sourcePage:"traces"` view with `signal:"logs"` is a server-side error.
5. **Mandatory pre-save sample fetch.** Probe with the **exact** filter
   from `compositeQuery.queries[0].spec` against the destination
   signal:
   - `sourcePage=traces` → `signoz:signoz_search_traces` with `limit=1`
   - `sourcePage=logs` → `signoz:signoz_search_logs` with `limit=1`
   - `sourcePage=metrics` → `signoz:signoz_query_metrics` with the
     `metricName` from `spec.aggregations[0].metricName` plus the same
     filter, `timeRange=1h`, `requestType=scalar`. Repeat per metric
     query if the view has multiple. The tool requires `metricName` —
     a filter-only probe is not supported.

   Required even if Step 3 ran cleanly: the sub-skill validates the
   query *it* authored, not whatever you persist after edits or lifts.
   Empty → save anyway / revise / abort. Autonomous mode without
   authorization to persist empty views: abort and escalate.
6. **Preview before writing — this step is not optional.** Before calling
   `signoz:signoz_create_view`, show the user a summary: name, sourcePage,
   panelType, the full filter expression, and the Step 5 probe result
   ("sample fetch: N rows in last 1h"). For a human in the loop, wait
   for confirmation. For an autonomous agent, log the preview and proceed.
7. Call `signoz:signoz_create_view`. The server populates `id`,
   `createdAt/By`, `updatedAt/By` — never send those.

### List or find views

`signoz:signoz_list_views` requires a `sourcePage`. If the user did not
specify one and is searching by name, call it once per signal (traces,
logs, metrics) and merge — do not guess. Use the `name` and `category`
parameters for server-side partial-match filtering when the user gives a
substring; do not fetch everything and grep client-side.

The response paginates. **Always check `pagination.hasMore`** before
concluding a view does not exist. Default page size is 50; pass `offset =
pagination.nextOffset` to continue. A view is only confirmed missing for a
given `sourcePage` once you have walked pages until `hasMore = false`. As
long as `hasMore = true`, keep paginating — there is no page-count cap.

### Get a single view

Use `signoz:signoz_get_view` with the UUID. The returned `data` object is
the canonical SavedView shape — it is what you pass back to
`signoz:signoz_update_view`. Treat that data as the source of truth, not
whatever the user described from memory.

### Update a view (GET-then-PUT)

`signoz:signoz_update_view` is a **full-body replace** (HTTP PUT
upstream). Sending a partial body wipes the unspecified fields. The flow:

1. `signoz:signoz_get_view` with the view's `id` → returns
   `{ "status": "success", "data": { ...SavedView... } }`.
2. Take the `data` object. Strip server-populated fields (`id`,
   `createdAt`, `createdBy`, `updatedAt`, `updatedBy`) — the MCP server
   strips them for you, but omitting them up front makes the diff
   readable.
3. **If the update changes `compositeQuery`** (new filter, different panel
   type, different aggregation), invoke `signoz-generating-queries` to
   build and validate the new query before proceeding. Do not hand-edit
   `compositeQuery` from the user's description — the same
   `signal == sourcePage` rule applies, and `panelType` changes often
   imply a `stepInterval` change too. For pure metadata tweaks (rename,
   recategorize), skip this step and do not touch `compositeQuery`.
4. Modify only the field(s) the user asked to change.
5. **Mandatory pre-save sample fetch — when `compositeQuery` changed.**
   Run the 1-row probe from the Create flow's Step 5 against the new
   filter. Empty → save anyway / revise / abort. Skip only for pure
   metadata tweaks (rename, recategorize).
6. **Show a diff-style preview before writing.** One line per changed
   field: `name: "slow-checkout" → "slow-checkout-p99"`. Explicitly note
   any fields that are unchanged (e.g. "compositeQuery: unchanged") and
   include the Step 5 probe result when `compositeQuery` changed. This
   prevents silent mistakes and gives the user a chance to cat