signoz-managing-views

管理已保存的视图

通过 SigNoz MCP 服务创建、读取、更新和删除 SigNoz 的已保存 Explorer 视图。已保存视图是 Logs、Traces、Metrics 或 Cost Meter 页面上 Explorer 查询的可重复使用快照，包含名称、筛选条件和面板类型，并限定在一个 source 中。它们不是仪表板，也不是告警。

这些工具调用 v2 /api/v2/saved_views API。创建和更新请求体使用 v2 的类型化结构（source + spec），而非已弃用的 v1 compositeQuery/category/tags/extraData 结构；参数 sourcePage 已更名为 source。

本技能在一处涵盖完整的 CRUD 操作，因为这些操作使用相同的架构、相同的身份模型（每个视图使用一个 UUID）和相同的前置资源。只有删除操作会造成实际影响，而更新也有一个容易出错的地方（完整请求体替换）；下文会对两者明确设置防护措施。

前置条件

本技能会调用 SigNoz MCP 服务工具（signoz_create_view、 signoz_list_views、signoz_get_view、 signoz_update_view、signoz_delete_view、 signoz_get_field_keys、signoz_get_field_values）。运行工作流前，请确认 signoz_* 工具可用。如果不可用，请先运行 signoz-mcp-setup，以初始化或修复 MCP 连接。不要改用原始 HTTP 调用，也不要在没有 MCP 工具的情况下编造视图请求体。

适用场景

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

• 创建基于当前或描述的 Explorer 查询的已保存视图。
• 列出 / 查找现有视图（按 source 或名称）。
• 查看单个视图的筛选条件或面板类型。
• 更新视图：重命名其显示标签，或更改其筛选条件、面板类型或聚合。
• 删除不再有用的视图。

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

• 构建仪表板面板 → signoz-creating-dashboards / signoz-modifying-dashboards。
• 运行临时 Explorer 查询但不保存 → signoz-generating-queries。
• 创建或更改告警规则 → signoz-creating-alerts。

架构参考

编写任何创建或更新请求体之前，先读取这两个资源。 不要凭记忆手动编写 spec。正确的架构是这些资源中所述的 v2 类型化规范（schemaVersion: "v2"）；已弃用的 v1 字段（compositeQuery、category、tags、extraData）不受支持。

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

• signoz://view/instructions：SavedView 字段参考、source 规则、spec 字段、先 GET 再替换的更新流程，以及最简创建请求体。
• signoz://view/examples：往返转换后的 v2 请求体，仅在符合当前意图和架构时用于调整。

操作流程

创建视图

1. 解析 source：必须恰好是 traces、logs、 metrics、meter 之一。如果用户的意图不明确（“保存此查询”）， 请询问他们指的是哪个 Explorer。不能仅根据筛选字符串推断。Cost Meter （用量／计费）视图请使用 meter；它与 metrics 是不同的 Explorer 页面， 即使查询运行在 metrics 信号上也是如此（见第 4 步）。

2. 读取架构资源。 在编写任何载荷之前，使用客户端的资源读取机制读取 signoz://view/instructions 和 signoz://view/examples。即使你认为自己 了解架构，也不要跳过此步骤。

3. 使用 signoz-generating-queries 构建查询，此步骤为必需。 使用 Skill 工具调用 signoz-generating-queries。此子技能会一次性处理字段发现、 类型检查和实时数据验证；改用 signoz://view/examples 中的示例载荷，或直接 运行一个裸的 signoz_search_traces 调用，会跳过字段类型检查和服务名称解析， 而这些检查可以在无声的 400 错误演变为永久错误视图之前将其捕获。跳过此步骤 意味着格式错误的筛选条件会被保存为视图，之后必须删除并重新创建。 对于 meter 视图，请告知 signoz-generating-queries 这是一个 Cost Meter 查询（source=meter），以便发现过程查询 meter 存储，而不是默认存储。 保留其成功的 signoz_execute_builder_query 验证调用中的完整 queries 数组，然后明确地进行转换：

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

   将 spec 参数构造为 signoz_create_view 的 { "displayName": "<human label>", "panelType": "<list|graph|table|value|trace>", "requestType": "<raw|time_series|scalar|trace>", "queries": <copied queries> }， 如果 Explorer 布局需要，则添加 selectedFields / display。 完整复制 queries 数组，但不要复制仅用于执行的封装字段 schemaVersion、start、end、requestType（执行封装中的）、formatOptions 或 variables；不要在已保存的 spec 中放入 query 键或 compositeQuery 对象。根据已保存视图的用途选择 panelType 和 requestType，不要从执行封装中臆造。 设置顶层 name（DNS-1123 标签：小写字母、数字、连字符），或传入 generateName: true，以便根据 spec.displayName 生成名称。schemaVersion 始终为 "v2"；省略时由服务端填入。 复制的查询必须无损保留每个正数 spec.limit 和 v5 的每个 spec.order 条目。绝不要将它们转换为仪表板 orderBy。 原始/列表视图使用 100 行（日志：timestamp/id 降序；跟踪：timestamp 降序）；独立聚合视图和公式结果使用 100 个分组。 公式引用的构建器查询使用 10000，因为其限制会在计算前应用。根据情况按主聚合或 __result 降序排列。时间序列的 top-N 会在整个选定时间窗口内对分组排名，因此可能遗漏短暂的局部峰值。 在 v2 资源允许的范围内，原样保留原始查询条目，包括禁用标记以及 PromQL 或 SQL 封装。创建时，PromQL 或 SQL 封装必须逐字来自用户或现有视图；signoz-generating-queries 不会编写此类封装，因此请在步骤 5 中验证。

4. 在每个 builder_query spec 中强制执行信号规则。

   • 对于 traces / logs / metrics：signal == source。source:"traces" 且 signal:"logs" 的视图会导致服务端错误。
   • 对于 meter（Cost Meter）：signal:"metrics" 且 source:"meter"： Cost Meter 视图会针对 metrics 信号查询 meter 存储。省略 source:"meter" 会静默查询默认 metrics 存储；在非 meter 来源的视图中设置 source:"meter" 则会被拒绝。

5. 保存前必须获取样本。 使用 spec.queries[0].spec 中的完全相同筛选条件，针对目标信号进行探测：

   • source=traces → 使用 limit=1 调用 signoz_search_traces
   • source=logs → 使用 limit=1 调用 signoz_search_logs
   • source=metrics → 使用来自 spec.aggregations[0].metricName 的 metricName，以及相同的筛选条件、timeRange=1h 和 requestType=scalar 调用 signoz_query_metrics。如果视图包含多个指标查询，则逐个重复。此工具要求提供 metricName；不支持仅使用筛选条件进行探测。
   • source=meter → 使用来自 spec.aggregations[0].metricName 的 metricName、source=meter、相同的筛选条件、timeRange=24h（Cost Meter 按小时汇总，因此 1h 窗口可能只有一个不完整的时间桶）和 requestType=scalar 调用 signoz_query_metrics。
   • PromQL 或 SQL 封装 → 使用该完全相同的封装，在较短的近期时间窗口内调用 signoz_execute_builder_query。上述构建器探测规则不适用于此类封装。 即使步骤 3 顺利完成，也仍然必需：子技能验证的是它编写的查询，而不是你编辑或提取后保存的内容。 为空 → 仍然保存／修改／中止。若自主模式未获授权保存空视图，则中止并升级处理。

6. 写入前预览；此步骤不可省略。 调用 signoz_create_view 前，向用户展示摘要：名称、来源、 panelType、完整筛选表达式，以及步骤 5 的探测结果 （“最近 1h 获取样本：N 行”；对于 meter 视图，探测时间窗口 为 24h，因此应据此报告）。如果有人参与流程，请等待确认。对于自主 Agent，请记录预览并继续。

7. 调用 signoz_create_view。成功后，响应中的 data 包含新视图的 id（上游 HTTP 201）。服务端会填充 id、 createdAt/By、updatedAt/By；切勿发送这些字段。

对于已保存的日志筛选器，请使用 search('timeout') 进行明确的跨字段全文搜索。仅当确实需要限定到特定范围时，才使用 search('timeout', body) 等限定范围的形式。字段发现确定目标后，优先使用规范字段谓词，例如 body CONTAINS 'timeout'。字面值中的反斜杠要在撇号之前转义。 signoz_search_logs.searchText 这一便捷方式（由 searchScope 选择匹配位置；默认为日志正文）不能替代保留编写好的 search() 筛选器。

列出或查找视图

signoz_list_views 要求提供 source。如果用户未指定来源且按名称搜索，则对每种来源（traces、 logs、metrics、meter）各调用一次并合并结果；不要猜测。用户提供子字符串时，使用 name 参数进行服务端部分匹配筛选；不要获取所有结果后再在客户端用 grep 搜索。没有 category 筛选器；它已随 v2 API 一同移除。

响应采用分页。在确认视图不存在之前，务必检查 pagination.hasMore。默认页面大小为 50；传入 offset = pagination.nextOffset 以继续。只有遍历完所有页面，直到 hasMore = false，才能确认某个 source 下的视图确实不存在。只要 hasMore = true，就继续分页；页面数量没有上限。

获取单个视图

使用 signoz_get_view，并传入 UUID（id；旧别名 viewId 也可使用）。返回的 data 对象是规范的 SavedView 结构；将其传回 signoz_update_view 即可。应以该数据为准，而不是用户凭记忆描述的内容。

更新视图（先获取，再替换）

signoz_update_view 会执行完整替换。发送不完整的请求体会清除未指定的字段。机器 name 在服务端不可变；如需重命名视图，请更改 spec.displayName。流程如下：

1. 使用视图的 id 调用 signoz_get_view → 返回 { "status": "success", "data": { ...SavedView... } }。
2. 取出 data 对象。删除服务端填充的字段（id、 createdAt、createdBy、updatedAt、updatedBy），并删除 name；MCP 服务会替你删除这些字段，但提前省略能让差异更清晰。
3. 如果更新会更改 spec.queries（新增筛选条件、更改面板 类型、更改聚合方式），请先调用 signoz-generating-queries，在继续操作前构建并验证新查询。不要根据用户的描述手动编辑 spec.queries；同样适用第 4 步的信号规则（包括 meter 的情况：signal:"metrics" + source:"meter"），而且更改 panelType 通常也意味着要更改 stepInterval。对于 meter 视图，请告知 signoz-generating-queries 这是一个 Cost Meter 查询（source=meter），以便它发现并针对 meter 存储进行验证。从成功执行的查询中提取替换用的 spec.queries，并使用与创建时相同的显式转换方式：只复制 query.compositeQuery.queries。排除仅用于执行的封装字段。对于纯元数据调整（更改显示名称），跳过此步骤，不要修改 spec.queries。
4. 只修改用户要求更改的字段。保持 source 不变；跨来源移动会被拒绝。
5. 保存前必须获取示例数据（当 spec.queries 发生更改时）。 针对新筛选条件，按照创建流程第 5 步执行 1 行探测。若结果为空 → 仍然保存／修改／中止。纯元数据调整（更改显示名称）可跳过此步骤。
6. 写入前展示差异预览。 每个更改的字段占一行：spec.displayName: "slow-checkout" → "slow-checkout-p99"。 明确说明任何未更改的字段（例如“查询： 未更改”）；如果 spec.queries 发生更改，还需包含第 5 步的探测结果。这样可以避免无提示的错误，并让用户有机会发现目标视图选错。对 spec.queries 的任何更改都必须等待确认，因为这会改变视图实际显示的内容。
7. 使用 { "id": "<id>", "view": <modified data> } 调用 signoz_update_view。 view 必须包含 source 和完整的 spec；上游成功时会返回空的 204。

删除视图

删除具有破坏性，会立即从共享列表中移除视图；任何将该视图加入书签的团队成员都会看到它消失。根据宿主应用的不同，用户可能会在删除后不久获得一键恢复操作（SigNoz Assistant 会捕获快照并提供 restore 操作），但应将其视为恢复手段，而不是确保删除正确的替代方案。请将此操作视为从共享表中删除一行：

1. 先列出以定位。 调用 signoz_list_views，按名称查找视图。如果 source 未知，请搜索全部四种来源（traces、logs、metrics、meter）。
2. 必须获取以确认。 使用第 1 步中的 UUID 调用 signoz_get_view。即使你从看似正确的列表结果中获取了 UUID，也绝不可跳过此步骤。列表结果是分页的，名称匹配并不能保证 UUID 正确；signoz_get_view 可确认该 UUID 对应的是用户指定的视图。 调用 signoz_delete_view 前，必须先调用 signoz_get_view，确认名称和 source 匹配；绝不可对未经确认的 UUID 调用 signoz_delete_view。
3. 展示并征求确认。 展示已确认视图的名称和 source，并明确征求确认。不要根据用户最初的提示自动确认，即便提示语气十分强烈也不行；破坏性操作必须针对已确认的目标重新征求确认。
4. 调用 signoz_delete_view。报告成功时，应提供已删除视图的名称（而不只是 UUID），以便用户识别。

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

防护措施

• 创建和更新 spec.queries 时，必须先获取预保存样本。 每个流程的第 5 步都会针对目标信号执行一次 1 行探测，使用即将保存的载荷中的确切过滤条件。跳过此步骤等同于跳过删除前先获取确认。第 3 步中委派给 signoz-generating-queries 是必要的，但还不够；它验证的是其编写的查询，而不是编辑后要保存的过滤条件。

  跨信号提升陷阱： 字段键按信号区分。在 metrics 上观察到的属性（例如计数器上的 oauth.error_code），对于同一租户的 traces 或 logs 可能并不存在，即使它们由同一服务发出。从目标信号不同的相邻仪表板面板、告警规则或视图中提取属性，是导致已保存视图为空的最常见原因。signoz_get_field_keys signal=<destination signal> 是必要的，但还不够；稀疏发射仍会导致视图结果为零。只有样本获取才能确认。目标信号对于 traces/logs/metrics 与 source 相同；对于 meter 视图，目标信号是 signal=metrics，而 source=meter（绝不能使用 signal=meter）。

  在共享工作区中，按自身过滤条件返回零行的已保存视图会成为永久遗留项；人工预览无法从 JSON 判断过滤条件是否会匹配，而自主模式没有预览，因此样本获取是唯一的安全保障。

• 保存前转换执行封套。 可执行查询和已保存视图规范有意采用不同的外层结构。在创建调用的 spec 或 view.spec 中，严格保存 spec: {displayName, panelType, requestType, queries, ...}，其中 queries 来自经过验证的执行结果 query.compositeQuery.queries。绝不要将范围、请求、格式设置或变量封套复制到视图中。

快速参考

操作	调用的工具	关键防护措施
创建	读取 signoz://view/instructions + signoz://view/examples → signoz-generating-queries → 针对确切筛选条件获取样本 → 预览 → signoz_create_view	保存前必须获取样本；写入前预览；不得使用 v1 字段
列出	signoz_list_views（未提供来源时调用 4 次：traces/logs/metrics/meter）	检查 pagination.hasMore
获取	signoz_get_view(id)	返回用于更新的规范正文
更新	signoz_get_view → 修改 → 如果 spec.queries 已更改，则获取样本 → 预览差异 → signoz_update_view	完整替换；name 不可变（重命名需修改 spec.displayName）；必须预览差异
删除	signoz_list_views → signoz_get_view → 确认 → signoz_delete_view	删除前必须先获取；需重新确认

常见错误

错误	修正方法
根据示例或记忆手动编写 spec.queries（即使已经阅读 signoz://view/examples）	使用 Skill 工具调用 signoz-generating-queries；阅读示例并用 signoz_search_traces 验证不能替代此步骤
发送已弃用的 v1 格式：compositeQuery、category、tags、extraData 或 sourcePage 参数	v2 API 使用 source + spec；请先阅读这两个架构资源
将完整的可执行查询封装复制到保存的 spec 中	只复制 query.compositeQuery.queries，然后构造 spec {displayName, panelType, requestType, queries}；排除仅用于执行的 schemaVersion、start、end、requestType、formatOptions 和 variables
从指标、告警规则或同类视图中取用属性名，并在 source=traces / =logs 视图筛选条件中使用，却未在目标信号上重新验证	字段键的作用范围是信号；指标上的属性可能不存在于 traces 或 logs 中。务必通过 signoz_get_field_keys signal=<destination signal> 重新检查（对于 meter 视图，使用 signal=metrics source=meter，切勿使用 signal=meter），并执行必需的保存前样本获取；检查字段键是必要条件，但并非充分条件
因为 signoz-generating-queries 已验证查询，就跳过保存前的样本获取	子技能验证的是它所编写的查询；要持久化的筛选条件可能之后经过编辑或复制。无论如何都必须执行第 5 步的样本获取
删除前跳过 signoz_get_view（仅依赖列表中的 UUID）	调用 signoz_delete_view 前，务必调用 signoz_get_view 确认名称和来源
更新时尝试重命名机器标识 name	name 在服务端不可变；更改 spec.displayName 来更新可见标签
构建器查询中的 signal ≠ source	对于 traces/logs/metrics，每个 builder_query.signal 都必须与视图的 source 相同。对于 meter 视图，使用 signal:"metrics" + source:"meter"（不能使用 signal:"meter"）
将 Cost Meter 视图归入 source:"metrics"（同时设置 source:"meter"）	Cost Meter 视图应归入 source:"meter"；否则它们不会显示在 Meter Explorer 中，还会被错误归入 Metrics。对于非 meter 来源，服务端会拒绝 source:"meter"
仅包含部分字段的更新请求体（省略未更改的字段）	先 GET 获取完整请求体 → 仅修改已更改的字段 → 使用 source + 完整 spec 替换
仅查看第 1 页后就宣称“没有此视图”	检查 pagination.hasMore；继续使用 offset = pagination.nextOffset 查询
规范化并删除 PromQL、SQL、禁用标志、所选字段或未知的手动编写内容	在读取-修改-写入过程中，保留当前类型化资源允许的所有字段；只删除已知的服务端填充字段

汇报结果

每次写入（创建／更新／删除）后，请在回复中包含：

• 视图名称和 UUID。
• source。
• 仅当 MCP 响应或 SigNoz 前端提供了规范 URL，或用户明确要求时，才提供直接链接。不要编造前端路由；已保存视图的路径因信号而异，且会随时间变化。如有疑问，请省略链接，并报告 UUID 和 source。
• 对于更新，说明变更内容（一行差异）。
• 对于删除，明确确认已删除，并注明名称。

后续建议

视图操作后，你最多可以提供 3 个与刚才操作相关的后续意图。宿主应用会渲染这些内容；请遵循宿主的 UI 渲染规则，使用相应机制。根据用户的上下文判断哪些建议自然；不必凑足 3 个。

以下两条限制优先于你的判断：

• 只读操作在建议项上也必须保持只读。 列出／获取／查找后，不要提供建议项来提议写入（例如“更新此视图”“删除此视图”）。这与下文“汇报结果”中的只读停止规则相矛盾。可以提供重新运行视图底层查询的建议项；这仍属于只读路径。如果用户在下一条消息中提出更新或删除，再据此处理。
• 不要重复宿主注入的操作。 如果宿主在删除后提供恢复操作（SigNoz Assistant 会如此），也不要再提供恢复建议；否则会重复显示。

当用户只是在探索（“只是列出我的视图”“这里有什么？”），且没有表示有进一步意图时，完全不要提供后续建议。不提供建议总比提供错误建议好。

请根据用户意图描述后续建议，而不是工具或技能名称。用户点击的标签应当像是用户接下来会提出的要求。

只读操作（列出、获取）应简洁地报告（名称、ID、来源、筛选表达式、面板类型），然后停止。不要向用户复述架构。