signoz-modifying-dashboards

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Dashboard Modify

修改仪表盘

Prerequisites

前提条件

This skill calls SigNoz MCP server tools (
signoz:signoz_get_dashboard
,
signoz:signoz_update_dashboard
,
signoz:signoz_list_dashboards
,
signoz:signoz_list_metrics
). 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 hand-edit dashboard JSON without the MCP tools.
本技能调用SigNoz MCP服务器工具(
signoz:signoz_get_dashboard
signoz:signoz_update_dashboard
signoz:signoz_list_dashboards
signoz:signoz_list_metrics
)。运行工作流前,请确认
signoz:signoz_*
工具可用。如果不可用,说明SigNoz MCP服务器未安装或配置——请停止操作并引导用户按照以下链接进行设置:https://signoz.io/docs/ai/signoz-mcp-server/。请勿在没有MCP工具的情况下回退到原始HTTP调用或手动编辑仪表盘JSON。

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:
  1. Call
    signoz:signoz_list_dashboards
    to list existing dashboards. Paginate through all pages — check
    pagination.hasMore
    in the response. If
    hasMore
    is true, call again with
    offset
    set to
    pagination.nextOffset
    and repeat until all pages are exhausted. Never stop at the first page.
  2. Present matching candidates to the user and ask which one to modify.
确认用户想要修改的仪表盘。如果用户提供了仪表盘名称、UUID,或者上下文明确(例如@提及或自动上下文提供了仪表盘资源),则直接使用该信息。
如果目标仪表盘不明确:
  1. 调用
    signoz:signoz_list_dashboards
    列出所有现有仪表盘。需遍历所有分页——检查响应中的
    pagination.hasMore
    。如果
    hasMore
    为true,则使用
    offset
    设置为
    pagination.nextOffset
    再次调用,重复此操作直到获取所有页面内容。切勿仅停留在第一页。
  2. 将匹配的候选仪表盘展示给用户,询问要修改哪一个。

Step 2: Fetch the current dashboard state

步骤2:获取当前仪表盘状态

Call
signoz:signoz_get_dashboard
with the dashboard UUID to retrieve its full configuration. This is mandatory
signoz:signoz_update_dashboard
requires the complete post-update state, not a partial patch. Never skip this step.
Examine 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
    panelMap
    structure (row-to-child mappings)
调用
signoz:signoz_get_dashboard
并传入仪表盘UUID,以获取其完整配置。这一步是必须的——
signoz: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
    dataSource
    (e.g., traces → logs), or fundamentally altering what data is shown (changing aggregation from p99 to avg, removing groupBy dimensions)
  • 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.
根据用户的请求规划修改内容。
以下情况需先与用户确认再执行修改:
  • 修改具有破坏性——移除面板、删除变量、用完全不同的查询语句替换原有查询、更改面板的
    dataSource
    (例如,追踪→日志),或从根本上改变展示的数据(将聚合方式从p99改为平均值、移除groupBy维度)
  • 请求存在歧义——多个面板都可能匹配“延迟面板”的描述
  • 修改范围较大——重构板块、一次性添加多个面板
破坏性指会导致数据丢失或行为静默变更。即使用户说“快点做”,也需要简短确认(例如“我将永久移除‘内存碎片’面板,可以吗?”),这仅需几秒钟,却能避免不可挽回的错误。用户的急切需求不能绕过此防护规则。
**非破坏性变更可直接执行:**重命名、添加单个面板、修改单位、添加变量、切换面板类型(查询语句保留)、调整布局、添加阈值。
**复合修改:**当请求包含多项变更(例如,移除一个面板+添加一个面板+重命名),需基于获取的状态规划所有变更,并作为单次更新应用。请勿在变更之间重复执行应用和重新获取状态的操作。

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:
    1. Create a new widget with a UUID for its
      id
      (use
      crypto.randomUUID()
      format).
    2. Include all required widget fields:
      id
      ,
      title
      ,
      description
      ,
      panelTypes
      ,
      query
      ,
      opacity
      ("1"),
      nullZeroValues
      ("zero"),
      timePreferance
      ("GLOBAL_TIME" — note the deliberate misspelling),
      stepSize
      (60),
      yAxisUnit
      ,
      isStacked
      (false),
      fillSpans
      (false),
      isLogScale
      (false),
      mergeAllActiveQueries
      (false),
      thresholds
      ([]),
      softMin
      (0),
      softMax
      (0),
      legendPosition
      ("bottom"),
      columnUnits
      ({}),
      customLegendColors
      ({}),
      selectedLogFields
      ([]),
      selectedTracesFields
      ([]),
      contextLinks
      ({"linksData": []}).
    3. Add a layout entry with
      i
      matching the widget ID, and appropriate
      x
      ,
      y
      ,
      w
      ,
      h
      values in the 12-column grid.
    4. If the dashboard uses rows, add the panel's layout to the appropriate row's
      panelMap[rowId].widgets
      array. If the dashboard has no rows (empty
      panelMap
      ), skip panelMap — the panel lives at the top level.
    5. For query construction, read the
      signoz://dashboard/query-builder-example
      MCP resource for the v5 builder query format. Use the signal-specific resources as needed (
      signoz://dashboard/promql-example
      ,
      signoz://dashboard/clickhouse-*
      ,
      signoz://traces/query-builder-guide
      ).
  • Removing a panel: Remove the widget from
    widgets
    , its entry from
    layout
    , and its entry from the parent row's
    panelMap.widgets
    (if it exists in panelMap). Do not try to auto-compact or shift
    y
    positions 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.
  • Editing a panel's query: Replace the query object on the target widget. Keep all other widget fields intact.
  • Changing panel type: Update
    panelTypes
    and handle type-specific fields:
    • graph
      table
      : add
      columnUnits
      ({}) and
      columnWidths
      ({}) if missing. Graph-only fields like
      isStacked
      ,
      fillSpans
      ,
      isLogScale
      become inert but are harmless to leave.
    • graph
      /
      table
      histogram
      : add
      bucketCount
      (30) and
      bucketWidth
      (0).
    • Any →
      list
      (logs): add
      selectedLogFields
      array.
    • Any →
      list
      (traces): add
      selectedTracesFields
      array.
    • Keep the existing query intact — the data source and query are independent of the visualization type.
  • Adding/editing variables: Add or update entries in the
    variables
    map. Use OTel attribute names for the underlying attribute (e.g.,
    service.name
    ,
    deployment.environment.name
    ). Use DYNAMIC type when the values come from a standard telemetry attribute. Each variable needs a UUID for
    id
    and
    key
    .
  • Rearranging layout / side-by-side placement:
    • Dashboard uses a 12-column grid.
      x
      ranges 0–11,
      w
      ranges 1–12.
    • Two panels side-by-side: each gets
      w: 6
      , first at
      x: 0
      , second at
      x: 6
      , same
      y
      and
      h
      .
    • Three panels in a row:
      w: 4
      at
      x: 0
      ,
      x: 4
      ,
      x: 8
      .
    • When resizing an existing panel to make room, update its
      w
      and
      x
      , then place the new panel in the freed space at the same
      y
      .
    • Common heights:
      h: 6
      for graphs/tables,
      h: 2
      h: 3
      for value panels,
      h: 1
      for row headers.
    • Keep panelMap in sync: whenever you change
      x
      ,
      y
      ,
      w
      , or
      h
      in the top-level
      layout
      array, apply the same change to the matching entry in
      panelMap[rowId].widgets
      . These are duplicated and must stay consistent.
Call
signoz:signoz_update_dashboard
with the dashboard UUID and the complete modified dashboard JSON.
将规划的变更合并到步骤2获取的完整仪表盘JSON中。
修改规则:
  • 保留所有未修改的内容。复制整个仪表盘对象,仅修改用户要求变更的特定字段。请勿删除不属于变更范围的小部件、变量、布局项或panelMap条目。
  • 添加面板:
    1. 创建一个新的小部件,为其
      id
      分配一个UUID(使用
      crypto.randomUUID()
      格式)。
    2. 包含所有必填的小部件字段:
      id
      title
      description
      panelTypes
      query
      opacity
      (值为"1")、
      nullZeroValues
      (值为"zero")、
      timePreferance
      (值为"GLOBAL_TIME"——注意此处拼写故意有误)、
      stepSize
      (值为60)、
      yAxisUnit
      isStacked
      (值为false)、
      fillSpans
      (值为false)、
      isLogScale
      (值为false)、
      mergeAllActiveQueries
      (值为false)、
      thresholds
      (值为[])、
      softMin
      (值为0)、
      softMax
      (值为0)、
      legendPosition
      (值为"bottom")、
      columnUnits
      (值为{})、
      customLegendColors
      (值为{})、
      selectedLogFields
      (值为[])、
      selectedTracesFields
      (值为[])、
      contextLinks
      (值为{"linksData": []})。
    3. 添加一个布局条目,其
      i
      值与小部件ID匹配,并在12列网格中设置合适的
      x
      y
      w
      h
      值。
    4. 如果仪表盘使用行结构,将面板的布局添加到对应行的
      panelMap[rowId].widgets
      数组中。如果仪表盘没有行结构(
      panelMap
      为空),则跳过panelMap——面板直接位于顶层。
    5. 构建查询语句时,请参考
      signoz://dashboard/query-builder-example
      MCP资源中的v5构建器查询格式。根据需要使用特定信号的资源(
      signoz://dashboard/promql-example
      signoz://dashboard/clickhouse-*
      signoz://traces/query-builder-guide
      )。
  • **移除面板:**从
    widgets
    中删除该小部件,从
    layout
    中删除其条目,并从父行的
    panelMap.widgets
    中删除其条目(如果存在于panelMap中)。请勿尝试自动压缩或调整剩余面板的
    y
    位置——SigNoz前端网格引擎会自动处理间隙填充。只需删除这三处引用(小部件、布局、panelMap条目),保持其他所有位置不变。
  • **编辑面板的查询语句:**替换目标小部件的查询对象。保留小部件的所有其他字段不变。
  • **切换面板类型:**更新
    panelTypes
    并处理类型特定字段:
    • graph
      table
      :如果缺少
      columnUnits
      (值为{})和
      columnWidths
      (值为{}),则添加这两个字段。仅图表有的字段如
      isStacked
      fillSpans
      isLogScale
      会失效,但保留它们不会产生问题。
    • graph
      /
      table
      histogram
      :添加
      bucketCount
      (值为30)和
      bucketWidth
      (值为0)。
    • 任意类型 →
      list
      (日志):添加
      selectedLogFields
      数组。
    • 任意类型 →
      list
      (追踪):添加
      selectedTracesFields
      数组。
    • 保留现有查询语句不变——数据源和查询语句与可视化类型无关。
  • **添加/编辑变量:**在
    variables
    映射中添加或更新条目。使用OTel属性名称作为底层属性(例如
    service.name
    deployment.environment.name
    )。当值来自标准遥测属性时,使用DYNAMIC类型。每个变量需要为
    id
    key
    分配UUID。
  • 重新排列布局 / 并排放置:
    • 仪表盘使用12列网格
      x
      的范围为0–11,
      w
      的范围为1–12。
    • 两个面板并排:每个面板的
      w
      设为6,第一个的
      x
      设为0,第二个的
      x
      设为6,
      y
      h
      值相同。
    • 三个面板在一行:
      w
      设为4,分别位于
      x:0
      x:4
      x:8
    • 调整现有面板大小以腾出空间时,更新其
      w
      x
      值,然后将新面板放在同一
      y
      值的空闲空间中。
    • 常见高度:图表/表格面板的
      h
      设为6,数值面板的
      h
      设为2–3,行标题的
      h
      设为1。
    • 保持panelMap同步:每当修改顶层
      layout
      数组中的
      x
      y
      w
      h
      值时,需对
      panelMap[rowId].widgets
      中的对应条目应用相同的修改。这些内容是重复的,必须保持一致。
调用
signoz:signoz_update_dashboard
,传入仪表盘UUID和完整的修改后仪表盘JSON。

Step 5: Report the result

步骤5:反馈结果

Briefly tell the user what was changed. Offer further modifications if relevant.
简要告知用户已完成的修改。如有相关需求,可提供进一步修改的选项。

Guardrails

防护规则

  • Full state on update:
    signoz:signoz_update_dashboard
    requires the complete dashboard JSON (not a partial patch). Always call
    signoz:signoz_get_dashboard
    first to get the current state, merge your changes into that full object, and pass the result to
    signoz:signoz_update_dashboard
    . Never construct an update payload from scratch.
  • 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
    signoz://dashboard/*
    MCP resources (
    instructions
    ,
    widgets-instructions
    ,
    widgets-examples
    ,
    query-builder-example
    ). Include all required widget fields (see "Adding a panel" above). Never generate malformed queries or layouts.
  • OTel attribute names: Always use OpenTelemetry semantic conventions for attribute names in filters, groupBy, and variables. Use
    service.name
    not
    service
    ,
    host.name
    not
    host
    ,
    deployment.environment.name
    not
    env
    .
  • No metric guessing: If adding or changing queries and you are not sure what metrics are available, ask the user or call
    signoz:signoz_list_metrics
    to discover available metrics. Wrong metric names produce empty panels.
  • Paginate dashboard listing: When searching for a dashboard by name, always paginate through all pages of
    signoz:signoz_list_dashboards
    before concluding a dashboard does not exist.
  • UUIDs for new objects: Every new widget, layout item, variable, and query needs a unique UUID (
    crypto.randomUUID()
    format). Never use sequential IDs or short strings.
  • 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.
  • 更新时需提供完整状态
    signoz:signoz_update_dashboard
    需要完整的仪表盘JSON(而非部分补丁)。务必先调用
    signoz:signoz_get_dashboard
    获取当前状态,将变更合并到该完整对象中,再将结果传递给
    signoz:signoz_update_dashboard
    。切勿从头构建更新负载。
  • 保留未修改内容:切勿删除或覆盖不属于用户请求范围的小部件、变量、布局项或panelMap条目。使用差异合并,而非重新构建。
  • 确认破坏性变更:在移除面板、替换查询语句或删除变量前,需与用户确认——即使用户说“直接做”或表示急切。添加、重命名、类型变更和变量添加无需确认。
  • 仅使用有效JSON:遵循
    signoz://dashboard/*
    MCP资源(
    instructions
    widgets-instructions
    widgets-examples
    query-builder-example
    )中记录的v5 schema。包含所有必填的小部件字段(见上文“添加面板”部分)。切勿生成格式错误的查询语句或布局。
  • 使用OTel属性名称:在筛选器、groupBy和变量中始终使用OpenTelemetry语义规范的属性名称。使用
    service.name
    而非
    service
    host.name
    而非
    host
    deployment.environment.name
    而非
    env
  • 不要猜测指标:如果添加或修改查询语句时不确定可用的指标,可询问用户或调用
    signoz:signoz_list_metrics
    发现可用指标。错误的指标名称会导致面板无数据。
  • 分页列出仪表盘:按名称搜索仪表盘时,务必遍历
    signoz:signoz_list_dashboards
    的所有页面后,再判定仪表盘不存在。
  • 新对象使用UUID:每个新的小部件、布局项、变量和查询语句都需要唯一的UUID(
    crypto.randomUUID()
    格式)。切勿使用顺序ID或短字符串。
  • 范围边界:本技能仅修改现有仪表盘。如需从头创建新仪表盘,请引导用户使用SigNoz UI中的仪表盘编辑器——当前插件中暂无创建技能。

Examples

示例

User: "Add an error rate panel to my Redis dashboard"
Agent:
  1. Calls
    signoz:signoz_list_dashboards
    (paginates all pages) — finds "Redis Overview" dashboard with UUID
    abc-123
    .
  2. Calls
    signoz:signoz_get_dashboard
    with UUID
    abc-123
    — gets full configuration with 8 existing panels.
  3. Calls
    signoz:signoz_list_metrics
    to find available Redis error metrics.
  4. 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
    y
    position, and adds it to the appropriate row's
    panelMap
    .
  5. Calls
    signoz:signoz_update_dashboard
    with the full modified JSON (all 9 panels).
  6. 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:
  1. Identifies "API Monitoring" dashboard from context, calls
    signoz:signoz_get_dashboard
    .
  2. Finds the panel titled "Request Latency" — if multiple panels could match, confirms with user: "I found 'Request Latency'. Convert that one to a table?"
  3. Changes
    panelTypes
    from
    "graph"
    to
    "table"
    , adds
    columnUnits
    and
    columnWidths
    if missing, keeps the query intact.
  4. Calls
    signoz:signoz_update_dashboard
    with the full modified JSON (all panels preserved).
  5. 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:
  1. Fetches the dashboard via
    signoz:signoz_get_dashboard
    .
  2. 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.)
  3. User confirms.
  4. Removes the widget from
    widgets
    , its layout entry, and its panelMap reference. Leaves all other panel positions unchanged (the frontend grid closes gaps automatically). Updates
    title
    and
    name
    to "Service Health".
  5. Calls
    signoz:signoz_update_dashboard
    with the full modified JSON.
  6. Reports: "Removed the 'CPU Usage' panel and renamed the dashboard to 'Service Health'. Anything else to adjust?"
用户:“给我的Redis仪表盘添加一个错误率面板”
Agent:
  1. 调用
    signoz:signoz_list_dashboards
    (遍历所有分页)——找到名为“Redis Overview”的仪表盘,UUID为
    abc-123
  2. 调用
    signoz:signoz_get_dashboard
    并传入UUID
    abc-123
    ——获取包含8个现有面板的完整配置。
  3. 调用
    signoz:signoz_list_metrics
    查找可用的Redis错误指标。
  4. 创建一个新的图表小部件(包含UUID、所有必填字段和错误率的公式查询),在下一个可用的
    y
    位置添加布局条目,并将其添加到对应行的
    panelMap
    中。
  5. 调用
    signoz:signoz_update_dashboard
    并传入完整的修改后JSON(包含9个面板)。
  6. 反馈:“已在您的Redis Overview仪表盘的Overview板块下添加了‘Error Rate’图表面板。需要调整其他内容吗?”

用户:“把我的API仪表盘上的延迟面板从图表改成表格”
Agent:
  1. 从上下文中识别出“API Monitoring”仪表盘,调用
    signoz:signoz_get_dashboard
  2. 找到标题为“Request Latency”的面板——如果有多个面板匹配,与用户确认:“我找到了‘Request Latency’面板,要将其转换为表格吗?”
  3. panelTypes
    "graph"
    改为
    "table"
    ,如果缺少
    columnUnits
    columnWidths
    则添加这两个字段,保留查询语句不变。
  4. 调用
    signoz:signoz_update_dashboard
    并传入完整的修改后JSON(保留所有面板)。
  5. 反馈:“已将‘Request Latency’从图表改为表格。需要调整列宽或添加列单位吗?”

用户:“移除CPU面板并将仪表盘重命名为‘Service Health’”
Agent:
  1. 通过
    signoz:signoz_get_dashboard
    获取仪表盘。
  2. 找到“CPU Usage”面板。与用户确认:“我将移除‘CPU Usage’面板并将仪表盘重命名为‘Service Health’,可以继续吗?”(移除操作具有破坏性——务必确认)
  3. 用户确认。
  4. widgets
    中删除该小部件,删除其布局条目和panelMap引用。保持其他所有面板位置不变(前端网格会自动填充间隙)。将
    title
    name
    更新为“Service Health”。
  5. 调用
    signoz:signoz_update_dashboard
    并传入完整的修改后JSON。
  6. 反馈:“已移除‘CPU Usage’面板并将仪表盘重命名为‘Service Health’。还有其他需要调整的内容吗?”",