signoz-explaining-dashboards

仪表板解读

前提条件

此技能会调用 SigNoz MCP 服务工具（signoz_get_dashboard、 signoz_list_dashboards）。运行工作流前，请确认 signoz_* 工具可用。如果不可用，说明尚未安装或配置 SigNoz MCP 服务； 请先运行 signoz-mcp-setup，以初始化或修复 MCP 连接。不要仅凭仪表板标题 猜测其内容。

适用场景

用户提出以下需求时，使用此技能：

• 了解、解释或解读现有仪表板
• 了解各面板展示的内容及其重要性
• 了解仪表板上需要关注的内容，或健康／异常状态的表现
• 了解仪表板上的变量、筛选条件或查询

请勿在以下情况使用：

• 用户想要修改现有仪表板 → signoz-modifying-dashboards

说明

步骤 1：确定目标仪表板

使用用户提供的 ID，或直接包含 ID 的仪表板资源。 如果用户只提供名称，请调用 signoz_list_dashboards，并通过 spec.display.name 将名称解析为 ID。请检查完整列表：使用 filter 参数缩小范围；如果结果为空，则不带筛选条件重新运行；并通过将 offset 增加 limit 逐页查询，直至覆盖 total。切勿将仪表板名称传给 signoz_get_dashboard，也不要仅凭第一页就断定仪表板不存在。

如果匹配到多个仪表板，请列出候选项，并询问用户想要解读哪一个。

步骤 2：获取完整的仪表板配置

使用仪表板 ID 调用 signoz_get_dashboard。这是必需步骤；要准确解读仪表板， 必须获取完整的 JSON。切勿仅凭标题猜测。

检查响应，了解以下内容：

• spec.display.name、.description、tags：仪表板的身份信息及作者提供的背景
• spec.variables：仪表板级筛选条件（用户可更改的下拉选项）
• spec.panels（以面板 ID 为键的映射）：面板、其插件类型、标题和查询
• spec.layouts：通过 content.$ref 将面板放置在 12 列网格中的 Grid 条目
• 各 Grid 的 spec.display.title：面板所属的区块

第 3 步：撰写说明

按以下顺序组织说明：

1. 概览：用一段话概述仪表板的用途、监控内容，以及它使用的数据源（指标、追踪、日志）。如果 tags 能提供有用的背景信息，也请提及。

2. 变量和筛选条件：说明每个变量：

• 名称（spec.name，即 $handle 查询引用的名称）及其筛选内容；对于 signoz/DynamicVariable，这是 plugin.spec.signal 上的 plugin.spec.name
• 类型：signoz/DynamicVariable（从遥测数据自动填充）、signoz/QueryVariable（由查询驱动的下拉选项）、signoz/CustomVariable（已配置的选项），或 TextVariable（自由文本输入）
• 是否支持多选（allowMultiple），以及是否有“ALL”选项
• 如果有面板的 filter.expression 未引用某个变量，请予以说明：更改该变量的下拉选项不会影响这些面板，可能造成困惑

3. 逐个面板说明。按 Grid 分区对面板分组：按顺序遍历 spec.layouts，使用每个 Grid 的 spec.display.title 作为分区标题，并按照 spec.items（先按 y，再按 x）找到它们通过 $ref 引用的面板。对于仅有一个且未命名的 Grid，请按位置顺序遍历面板，并按逻辑主题组织。对每个面板：

• 标题和面板类型：根据插件 kind，用通俗语言说明：signoz/TimeSeriesPanel、signoz/NumberPanel（单值）、signoz/TablePanel、signoz/BarChartPanel、signoz/PieChartPanel、signoz/HistogramPanel、signoz/ListPanel（原始行）、signoz/AreaChartPanel（填充曲线；visualization.stack 为 normal 时显示总量，为 percent 时显示各曲线占比）、signoz/TextPanel（无查询的静态说明）
• 显示内容：用通俗语言解读面板中的查询。对于 signoz/BuilderQuery，说明信号、聚合、filter.expression 和 groupBy。对于 signoz/CompositeQuery，说明每个成员以及公式如何将它们组合起来。对于 ClickHouse SQL 或 PromQL，将查询意图转述为通俗语言。
• 需要关注的情况：说明什么情况表示健康，什么模式表示出现问题。请具体说明：“使用率持续高于 80% 意味着……”而不是只说“注意是否过高”。建议应根据实际查询的指标，而不是笼统的领域知识。
• 单位：提及 plugin.spec.formatting.unit，以便用户了解如何读取数值

对于查询较复杂的面板：

• 公式（位于复合查询中）：分别说明每个成员（A、B 等），然后说明公式计算的内容及其目的
• 函数（rate、derivative、clampMin/Max、timeShift）：用通俗语言说明转换含义（例如：“rate 会将原始计数器转换为每秒值”）

4. 仪表板健康状况观察。完成逐个面板说明后，指出发现的结构性问题：

• 没有查询的面板，或成员全部已停用的复合查询
• spec.panels 中没有任何 Grid 项引用的面板（它们不会显示）
• 已定义但未被任何面板筛选条件引用的变量
• 缺少适用阈值的面板（例如，没有饱和警告线的利用率面板）
• 未使用速率函数便显示的计数器（原始计数器会不断上升，而非显示运行指标速率）
• 可能隐藏尖峰的过宽步长间隔
• 可能导致图表难以阅读的高基数 groupBy

5. 覆盖缺口。根据仪表板实际监控的内容，指出缺失的重要可观测性领域。仅提及与仪表板所涵盖的技术或领域直接相关的缺口；不要推测无关领域。以建议的形式表达：“您可以考虑添加 X 面板，以覆盖 Y。”

第 4 步：提供后续建议

根据说明中揭示的信息，提出最多 3 个后续意图，例如运行某个面板的底层查询、弥补覆盖范围的缺口，或针对用户尚未设置告警的可操作阈值配置告警。酌情判断；不要为了凑数而硬凑 3 个。

如果用户显然只是在了解仪表板（“这是什么？”），且没有表现出进一步意图，则跳过后续建议。不提供后续建议，也好过提供错误的建议。

防护措施

• 先获取，再说明：始终调用 signoz_get_dashboard 获取完整配置。切勿仅根据仪表板标题或列表内容进行说明。
• 解释，不要照搬：将查询转换为通俗的运维语言。除非用户明确要求，否则切勿向用户展示原始查询 JSON。
• 以实际内容为依据：有关“需要关注什么”的建议，应基于仪表板中的实际指标和查询，而非与现有面板无关的通用领域知识。
• 按分区分组：使用每个 Grid 的 spec.display.title 对面板分组，不要按布局坐标分组。这些标题是仪表板作者设定的分区标题。
• 默认不查询数据：除非用户提出要求，否则不要运行实时查询。解释技能旨在帮助理解仪表板结构，而非检查当前数据。
• 对仪表板列表进行分页：按名称搜索仪表板时，在确认某个仪表板不存在之前，始终遍历 signoz_list_dashboards 的所有页面。
• 支持所有查询类型：处理 builder、ClickHouse SQL 和 PromQL 查询；每种查询都需要采用不同的解释方法。对于 builder 查询，读取聚合、筛选表达式和 groupBy。对于原始 SQL/PromQL，解析查询字符串并说明其意图。
• 范围边界：此技能用于解释仪表板。如果用户在获得说明后希望进行更改，请引导其使用 signoz-modifying-dashboards。

示例

用户：“解释一下我的 PostgreSQL 仪表板”

Agent：

1. 调用 signoz_list_dashboards（遍历所有分页）：找到名为“PostgreSQL Overview”、id 为 abc-123 的仪表板。
2. 使用 id abc-123 调用 signoz_get_dashboard：获取完整配置。
3. 提供结构化说明：
   • 概览：“此仪表板监控 PostgreSQL 数据库的健康状况，包括连接数、查询性能、缓冲区缓存效率和复制。它使用 OpenTelemetry PostgreSQL 接收器的指标。”
   • 变量：“有两个变量：host_name（动态变量，按 host.name 筛选）和 database（动态变量，按 postgresql.database.name 筛选）。 两者都支持多选。”
   • 按部分划分的面板：逐一介绍每个网格部分，解释每个面板的指标、聚合方式以及需要关注的事项。
   • 健康状况观察：“‘连接数’面板未配置阈值；建议在最大连接数的 80% 处添加一条线。”
   • 覆盖范围缺口：“没有用于监控 vacuum/autovacuum 健康状况或锁争用的面板。如果你负责管理写入繁重的工作负载，建议添加这些面板。”
4. 询问：“需要我运行任何面板查询来检查数据，或添加建议的面板吗？”

---

用户：“这个仪表板上的每个面板都显示什么？”（通过 @mention 或自动上下文提供仪表板上下文）

Agent：

1. 从提供的上下文中提取仪表板 id。
2. 调用 signoz_get_dashboard：获取完整配置。
3. 按网格部分分组，逐一介绍面板，说明每个面板显示的内容以及需要关注的事项。
4. 除非发现值得注意的问题，否则跳过健康状况和覆盖缺口部分，因为用户具体询问的是面板。

---

用户：“帮我了解一下这个大模型监控仪表板，我刚接触它。”

Agent：

1. 确定仪表板并获取完整配置。
2. 提供适合初学者的说明，详细介绍每个面板：
   • 解释指标的含义（例如：“Token 使用量表示大模型调用消耗的 Token 数，直接影响成本”）
   • 解释变量的控制内容，并建议先选择“ALL”选项，在筛选之前查看全貌
   • 强调哪些重要面板适合每天关注，哪些面板仅在调试时有用
3. 提议为关键面板设置告警。