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 two sharp edges (full-body replace, and a source change moves the view to another Explorer); 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 to adapt only where they match the current intent and schema.

Operation flows

Create a view

1. Resolve source: the Explorer the view belongs to. The Explorers with a saved-views page today are traces, logs, metrics, and meter. Newer sources (for example ai_observability) are accepted but have no Explorer page yet; use one only when the user names it, and say so. 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. Preserve raw query entries exactly where the v2 resource permits them, including disabled flags and PromQL or SQL envelopes. On create, a PromQL or SQL envelope must come verbatim from the user or an existing view; signoz-generating-queries does not author it, so validate it in Step 5.

4. Enforce the signal rule in every builder_query spec. A mismatch saves without error, and the Explorer renders only views whose queries match its signal, so the view is unusable.

   • For traces / logs / metrics: signal == source. A source:"traces" view with signal:"logs" never renders in the Traces Explorer.
   • 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" inside a view whose top-level source is metrics files it under the Metrics Explorer, where the Cost Meter page never lists it.

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.
   • PromQL or SQL envelope → signoz_execute_builder_query with that exact envelope over a short recent window. The builder probes above do not apply to it.

   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.

For saved log filters, use search('timeout') for explicit cross-field full-text search. Use scoped forms such as search('timeout', body) only when that exact scope is intended. Once field discovery identifies the target, prefer a canonical field predicate such as body CONTAINS 'timeout'. Escape backslashes before apostrophes in literal values. The signoz_search_logs.searchText convenience (searchScope chooses where it matches; the default is the log body) is not a substitute for preserving an authored search() filter.

List or find views

source is optional on signoz_list_views. Pass it when the user names an Explorer. When the user did not specify one and is searching by name, call it once with source omitted: that single call lists every Explorer's views, so do not guess a source and do not fan out one call per source. 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 listing (one source, or all Explorers when source is omitted) 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 unless the user asked to move the view: changing source on update moves the view to that Explorer's list. Treat a move as a deliberate change with two consequences to state in the preview: the view disappears from the old Explorer, and its queries must satisfy the Step 4 signal rule for the new source or the moved view never renders. For a meter or metrics move, also flip the per-query source:"meter" field to match.
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, omit it so one call covers every Explorer.
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

Operation	Tools called	Key guard
Create	read signoz://view/instructions + signoz://view/examples → signoz-generating-queries → sample fetch on exact filter → preview → signoz_create_view	Mandatory pre-save sample fetch; preview before write; no v1 fields
List	signoz_list_views (omit source to list every Explorer in one call)	Check pagination.hasMore
Get	signoz_get_view(id)	Returns canonical body for update
Update	signoz_get_view → modify → sample fetch if spec.queries changed → diff preview → signoz_update_view	Full replacement; name immutable (rename = spec.displayName); a source change moves the view; diff preview required
Delete	signoz_list_views → signoz_get_view → confirm → signoz_delete_view	Get-before-delete mandatory; fresh confirmation

Common mistakes

Mistake	Fix
Hand-composing spec.queries from examples or memory (even after reading signoz://view/examples)	Use the Skill tool to invoke signoz-generating-queries; reading examples and validating with signoz_search_traces is not a substitute
Sending the retired v1 shape: compositeQuery, category, tags, extraData, or the sourcePage parameter	The v2 API takes source + spec; read both schema resources first
Copying the full executable query envelope into the saved spec	Copy only query.compositeQuery.queries, then construct the spec {displayName, panelType, requestType, queries}; exclude the execution-only schemaVersion, start, end, requestType, formatOptions, and variables
Lifting an attribute name from a metric, alert rule, or sibling view and using it in a source=traces / =logs view filter without re-verifying on the destination signal	Field keys are signal-scoped; an attribute on metrics may not exist on traces or logs. Always re-check via signoz_get_field_keys signal=<destination signal> (for a meter view, signal=metrics source=meter, never signal=meter) and run the mandatory pre-save sample fetch; the key check is necessary but not sufficient
Skipping the pre-save sample fetch because signoz-generating-queries already validated the query	The sub-skill validates the query it authored; the filter you persist may have been edited or lifted since then. The Step 5 sample fetch is mandatory regardless
Skipping signoz_get_view before delete (relying on list UUID alone)	Always call signoz_get_view to confirm name+source before signoz_delete_view
Trying to rename the machine name on update	name is immutable server-side; change spec.displayName for the visible label
signal ≠ source in builder query	For traces/logs/metrics, every builder_query.signal must equal the view's source. For a meter view, use signal:"metrics" + source:"meter" (not signal:"meter"). SigNoz saves the mismatch; the Explorer never renders it
Filing a Cost Meter view under source:"metrics" (with source:"meter")	Cost Meter views go under source:"meter"; otherwise they're invisible in the Meter Explorer and mis-filed under Metrics. The write succeeds either way, so check it before saving
Changing source on update without the user asking	A source change moves the view to another Explorer; keep the fetched source unless a move is the intent, and preview the move explicitly
Calling signoz_list_views once per source when no source was given	Omit source; one unscoped call lists every Explorer's views
Partial update body (omitting unchanged fields)	GET full body first → modify only changed fields → replace with source + full spec
Declaring "no such view" after only page 1	Check pagination.hasMore; continue with offset = pagination.nextOffset
Normalizing away PromQL, SQL, disabled flags, selected fields, or unknown authored content	Preserve every field allowed by the current typed resource across read-modify-write; strip only known server-populated fields

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.