signoz-managing-views

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, Metrics, or Cost Meter page: name + filters + panel type, scoped to one source. They are not dashboards and not alerts.

The tools call the v2 /api/v2/saved_views API. The create/update payloads are the typed v2 shape (source + spec), not the retired v1 compositeQuery/category/tags/extraData shape; the sourcePage parameter was renamed to source.

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_create_view, signoz_list_views, signoz_get_view, signoz_update_view, signoz_delete_view, signoz_get_field_keys, signoz_get_field_values). Before running the workflow, confirm the 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 source or name).
• Inspect a single view's filter or panel type.
• Update a view: rename its display label, 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 spec from memory. The correct schema is the v2 typed spec (schemaVersion: "v2") described in these resources; the retired v1 fields (compositeQuery, category, tags, extraData) are not accepted.

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

• signoz://view/instructions: SavedView field reference, source rules, the spec fields, the GET-then-replace update flow, the minimal create body.
• signoz://view/examples: round-tripped v2 payloads (traces list, logs list, metrics graph, and a Cost Meter graph) you can adapt verbatim.

Operation flows

Create a view

1. Resolve source: must be exactly one of traces, logs, metrics, meter. If the user's intent is ambiguous ("save this query"), ask which Explorer they mean. It cannot be inferred from filter strings alone. Use meter for Cost Meter (usage / billing) views; it is a distinct Explorer page from metrics, even though the query runs on the metrics signal (see Step 4).

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.

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_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. For a meter view, tell signoz-generating-queries it's a Cost Meter query (source=meter) so discovery hits the meter store, not the default one. Retain the exact queries array from its successful signoz_execute_builder_query validation call, then translate it explicitly:

   execution query.compositeQuery.queries
     -> saved spec.queries

   Build the spec argument to signoz_create_view as { "displayName": "<human label>", "panelType": "<list|graph|table|value|trace>", "requestType": "<raw|time_series|scalar|trace>", "queries": <copied queries> }, adding selectedFields / display when the Explorer layout calls for them. Copy the queries array losslessly, but do not copy the execution-only envelope fields schemaVersion, start, end, requestType (the execution envelope's), formatOptions, or variables; do not put a query key or a compositeQuery object inside the saved spec. Choose panelType and requestType from the saved-view intent rather than inventing them from the execution envelope. Set the top-level name (a DNS-1123 label: lowercase letters, digits, hyphens) or pass generateName: true to derive it from spec.displayName. schemaVersion is always "v2"; the server fills it in when omitted. The copied queries must retain every positive spec.limit and v5 spec.order entry losslessly. Never translate them to dashboard orderBy. Raw/list views use 100 rows (logs: timestamp/id desc; traces: timestamp desc); standalone aggregate views and formula results use 100 groups. Builder queries referenced by a formula use 10000 because their limits are applied before evaluation. Order by the primary aggregation or __result desc as appropriate. Time-series top-N ranks groups over the whole selected window and can omit a short-lived local spike.

4. Enforce the signal rule in every builder_query spec.

   • For traces / logs / metrics: signal == source. A source:"traces" view with signal:"logs" is a server-side error.
   • For meter (Cost Meter): signal:"metrics" and source:"meter": a Cost Meter view is queried on the metrics signal against the meter store. Omitting source:"meter" silently queries the default metrics store; setting source:"meter" on a non-meter source view is rejected.

5. Mandatory pre-save sample fetch. Probe with the exact filter from spec.queries[0].spec against the destination signal:

   • source=traces → signoz_search_traces with limit=1
   • source=logs → signoz_search_logs with limit=1
   • source=metrics → 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.
   • source=meter → signoz_query_metrics with the metricName from spec.aggregations[0].metricName, source=meter, the same filter, timeRange=24h (Cost Meter rolls up hourly, so a 1h window can be a single partial bucket), requestType=scalar.

   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_create_view, show the user a summary: name, source, panelType, the full filter expression, and the Step 5 probe result ("sample fetch: N rows in last 1h"; for a meter view the probe window is 24h, so report it as such). For a human in the loop, wait for confirmation. For an autonomous agent, log the preview and proceed.

7. Call signoz_create_view. On success the response data carries the new view's id (HTTP 201 upstream). The server populates id, createdAt/By, updatedAt/By; never send those.

List or find views

signoz_list_views requires a source. If the user did not specify one and is searching by name, call it once per source (traces, logs, metrics, meter) and merge; do not guess. Use the name parameter for server-side partial-match filtering when the user gives a substring; do not fetch everything and grep client-side. There is no category filter; it was removed with the v2 API.

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 source 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_get_view with the UUID (id; the legacy alias viewId also works). The returned data object is the canonical SavedView shape; it is what you pass back to signoz_update_view. Treat that data as the source of truth, not whatever the user described from memory.

Update a view (GET-then-replace)

signoz_update_view is a full replacement. Sending a partial body wipes the unspecified fields. The machine name is immutable server-side; renaming a view means changing spec.displayName. The flow:

1. 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) and drop name; the MCP server strips them for you, but omitting them up front makes the diff readable.
3. If the update changes spec.queries (new filter, different panel type, different aggregation), invoke signoz-generating-queries to build and validate the new query before proceeding. Do not hand-edit spec.queries from the user's description; the same Step 4 signal rule applies (including the meter case: signal:"metrics" + source:"meter"), and panelType changes often imply a stepInterval change too. For a meter view, tell signoz-generating-queries it is a Cost Meter query (source=meter) so it discovers and validates against the meter store. Derive the replacement spec.queries from the successful execution query using the same explicit translation as Create: copy only query.compositeQuery.queries. Exclude the execution-only envelope fields. For pure metadata tweaks (display-label rename), skip this step and do not touch spec.queries.
4. Modify only the field(s) the user asked to change. Keep source unchanged; a cross-source move is rejected.
5. Mandatory pre-save sample fetch, when spec.queries 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 (display-label rename).
6. Show a diff-style preview before writing. One line per changed field: spec.displayName: "slow-checkout" → "slow-checkout-p99". Explicitly note any fields that are unchanged (e.g. "queries: unchanged") and include the Step 5 probe result when spec.queries changed. This prevents silent mistakes and gives the user a chance to catch a wrong target view. Wait for confirmation on any change to spec.queries, since that changes what the view actually shows.
7. Call signoz_update_view with { "id": "<id>", "view": <modified data> }. view must carry source and the full spec; success is an empty 204 upstream.

Delete a view

Deletion is destructive and immediately removes the view from the shared list; any team member who had the view bookmarked will see it disappear. Depending on the host application, the user may be offered a one-click restore action shortly after the delete (the SigNoz Assistant captures a snapshot and exposes a restore action), but treat that as a recovery affordance, not a substitute for getting the delete right. Treat this like dropping a row from a shared table:

1. List to locate. Call signoz_list_views to find the view by name. If source is unknown, search all four sources (traces, logs, metrics, meter).
2. Get to confirm, mandatory. Call signoz_get_view with the UUID from step 1. Do NOT skip this step even when you got the UUID from a list result that looks correct. List results are paginated and a name match is not a UUID guarantee; signoz_get_view is the confirmation that the UUID maps to the view the user named. Never call signoz_delete_view on a UUID without a prior signoz_get_view confirming the matching name and source.
3. Show and ask. Present the resolved view's name and source, and explicitly ask for confirmation. Do not auto-confirm based on the original prompt, even an emphatic one; destructive operations get a fresh confirmation against the resolved target.
4. Call signoz_delete_view. Report success with the deleted view's name (not just the UUID), so the user can recognize it.

For autonomous agents without a human in the loop: refuse delete unless the calling context has been explicitly authorized for destructive operations on saved views, and log the resolved view metadata before the call.

Guardrails

• Mandatory pre-save sample fetch on create and on spec.queries updates. Step 5 of each flow runs a 1-row probe against the destination signal using the exact filter from the about-to-save payload. Skipping is equivalent to skipping get-before-delete. The Step 3 signoz-generating-queries delegation is necessary but not sufficient; it validates the query it authored, not the filter you persist after edits.

  Cross-signal-lift footgun: field keys are signal-scoped. An attribute observed on metrics (e.g. oauth.error_code on a counter) may not exist on traces or logs for the same tenant, even when emitted by the same service. Lifting an attribute from a sibling dashboard panel, alert rule, or view that targets a different signal is the most common source of empty saved views. signoz_get_field_keys signal=<destination signal> is necessary but not sufficient; sparse emission still produces zero-result views. Only the sample fetch confirms. The destination signal equals source for traces/logs/metrics; for a meter view it is signal=metrics with source=meter (never signal=meter).

  A saved view returning zero rows under its own filter is a permanent artifact in a shared workspace; the human preview can't tell from JSON that the filter won't match, and autonomous mode has no preview, so the sample fetch is the only safety net.

• Translate the execution envelope before saving. The executable query and saved-view spec intentionally have different outer shapes. Save exactly spec: {displayName, panelType, requestType, queries, ...} in the create call or view.spec, where queries comes from the validated execution query.compositeQuery.queries. Never copy the range, request, formatting, or variables envelope into a view.

Quick reference

Common mistakes

Reporting back

After any write (create / update / delete), include in your reply:

• The view's name and UUID.
• The source.
• A direct link only if the MCP response or SigNoz frontend provides a canonical URL, or the user explicitly asks for one. Do not fabricate frontend routes; saved-view paths differ per signal and change over time. When in doubt, omit the link and report the UUID + source.
• For updates, what changed (one-line diff).
• For deletes, an explicit "deleted" confirmation with the name.

Follow-up suggestions

After a view operation, you may surface up to 3 follow-up intents that match what just happened. The host application renders them; follow the host's UI rendering rules for the exact mechanism. Use your judgment about what's natural for the user's context; do not pad to 3.

Two anti-rules that override your judgment:

• Read-only stays read-only at the chip surface. After list / get / find, do not offer chips that propose a write (e.g. "Update this view", "Delete this view"). That contradicts the read-only stop rule in Reporting back below. Chips that re-run the view's underlying query are fine; those stay on the read path. If the user's next message names an update or delete, route from there.
• Do not duplicate host-injected actions. If the host offers a restore action after a delete (the SigNoz Assistant does), do not also surface restore as a follow-up; it would render twice.

When the user is purely exploring ("just listing my views", "what's in here?") and signals no further intent, skip follow-ups entirely. Offering no follow-ups is better than offering wrong ones.

Describe follow-ups by user intent, not by tool or skill name. The label the user clicks should read like the user's next prompt.

Read-only operations (list, get) should report concisely (name, id, source, filter expression, panel type) and stop. Don't narrate the schema back to the user.