signoz-modifying-dashboards
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseDashboard Modify
修改仪表盘
Prerequisites
前提条件
This skill calls SigNoz MCP server tools (,
, , ).
Before running the workflow, confirm the 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 hand-edit dashboard JSON without the MCP tools.
signoz:signoz_get_dashboardsignoz:signoz_update_dashboardsignoz:signoz_list_dashboardssignoz:signoz_list_metricssignoz:signoz_*本技能调用SigNoz MCP服务器工具(、、、)。运行工作流前,请确认工具可用。如果不可用,说明SigNoz MCP服务器未安装或配置——请停止操作并引导用户按照以下链接进行设置:https://signoz.io/docs/ai/signoz-mcp-server/。请勿在没有MCP工具的情况下回退到原始HTTP调用或手动编辑仪表盘JSON。
signoz:signoz_get_dashboardsignoz:signoz_update_dashboardsignoz:signoz_list_dashboardssignoz:signoz_list_metricssignoz:signoz_*When to use
适用场景
Use this skill when the user asks to:
- Add, remove, or edit panels/widgets on an existing dashboard
- Change a panel's query, title, type, or display settings
- Add, remove, or edit dashboard variables
- Rename or re-describe a dashboard
- Rearrange panel layout or resize panels
- Change a panel type (e.g., graph to table, value to graph)
- Add or modify thresholds on a panel
- Update tags on a dashboard
Do NOT use when:
- User wants to understand what a dashboard shows →
signoz-explaining-dashboards
当用户要求执行以下操作时使用本技能:
- 在现有仪表盘上添加、移除或编辑面板/小部件
- 修改面板的查询语句、标题、类型或显示设置
- 添加、移除或编辑仪表盘变量
- 重命名或重新描述仪表盘
- 重新排列面板布局或调整面板大小
- 切换面板类型(例如,图表转表格、数值转图表)
- 添加或修改面板的阈值
- 更新仪表盘的标签
请勿使用本技能的场景:
- 用户想要了解仪表盘展示的内容 → 使用
signoz-explaining-dashboards
Instructions
操作步骤
Step 1: Identify the target dashboard
步骤1:确定目标仪表盘
Determine which dashboard the user wants to modify. If the user provides a
dashboard name, UUID, or it is clear from context (e.g., an @mention or auto-context
providing a dashboard resource), use that.
If the target dashboard is ambiguous:
- Call to list existing dashboards. Paginate through all pages — check
signoz:signoz_list_dashboardsin the response. Ifpagination.hasMoreis true, call again withhasMoreset tooffsetand repeat until all pages are exhausted. Never stop at the first page.pagination.nextOffset - Present matching candidates to the user and ask which one to modify.
确认用户想要修改的仪表盘。如果用户提供了仪表盘名称、UUID,或者上下文明确(例如@提及或自动上下文提供了仪表盘资源),则直接使用该信息。
如果目标仪表盘不明确:
- 调用列出所有现有仪表盘。需遍历所有分页——检查响应中的
signoz:signoz_list_dashboards。如果pagination.hasMore为true,则使用hasMore设置为offset再次调用,重复此操作直到获取所有页面内容。切勿仅停留在第一页。pagination.nextOffset - 将匹配的候选仪表盘展示给用户,询问要修改哪一个。
Step 2: Fetch the current dashboard state
步骤2:获取当前仪表盘状态
Call with the dashboard UUID to retrieve its full
configuration. This is mandatory — requires the
complete post-update state, not a partial patch. Never skip this step.
signoz:signoz_get_dashboardsignoz:signoz_update_dashboardExamine the response to understand:
- Current widgets and their IDs
- Current layout positions (x, y, w, h in the 12-column grid)
- Current variables
- Current queries on each panel
- The structure (row-to-child mappings)
panelMap
调用并传入仪表盘UUID,以获取其完整配置。这一步是必须的——需要更新后的完整状态,而非部分补丁。切勿跳过此步骤。
signoz:signoz_get_dashboardsignoz:signoz_update_dashboard检查响应内容,了解以下信息:
- 当前的小部件及其ID
- 当前的布局位置(12列网格中的x、y、w、h值)
- 当前的变量
- 每个面板的当前查询语句
- 结构(行与子项的映射关系)
panelMap
Step 3: Plan the modification
步骤3:规划修改内容
Based on the user's request, plan the changes.
Confirm with the user before applying if:
- The modification is destructive — removing panels, deleting variables,
replacing an entire query with a different one, changing a panel's (e.g., traces → logs), or fundamentally altering what data is shown (changing aggregation from p99 to avg, removing groupBy dimensions)
dataSource - The request is ambiguous — multiple panels could match "the latency panel"
- The change is large — restructuring sections, adding many panels at once
Destructive means data loss or silent behavior change. Even if the user says
"just do it quickly," a brief confirmation ("I'll remove 'Memory Fragmentation'
permanently — OK?") takes seconds and prevents irreversible mistakes. User urgency
does not override this guardrail.
Non-destructive changes proceed directly: renaming, adding a single panel,
changing a unit, adding a variable, changing panel type (the query is preserved),
adjusting layout, adding thresholds.
Compound modifications: When a request involves multiple changes (e.g., remove a
panel + add a panel + rename), plan all changes against the fetched state and apply
them as a single update. Do not apply and re-fetch between changes.
根据用户的请求规划修改内容。
以下情况需先与用户确认再执行修改:
- 修改具有破坏性——移除面板、删除变量、用完全不同的查询语句替换原有查询、更改面板的(例如,追踪→日志),或从根本上改变展示的数据(将聚合方式从p99改为平均值、移除groupBy维度)
dataSource - 请求存在歧义——多个面板都可能匹配“延迟面板”的描述
- 修改范围较大——重构板块、一次性添加多个面板
破坏性指会导致数据丢失或行为静默变更。即使用户说“快点做”,也需要简短确认(例如“我将永久移除‘内存碎片’面板,可以吗?”),这仅需几秒钟,却能避免不可挽回的错误。用户的急切需求不能绕过此防护规则。
**非破坏性变更可直接执行:**重命名、添加单个面板、修改单位、添加变量、切换面板类型(查询语句保留)、调整布局、添加阈值。
**复合修改:**当请求包含多项变更(例如,移除一个面板+添加一个面板+重命名),需基于获取的状态规划所有变更,并作为单次更新应用。请勿在变更之间重复执行应用和重新获取状态的操作。
Step 4: Apply the modification
步骤4:执行修改
Merge the planned changes into the full dashboard JSON from Step 2.
Modification rules:
-
Preserve everything you are not changing. Copy the entire dashboard object and only modify the specific fields the user asked about. Do not drop widgets, variables, layout items, or panelMap entries that are not part of the change.
-
Adding a panel:
- Create a new widget with a UUID for its (use
idformat).crypto.randomUUID() - Include all required widget fields: ,
id,title,description,panelTypes,query("1"),opacity("zero"),nullZeroValues("GLOBAL_TIME" — note the deliberate misspelling),timePreferance(60),stepSize,yAxisUnit(false),isStacked(false),fillSpans(false),isLogScale(false),mergeAllActiveQueries([]),thresholds(0),softMin(0),softMax("bottom"),legendPosition({}),columnUnits({}),customLegendColors([]),selectedLogFields([]),selectedTracesFields({"linksData": []}).contextLinks - Add a layout entry with matching the widget ID, and appropriate
i,x,y,wvalues in the 12-column grid.h - If the dashboard uses rows, add the panel's layout to the appropriate row's
array. If the dashboard has no rows (empty
panelMap[rowId].widgets), skip panelMap — the panel lives at the top level.panelMap - For query construction, read the MCP resource for the v5 builder query format. Use the signal-specific resources as needed (
signoz://dashboard/query-builder-example,signoz://dashboard/promql-example,signoz://dashboard/clickhouse-*).signoz://traces/query-builder-guide
- Create a new widget with a UUID for its
-
Removing a panel: Remove the widget from, its entry from
widgets, and its entry from the parent row'slayout(if it exists in panelMap). Do not try to auto-compact or shiftpanelMap.widgetspositions of remaining panels — the SigNoz frontend grid engine handles gap-closing automatically. Simply remove the three references (widget, layout, panelMap entry) and leave all other positions unchanged.y -
Editing a panel's query: Replace the query object on the target widget. Keep all other widget fields intact.
-
Changing panel type: Updateand handle type-specific fields:
panelTypes- →
graph: addtable({}) andcolumnUnits({}) if missing. Graph-only fields likecolumnWidths,isStacked,fillSpansbecome inert but are harmless to leave.isLogScale - /
graph→table: addhistogram(30) andbucketCount(0).bucketWidth - Any → (logs): add
listarray.selectedLogFields - Any → (traces): add
listarray.selectedTracesFields - Keep the existing query intact — the data source and query are independent of the visualization type.
-
Adding/editing variables: Add or update entries in themap. Use OTel attribute names for the underlying attribute (e.g.,
variables,service.name). Use DYNAMIC type when the values come from a standard telemetry attribute. Each variable needs a UUID fordeployment.environment.nameandid.key -
Rearranging layout / side-by-side placement:
- Dashboard uses a 12-column grid. ranges 0–11,
xranges 1–12.w - Two panels side-by-side: each gets , first at
w: 6, second atx: 0, samex: 6andy.h - Three panels in a row: at
w: 4,x: 0,x: 4.x: 8 - When resizing an existing panel to make room, update its and
w, then place the new panel in the freed space at the samex.y - Common heights: for graphs/tables,
h: 6–h: 2for value panels,h: 3for row headers.h: 1 - Keep panelMap in sync: whenever you change ,
x,y, orwin the top-levelharray, apply the same change to the matching entry inlayout. These are duplicated and must stay consistent.panelMap[rowId].widgets
- Dashboard uses a 12-column grid.
Call with the dashboard UUID and the complete modified
dashboard JSON.
signoz:signoz_update_dashboard将规划的变更合并到步骤2获取的完整仪表盘JSON中。
修改规则:
-
保留所有未修改的内容。复制整个仪表盘对象,仅修改用户要求变更的特定字段。请勿删除不属于变更范围的小部件、变量、布局项或panelMap条目。
-
添加面板:
- 创建一个新的小部件,为其分配一个UUID(使用
id格式)。crypto.randomUUID() - 包含所有必填的小部件字段:、
id、title、description、panelTypes、query(值为"1")、opacity(值为"zero")、nullZeroValues(值为"GLOBAL_TIME"——注意此处拼写故意有误)、timePreferance(值为60)、stepSize、yAxisUnit(值为false)、isStacked(值为false)、fillSpans(值为false)、isLogScale(值为false)、mergeAllActiveQueries(值为[])、thresholds(值为0)、softMin(值为0)、softMax(值为"bottom")、legendPosition(值为{})、columnUnits(值为{})、customLegendColors(值为[])、selectedLogFields(值为[])、selectedTracesFields(值为{"linksData": []})。contextLinks - 添加一个布局条目,其值与小部件ID匹配,并在12列网格中设置合适的
i、x、y、w值。h - 如果仪表盘使用行结构,将面板的布局添加到对应行的数组中。如果仪表盘没有行结构(
panelMap[rowId].widgets为空),则跳过panelMap——面板直接位于顶层。panelMap - 构建查询语句时,请参考MCP资源中的v5构建器查询格式。根据需要使用特定信号的资源(
signoz://dashboard/query-builder-example、signoz://dashboard/promql-example、signoz://dashboard/clickhouse-*)。signoz://traces/query-builder-guide
- 创建一个新的小部件,为其
-
**移除面板:**从中删除该小部件,从
widgets中删除其条目,并从父行的layout中删除其条目(如果存在于panelMap中)。请勿尝试自动压缩或调整剩余面板的panelMap.widgets位置——SigNoz前端网格引擎会自动处理间隙填充。只需删除这三处引用(小部件、布局、panelMap条目),保持其他所有位置不变。y -
**编辑面板的查询语句:**替换目标小部件的查询对象。保留小部件的所有其他字段不变。
-
**切换面板类型:**更新并处理类型特定字段:
panelTypes- →
graph:如果缺少table(值为{})和columnUnits(值为{}),则添加这两个字段。仅图表有的字段如columnWidths、isStacked、fillSpans会失效,但保留它们不会产生问题。isLogScale - /
graph→table:添加histogram(值为30)和bucketCount(值为0)。bucketWidth - 任意类型 → (日志):添加
list数组。selectedLogFields - 任意类型 → (追踪):添加
list数组。selectedTracesFields - 保留现有查询语句不变——数据源和查询语句与可视化类型无关。
-
**添加/编辑变量:**在映射中添加或更新条目。使用OTel属性名称作为底层属性(例如
variables、service.name)。当值来自标准遥测属性时,使用DYNAMIC类型。每个变量需要为deployment.environment.name和id分配UUID。key -
重新排列布局 / 并排放置:
- 仪表盘使用12列网格。的范围为0–11,
x的范围为1–12。w - 两个面板并排:每个面板的设为6,第一个的
w设为0,第二个的x设为6,x和y值相同。h - 三个面板在一行:设为4,分别位于
w、x:0、x:4。x:8 - 调整现有面板大小以腾出空间时,更新其和
w值,然后将新面板放在同一x值的空闲空间中。y - 常见高度:图表/表格面板的设为6,数值面板的
h设为2–3,行标题的h设为1。h - 保持panelMap同步:每当修改顶层数组中的
layout、x、y或w值时,需对h中的对应条目应用相同的修改。这些内容是重复的,必须保持一致。panelMap[rowId].widgets
- 仪表盘使用12列网格。
调用,传入仪表盘UUID和完整的修改后仪表盘JSON。
signoz:signoz_update_dashboardStep 5: Report the result
步骤5:反馈结果
Briefly tell the user what was changed. Offer further modifications if relevant.
简要告知用户已完成的修改。如有相关需求,可提供进一步修改的选项。
Guardrails
防护规则
- Full state on update: requires the complete dashboard JSON (not a partial patch). Always call
signoz:signoz_update_dashboardfirst to get the current state, merge your changes into that full object, and pass the result tosignoz:signoz_get_dashboard. Never construct an update payload from scratch.signoz:signoz_update_dashboard - Preserve what you don't change: Never drop or overwrite widgets, variables, layout items, or panelMap entries that are outside the scope of the user's request. Diff-and-merge, do not rebuild.
- Confirm destructive changes: Before removing panels, replacing queries, or deleting variables, confirm with the user — even if they say "just do it" or express urgency. Additions, renames, type changes, and variable additions do not need confirmation.
- Valid JSON only: Follow the v5 schema documented in the
MCP resources (
signoz://dashboard/*,instructions,widgets-instructions,widgets-examples). Include all required widget fields (see "Adding a panel" above). Never generate malformed queries or layouts.query-builder-example - OTel attribute names: Always use OpenTelemetry semantic conventions for
attribute names in filters, groupBy, and variables. Use not
service.name,servicenothost.name,hostnotdeployment.environment.name.env - No metric guessing: If adding or changing queries and you are not sure what
metrics are available, ask the user or call to discover available metrics. Wrong metric names produce empty panels.
signoz:signoz_list_metrics - Paginate dashboard listing: When searching for a dashboard by name, always
paginate through all pages of before concluding a dashboard does not exist.
signoz:signoz_list_dashboards - UUIDs for new objects: Every new widget, layout item, variable, and query
needs a unique UUID (format). Never use sequential IDs or short strings.
crypto.randomUUID() - Scope boundary: This skill modifies existing dashboards. To create a new dashboard from scratch, point the user at the SigNoz dashboard editor in the UI — there is no creation skill in this plugin yet.
- 更新时需提供完整状态:需要完整的仪表盘JSON(而非部分补丁)。务必先调用
signoz:signoz_update_dashboard获取当前状态,将变更合并到该完整对象中,再将结果传递给signoz:signoz_get_dashboard。切勿从头构建更新负载。signoz:signoz_update_dashboard - 保留未修改内容:切勿删除或覆盖不属于用户请求范围的小部件、变量、布局项或panelMap条目。使用差异合并,而非重新构建。
- 确认破坏性变更:在移除面板、替换查询语句或删除变量前,需与用户确认——即使用户说“直接做”或表示急切。添加、重命名、类型变更和变量添加无需确认。
- 仅使用有效JSON:遵循MCP资源(
signoz://dashboard/*、instructions、widgets-instructions、widgets-examples)中记录的v5 schema。包含所有必填的小部件字段(见上文“添加面板”部分)。切勿生成格式错误的查询语句或布局。query-builder-example - 使用OTel属性名称:在筛选器、groupBy和变量中始终使用OpenTelemetry语义规范的属性名称。使用而非
service.name,service而非host.name,host而非deployment.environment.name。env - 不要猜测指标:如果添加或修改查询语句时不确定可用的指标,可询问用户或调用发现可用指标。错误的指标名称会导致面板无数据。
signoz:signoz_list_metrics - 分页列出仪表盘:按名称搜索仪表盘时,务必遍历的所有页面后,再判定仪表盘不存在。
signoz:signoz_list_dashboards - 新对象使用UUID:每个新的小部件、布局项、变量和查询语句都需要唯一的UUID(格式)。切勿使用顺序ID或短字符串。
crypto.randomUUID() - 范围边界:本技能仅修改现有仪表盘。如需从头创建新仪表盘,请引导用户使用SigNoz UI中的仪表盘编辑器——当前插件中暂无创建技能。
Examples
示例
User: "Add an error rate panel to my Redis dashboard"
Agent:
- Calls (paginates all pages) — finds "Redis Overview" dashboard with UUID
signoz:signoz_list_dashboards.abc-123 - Calls with UUID
signoz:signoz_get_dashboard— gets full configuration with 8 existing panels.abc-123 - Calls to find available Redis error metrics.
signoz:signoz_list_metrics - Creates a new graph widget (with UUID, all required fields, and a formula query
for error rate), adds a layout entry at the next available position, and adds it to the appropriate row's
y.panelMap - Calls with the full modified JSON (all 9 panels).
signoz:signoz_update_dashboard - Reports: "Added an 'Error Rate' graph panel to your Redis Overview dashboard under the Overview section. Want me to adjust anything?"
User: "Change the latency panel from a graph to a table on my API dashboard"
Agent:
- Identifies "API Monitoring" dashboard from context, calls .
signoz:signoz_get_dashboard - Finds the panel titled "Request Latency" — if multiple panels could match, confirms with user: "I found 'Request Latency'. Convert that one to a table?"
- Changes from
panelTypesto"graph", adds"table"andcolumnUnitsif missing, keeps the query intact.columnWidths - Calls with the full modified JSON (all panels preserved).
signoz:signoz_update_dashboard - Reports: "Changed 'Request Latency' from a graph to a table. Want me to adjust column widths or add column units?"
User: "Remove the CPU panel and rename the dashboard to 'Service Health'"
Agent:
- Fetches the dashboard via .
signoz:signoz_get_dashboard - Finds the "CPU Usage" panel. Confirms: "I'll remove the 'CPU Usage' panel and rename the dashboard to 'Service Health'. Proceed?" (Removal is destructive — always confirm.)
- User confirms.
- Removes the widget from , its layout entry, and its panelMap reference. Leaves all other panel positions unchanged (the frontend grid closes gaps automatically). Updates
widgetsandtitleto "Service Health".name - Calls with the full modified JSON.
signoz:signoz_update_dashboard - Reports: "Removed the 'CPU Usage' panel and renamed the dashboard to 'Service Health'. Anything else to adjust?"
用户:“给我的Redis仪表盘添加一个错误率面板”
Agent:
- 调用(遍历所有分页)——找到名为“Redis Overview”的仪表盘,UUID为
signoz:signoz_list_dashboards。abc-123 - 调用并传入UUID
signoz:signoz_get_dashboard——获取包含8个现有面板的完整配置。abc-123 - 调用查找可用的Redis错误指标。
signoz:signoz_list_metrics - 创建一个新的图表小部件(包含UUID、所有必填字段和错误率的公式查询),在下一个可用的位置添加布局条目,并将其添加到对应行的
y中。panelMap - 调用并传入完整的修改后JSON(包含9个面板)。
signoz:signoz_update_dashboard - 反馈:“已在您的Redis Overview仪表盘的Overview板块下添加了‘Error Rate’图表面板。需要调整其他内容吗?”
用户:“把我的API仪表盘上的延迟面板从图表改成表格”
Agent:
- 从上下文中识别出“API Monitoring”仪表盘,调用。
signoz:signoz_get_dashboard - 找到标题为“Request Latency”的面板——如果有多个面板匹配,与用户确认:“我找到了‘Request Latency’面板,要将其转换为表格吗?”
- 将从
panelTypes改为"graph",如果缺少"table"和columnUnits则添加这两个字段,保留查询语句不变。columnWidths - 调用并传入完整的修改后JSON(保留所有面板)。
signoz:signoz_update_dashboard - 反馈:“已将‘Request Latency’从图表改为表格。需要调整列宽或添加列单位吗?”
用户:“移除CPU面板并将仪表盘重命名为‘Service Health’”
Agent:
- 通过获取仪表盘。
signoz:signoz_get_dashboard - 找到“CPU Usage”面板。与用户确认:“我将移除‘CPU Usage’面板并将仪表盘重命名为‘Service Health’,可以继续吗?”(移除操作具有破坏性——务必确认)
- 用户确认。
- 从中删除该小部件,删除其布局条目和panelMap引用。保持其他所有面板位置不变(前端网格会自动填充间隙)。将
widgets和title更新为“Service Health”。name - 调用并传入完整的修改后JSON。
signoz:signoz_update_dashboard - 反馈:“已移除‘CPU Usage’面板并将仪表盘重命名为‘Service Health’。还有其他需要调整的内容吗?”",