signoz-managing-views

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

通过SigNoz MCP服务器创建、读取、更新和删除SigNoz 已保存Explorer视图。已保存视图是Logs、Traces或Metrics页面上Explorer查询的可复用快照——包含名称+筛选器+面板类型，作用范围限定为单个

sourcePage

。它们不是仪表盘，也不是告警。

本技能将完整的CRUD操作整合在一处，因为这些操作共享相同的 schema、相同的身份模型（每个视图对应一个UUID）以及相同的前置资源。唯一具有实际影响范围的操作是删除，而更新操作有一个需要注意的点（全量替换）——以下会对这两个操作给出明确的防护说明。

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, the SigNoz MCP server is not installed or configured — stop and direct the user to set it up: https://signoz.io/docs/ai/signoz-mcp-server/. Do not fall back to raw HTTP calls or fabricate view payloads without the MCP tools.

本技能会调用SigNoz MCP服务器工具（

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

）。在执行工作流之前，请确认

signoz:signoz_*

工具可用。如果不可用，说明SigNoz MCP服务器未安装或配置——请停止操作并引导用户进行设置：https://signoz.io/docs/ai/signoz-mcp-server/。不要退回到原始HTTP调用，也不要在没有MCP工具的情况下手动构造视图负载。

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
```
.

当用户想要执行以下操作时，使用本技能：

创建：基于当前或描述的Explorer查询创建已保存视图。
列出/查找：现有视图（按
```
sourcePage
```
、名称或类别）。
查看：单个视图的筛选器或面板类型。
更新：视图——重命名、重新分类，或修改其筛选器、面板类型或聚合方式。
删除：不再有用的视图。

请勿在以下场景使用本技能：

构建仪表盘面板 → 使用

signoz-creating-dashboards

signoz-modifying-dashboards

。

运行临时Explorer查询但不保存 → 使用
```
signoz-generating-queries
```
。
创建或修改告警规则 → 使用
```
signoz-creating-alerts
```
。

Schema reference

Schema参考

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.

在编写任何创建或更新负载之前，请务必阅读这两个资源。不要凭记忆手动编写

compositeQuery

——正确的schema不是旧版的

builder.queryData

格式；而是以下资源中描述的v5规范。发送旧版负载会导致静默HTTP 400错误。

使用客户端的资源读取机制，通过URI读取这两个MCP资源：

```
signoz://view/instructions
```
—— SavedView字段参考、
```
sourcePage
```
规则、先GET后PUT的更新流程、最小化创建体。
```
signoz://view/examples
```
—— 三个可直接复用的往返负载（追踪列表、日志列表、指标图表）。

服务器会针对旧版v3/v4字段（

builder

、

promql

、

unit

、顶层

id

、

queryFormulas

、

queryTraceOperator

）返回HTTP 400错误——用户不会收到明确提示，因此提前读取资源是必须的，而非可选操作。

Operation flows

操作流程

Create a view

创建视图

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.
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.
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.

Enforce
signal == sourcePage
in every

builder_query

spec. A

sourcePage:"traces"

view with

signal:"logs"

is a server-side error.

Preview before writing — this step is not optional. Before calling
```
signoz:signoz_create_view
```
, show the user a summary: name, sourcePage, panelType, and the full filter expression. For a human in the loop, wait for confirmation. For an autonomous agent, log the preview and proceed.

Call

signoz:signoz_create_view

. The server populates

id

createdAt/By

updatedAt/By

— never send those.

确定
sourcePage
—— 必须是
```
traces
```
、
```
logs
```
、
```
metrics
```
中的一个。如果用户的意图不明确（例如“保存此查询”），请询问他们指的是哪个Explorer。无法仅通过筛选器字符串推断出该值。
读取schema资源。在编写任何负载之前，使用客户端的资源读取机制读取
```
signoz://view/instructions
```
和
```
signoz://view/examples
```
。即使你认为自己了解schema，也不要跳过此步骤——旧版
```
builder.queryData
```
格式会被拒绝并返回HTTP 400错误。
使用
signoz-generating-queries
构建查询——必须执行。使用
```
Skill
```
工具调用
```
signoz-generating-queries
```
。该子技能可一次性完成字段发现、类型检查和实时数据验证——直接改编
```
signoz://view/examples
```
中的示例负载或仅调用
```
signoz:signoz_search_traces
```
会跳过字段类型检查和服务名称解析，而这些步骤可以在错误的视图被永久保存前发现静默400错误。跳过此步骤会导致格式错误的筛选器被保存为视图，后续必须删除并重新创建。
强制要求每个
builder_query
规范中的
signal == sourcePage
。如果
```
sourcePage:"traces"
```
的视图中包含
```
signal:"logs"
```
，会导致服务器端错误。
写入前预览——此步骤不可选。在调用
```
signoz:signoz_create_view
```
之前，向用户展示摘要信息：名称、sourcePage、panelType和完整的筛选表达式。如果有人工参与，请等待确认。如果是自主Agent，请记录预览信息后继续。
调用
```
signoz:signoz_create_view
```
。服务器会自动填充
```
id
```
、
```
createdAt/By
```
、
```
updatedAt/By
```
——请勿主动发送这些字段。

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.

signoz:signoz_list_views

需要指定

sourcePage

。如果用户未指定且按名称搜索，请针对每个信号（traces、logs、metrics）各调用一次并合并结果——不要猜测。当用户提供子字符串时，使用

name

和

category

参数进行服务器端部分匹配筛选；不要获取所有数据后在客户端进行过滤。

响应结果支持分页。务必检查
pagination.hasMore
，再得出视图不存在的结论。默认页面大小为50；传递

offset = pagination.nextOffset

以继续分页。只有当遍历到

hasMore = false

时，才能确认某个

sourcePage

下不存在指定视图。只要

hasMore = true

，就继续分页——没有页数上限。

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.

使用

signoz:signoz_get_view

并传入UUID。返回的

data

对象是标准的SavedView格式——这也是你传递给

signoz:signoz_update_view

的内容。请将该数据视为唯一可信来源，而非用户凭记忆描述的内容。

Update a view (GET-then-PUT)

更新视图（先GET后PUT）

signoz:signoz_update_view

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

signoz:signoz_get_view

with the view's

id

→ returns

{ "status": "success", "data": { ...SavedView... } }

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.
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
```
.
Modify only the field(s) the user asked to change.
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"). This prevents silent mistakes and gives the user a chance to catch a wrong target view. Wait for confirmation on any change to
```
compositeQuery
```
, since that changes what the view actually shows.

Call

signoz:signoz_update_view

with

{ "viewId": "<id>", "view": <modified data> }

signoz:signoz_update_view

是全量替换（上游为HTTP PUT请求）。发送部分负载会清除未指定的字段。流程如下：

使用视图的

id

调用

signoz:signoz_get_view

→ 返回

{ "status": "success", "data": { ...SavedView... } }

。

获取
```
data
```
对象。移除服务器自动填充的字段（
```
id
```
、
```
createdAt
```
、
```
createdBy
```
、
```
updatedAt
```
、
```
updatedBy
```
）——MCP服务器会自动移除这些字段，但提前移除可以让差异更易读。
如果更新涉及修改
compositeQuery
（新筛选器、不同的面板类型、不同的聚合方式），在继续之前调用
```
signoz-generating-queries
```
来构建并验证新查询。不要根据用户的描述手动编辑
```
compositeQuery
```
——同样需要遵守
```
signal == sourcePage
```
规则，且
```
panelType
```
的变更通常意味着
```
stepInterval
```
也需要变更。对于纯元数据调整（重命名、重新分类），可跳过此步骤且不要修改
```
compositeQuery
```
。
仅修改用户要求变更的字段。
写入前展示差异式预览。每个变更字段占一行：
```
name: "slow-checkout" → "slow-checkout-p99"
```
。明确标注未变更的字段（例如“compositeQuery: 未变更”）。这可以防止静默错误，并让用户有机会发现目标视图错误。对于
```
compositeQuery
```
的任何变更，请等待用户确认，因为这会改变视图实际展示的内容。

使用

{ "viewId": "<id>", "view": <修改后的data> }

调用

signoz:signoz_update_view

。

Delete a view

删除视图

Deletion is permanent — there is no undo, and any team member who had the view bookmarked will see it disappear. Treat this like dropping a row from a shared table:

List to locate. Call
```
signoz:signoz_list_views
```
to find the view by name. If
```
sourcePage
```
is unknown, search all three signals.
Get to confirm — mandatory. Call
```
signoz: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:signoz_get_view
```
is the confirmation that the UUID maps to the view the user named. Never call
```
signoz:signoz_delete_view
```
on a UUID without a prior
```
signoz:signoz_get_view
```
confirming the matching name and
```
sourcePage
```
.
Show and ask. Present the resolved view's name,
```
sourcePage
```
, and category, 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.
Call
```
signoz: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.

删除操作是永久性的——无法撤销，所有收藏该视图的团队成员都会看到它消失。请将此操作视为删除共享表格中的一行数据：

列出以定位。调用
```
signoz:signoz_list_views
```
按名称查找视图。如果未知
```
sourcePage
```
，请搜索所有三个信号。
获取以确认——必须执行。使用步骤1中得到的UUID调用
```
signoz:signoz_get_view
```
。即使列表结果看起来正确，也不要跳过此步骤。列表结果是分页的，名称匹配并不等同于UUID正确——
```
signoz:signoz_get_view
```
是确认UUID对应用户指定视图的唯一方式。在未调用
```
signoz:signoz_get_view
```
确认名称和
```
sourcePage
```
匹配之前，切勿调用
```
signoz:signoz_delete_view
```
。
展示并确认。展示已定位视图的名称、
```
sourcePage
```
和类别，并明确请求用户确认。即使原始提示语气坚决，也不要自动确认——破坏性操作需要针对已定位的目标进行新的确认。
调用
```
signoz:signoz_delete_view
```
。返回成功信息时请包含已删除视图的名称（而非仅UUID），以便用户识别。

对于无人工参与的自主Agent：除非调用上下文已明确授权对已保存视图执行破坏性操作，否则拒绝删除请求，并在调用前记录已定位视图的元数据。

Quick reference

快速参考

Operation	Tools called	Key guard
Create	read `signoz://view/instructions` + `signoz://view/examples` → `signoz-generating-queries` → preview → `signoz:signoz_create_view`	Preview before write; no legacy fields
List	`signoz:signoz_list_views` (× 3 if no sourcePage given)	Check `pagination.hasMore`
Get	`signoz:signoz_get_view(viewId)`	Returns canonical body for update
Update	`signoz:signoz_get_view` → modify → preview → `signoz:signoz_update_view`	Full-body replace; diff preview required
Delete	`signoz:signoz_list_views` → `signoz:signoz_get_view` → confirm → `signoz:signoz_delete_view`	Get-before-delete mandatory; fresh confirmation

操作	调用的工具	关键防护措施
创建	读取 `signoz://view/instructions` + `signoz://view/examples` → `signoz-generating-queries` → 预览 → `signoz:signoz_create_view`	写入前预览；禁止使用旧版字段
列出	`signoz:signoz_list_views` （若未指定sourcePage则调用3次）	检查 `pagination.hasMore`
获取	`signoz:signoz_get_view(viewId)`	返回用于更新的标准格式内容
更新	`signoz:signoz_get_view` → 修改 → 预览 → `signoz:signoz_update_view`	全量替换；必须展示差异预览
删除	`signoz:signoz_list_views` → `signoz:signoz_get_view` → 确认 → `signoz:signoz_delete_view`	必须先获取再删除；需要新的确认

Common mistakes

常见错误

Mistake	Fix
Hand-composing `compositeQuery` 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:signoz_search_traces` is not a substitute
Skipping `signoz:signoz_get_view` before delete (relying on list UUID alone)	Always call `signoz:signoz_get_view` to confirm name+sourcePage before `signoz:signoz_delete_view`
Sending legacy fields: `builder` , `promql` , `unit` , top-level `id` , `queryFormulas`	Read schema resources; server returns HTTP 400 silently
`signal` ≠ `sourcePage` in builder query	Every `builder_query.signal` must equal the view's `sourcePage`
Partial update body (omitting unchanged fields)	GET full body first → modify only changed fields → PUT entire body
Declaring "no such view" after only page 1	Check `pagination.hasMore` ; continue with `offset = pagination.nextOffset`
Using PromQL or raw ClickHouse in a view	Only `queryType: "builder"` is supported; offer a dashboard panel instead
Setting `category` to an enum value	`category` is free-form string; omit if user doesn't specify

错误	修复方案
凭示例或记忆手动编写 `compositeQuery` （即使已读取 `signoz://view/examples` ）	使用 `Skill` 工具调用 `signoz-generating-queries` ——仅读取示例并通过 `signoz:signoz_search_traces` 验证无法替代该步骤
删除前跳过 `signoz:signoz_get_view` （仅依赖列表中的UUID）	在调用 `signoz:signoz_delete_view` 之前，务必调用 `signoz:signoz_get_view` 确认名称+sourcePage
发送旧版字段： `builder` 、 `promql` 、 `unit` 、顶层 `id` 、 `queryFormulas`	读取schema资源；服务器会静默返回HTTP 400错误
构建器查询中 `signal` ≠ `sourcePage`	每个 `builder_query.signal` 必须与视图的 `sourcePage` 一致
发送部分更新负载（省略未变更字段）	先获取完整内容 → 仅修改需要变更的字段 → PUT完整内容
仅查看第一页后就断言“不存在该视图”	检查 `pagination.hasMore` ；使用 `offset = pagination.nextOffset` 继续分页
在视图中使用PromQL或原生ClickHouse语句	仅支持 `queryType: "builder"` ；建议使用仪表盘面板替代
将 `category` 设置为枚举值	`category` 是自由格式字符串；如果用户未指定则省略

Reporting back

结果反馈

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

The view's name and UUID.
The
```
sourcePage
```
.
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 +
```
sourcePage
```
.
For updates, what changed (one-line diff).
For deletes, an explicit "deleted" confirmation with the name.

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

在执行任何写入操作（创建/更新/删除）后，回复中应包含：

视图的名称和UUID。
```
sourcePage
```
。
仅当MCP响应或SigNoz前端提供了标准URL，或者用户明确要求时，才提供直接链接。不要自行构造前端路由——已保存视图的路径因信号而异，且会随时间变化。如有疑问，请省略链接并返回UUID +
```
sourcePage
```
。
对于更新操作，说明变更内容（一行差异）。
对于删除操作，明确确认“已删除”并包含视图名称。

只读操作（列出、获取）应简洁反馈——名称、ID、sourcePage、筛选表达式、面板类型——无需向用户解释schema。",