signoz-creating-dashboards

Dashboard 创建

前置条件

此技能会调用 SigNoz MCP 服务工具（signoz_create_dashboard、 signoz_list_dashboards、signoz_list_dashboard_templates、 signoz_import_dashboard、signoz_get_dashboard、 signoz_update_dashboard、signoz_list_metrics、 signoz_get_field_keys、signoz_get_field_values、 signoz_aggregate_logs、signoz_aggregate_traces 等）。 运行工作流前，请确认 signoz_* 工具可用。如果不可用，则说明 SigNoz MCP 服务尚未安装或配置；请先运行 signoz-mcp-setup，以初始化或修复 MCP 连接。不要改用原始 HTTP 调用，也不要在没有 MCP 工具的情况下伪造 Dashboard JSON。

适用场景

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

• 创建、设置或构建新的 Dashboard。
• 为某项服务、数据库、基础设施组件或 AI/LLM 平台进行“监控”或“设置可观测性”。
• 导入精选的 Dashboard 模板。
• 在同一屏幕上一起可视化一组指标 / 跟踪 / 日志。

当用户想要执行以下操作时，请勿使用：

• 修改现有 Dashboard → signoz-modifying-dashboards。
• 了解现有 Dashboard 的展示内容 → signoz-explaining-dashboards。
• 运行一次性查询而不保存 → signoz-generating-queries。

必需输入（严格）

创建 Dashboard 是一项写入操作。此处猜测会让共享工作区堆满空白或范围错误的 Dashboard，最终还得由其他人清理。此技能执行宽松的输入约定；大多数字段都有合理的默认值，但少数值无法猜测：

输入	必需	缺失时的来源
Dashboard 意图（NL 目标）	是	$ARGUMENTS 或用户最近一轮对话
技术 / 领域（例如 PostgreSQL、Redis、“支付流水线”）	是	从意图中解析；否则询问
创建确认（以及存在重复项时的修改或创建选择）	是	询问用户（步骤 2）；即使没有重复项，且用户提到紧急程度，也仍需确认
自定义构建的资源范围（服务 / 命名空间 / 集群）	自定义构建时必需	通过 signoz_get_field_keys + signoz_get_field_values 发现；也可回退到 Dashboard 变量
自定义构建的具体指标 / 信号	推断	根据技术类型和 MCP signoz://dashboard/* 资源得出；在预览中展示
布局	推断	应用默认值（见下文“默认值”）

如果缺少必需输入且无法发现，请在调用任何写入工具前停止，并询问用户。由宿主应用决定如何展示问题（结构化澄清工具、内联 <assistant_question> 标签、交互式提示词等）；请遵循宿主的界面渲染规则。

问题中应包含：

• 缺少什么：具体指出所需输入（例如，“自定义构建未指定服务或集群”）。
• 基于发现调用提供的候选列表：列出用户可选择的各属性的具体值。示例格式： service.name → frontend、checkout、payments、inventory； k8s.cluster.name → prod-us-east-1、staging。
• 允许自由输入，让用户可以指定你未列出的值。

在自主模式下（没有人工参与），请升级给调用方处理，或从上游上下文中补全缺失信息。无论如何，都不要使用猜测的值继续调用 signoz_create_dashboard / signoz_import_dashboard。

工作流

创建流程从检查重复项 → 选择修改或创建 → 查找模板开始。匹配到模板时，流程为无数据探测 → 预览 → 导入；自定义构建时，流程为无数据探测 → 构建 → 逐面板试运行 → 预览 → 创建。模板查找在内部进行；用户唯一需要提前作出的选择是修改还是创建。

第 1 步：检查重复项

调用 signoz_list_dashboards。大多数安装的结果都能放在默认页面 （limit=50）中；当措辞具有辨识度时，可使用 filter 参数缩小范围 （参见 signoz://dashboard/list-filter-guide），并通过 offset 翻页，直到覆盖全部 total；该架构接受整数或字符串形式的 limit / offset 值。

按相关性匹配 将每个现有仪表板的小写 spec.display.name、.description 和 tags 与用户的技术领域进行比较。只展示人类会认为 属于同一主题的匹配项："redis" 仪表板不会仅仅因为带有 database 标签就匹配 "postgresql" 请求。收集每个匹配项的 spec.display.name、id 和 createdAt，供下一步使用。

第 2 步：询问用户（修改还是创建）

恰好提供两个选项（不要将模板导入作为单独的顶层 选项；这是第 3b 步中的内部决策）：

• 找到重复项： “已经有这些相似的仪表板： [列出名称、id、创建时间]。你希望我 (a) 修改其中一个， (b) 仍然创建一个新仪表板，还是 (c) 停止？”
• 没有重复项： “我将为此创建一个新仪表板。继续吗？” （没有可修改的内容时，不提供“修改”选项。）

等待用户选择。“修改” → 第 3a 步。“创建新的” / 确认 → 第 3b 步。“停止” → 停止。

第 3 步：创建或修改

第 3a 步：修改现有仪表板

立即将任务交给 signoz-modifying-dashboards，并提供所选的 仪表板 id 和用户意图。不要从此技能调用 signoz_update_dashboard 或 signoz_patch_dashboard； 修改不在范围内。（参见 Guardrails 中的“范围边界”。）

第 3b 步：创建新仪表板

先查找模板。用户已经同意创建新仪表板；查找结果将决定我们如何构建。

不带参数调用一次 signoz_list_dashboard_templates。 完整目录（约 95 个条目）会在一次调用中返回；在当前上下文中阅读并挑选最符合用户意图的条目。如果有多个条目都可能适用，请展示排名最高的 3–5 个，让用户选择。

根据结果分支：

• 只有一个明确匹配的模板：继续第 3b-i 步（导入模板）。简要告知用户“我找到了一个预构建的 [title] 模板，将使用它”，让用户知道要创建什么；不要等待用户确认。
• 有多个可能的匹配项：展示这些模板并请用户选择。选定后，继续第 3b-i 步。
• 模板与技术匹配，但与请求的信号不匹配：具体请求中很常见（例如“Kafka，但我想要按客户端统计的消费者提取速率”）。这不属于“没有模板”：先导入，然后将额外面板交给 signoz-modifying-dashboards，并提供新 id。从头构建没有任何收益，却会丢弃精心整理的基线。
• 没有模板：继续第 3b-ii 步（自定义构建）。这意味着目录中没有该技术的条目，而不是存在看起来不完美或针对不同指标族的条目。导入前无法读取模板正文，因此怀疑不匹配只能算是假设；而第 3b-i.1 步的探查位于导入流程之内，所以不能以此为由跳过该流程。先探查，再决定。

第 3b-i 步：导入模板

工具限制 唯一的模板工具是 signoz_list_dashboard_templates 和 signoz_import_dashboard。不要调用 shell、获取原始 GitHub URL，也不要编造其他工具名称。 signoz_import_dashboard 会使用目录条目中的模板 path，并通过一次调用创建仪表板，因此无需自行获取 JSON，也无需随后调用 signoz_create_dashboard。

Step 3b-i.1：预检查无数据探测（快速失败）

调用 signoz_import_dashboard 之前，先确认模板中的信号确实正在采集。模板导入时最常见的静默失败是“模板顺利导入，但每个面板都显示‘无数据’，因为该技术的数据未被采集”：用户点开后才发现仪表板毫无用处。

由于我们不会预先获取模板正文，因此请根据目录条目的 category、title 和 keywords，以及用户提到的技术进行探测。挑选最多约 5 个有代表性的信号并检查；总量保持精简：

• 基于指标的模板（大多数基础设施／运行时模板）：调用 signoz_list_metrics，将 searchText 设为技术前缀（例如 searchText="postgresql"）。结果为空 → 未采集该指标族。提前结束： 如果结果为空，就声明“均不存在”，并跳过其余指标探测；它们都会返回零。使用 timeRange 指定相对时间窗口；如果需要精确时间窗口而非服务器默认值，则传入 start／end（unix-ms 字符串）。
• 基于追踪的模板（APM 风格）：调用 signoz_aggregate_traces，设置 aggregation=count、timeRange=1h。探测“是否有任何数据流动”时无需筛选条件；添加 filter="service.name EXISTS" 不可靠，也没必要。计数为零 → 没有追踪数据流入。
• 基于日志的模板：调用 signoz_aggregate_logs，设置 aggregation=count、timeRange=1h，不添加筛选条件。计数为零 → 没有日志。
• 变量值（当模板明显依赖资源属性时，例如 service.name、k8s.cluster.name）：调用 signoz_get_field_values，确认有可供选择的值。顶层下拉菜单为空的仪表板，和所有面板都为空相比好不了多少。

根据探测结果分支处理：

• 所有信号均存在 → 不作提示，继续执行 Step 3b-i.2。
• 部分信号存在，部分缺失 → 列出缺失的信号，并询问用户是否确认继续。许多模板即使数据覆盖不完整仍然有用；由用户决定。
• 均不存在 → 告知用户在探测时间窗口内未找到该技术的数据，说明在设置数据采集之前，仪表板会显示“无数据”，并询问用户是要继续创建，还是停止。等待用户选择。

这项探测开销很低（少量查询，总计约数百毫秒）；尽早发现无数据情况，可以避免模板流程中最糟糕的用户体验问题。

Step 3b-i.2：预览、导入并报告

1. 预览 用一段简短文字告知用户即将进行的操作：使用哪个模板（title、path）、模板类别，以及探测结果。在自主模式下，使用者继续操作；在交互模式下，用户可以介入。
2. 导入 使用所选目录条目中的 path 调用 signoz_import_dashboard（例如 postgresql/postgresql.json）。服务器会在一次调用中获取 JSON、验证并创建仪表板。
3. 报告 查看响应并告知用户仪表板标题、面板数量和分区情况。说明仪表板的变量（“按 service.name 筛选”、“按 k8s.cluster.name 筛选”），让用户了解可调整的选项。提供两项后续操作：“要我调整面板、布局或变量吗？”以及“要我为这些信号配置告警吗？（signoz-creating-alerts）”。
4. 自定义处理 如果用户要求更改导入的仪表板，将新仪表板的 id 和请求的更改交给 signoz-modifying-dashboards。不要通过此技能调用 signoz_update_dashboard。

Step 3b-ii：自定义构建（无模板或导入失败）

如果 Step 3b 的模板查找没有找到匹配项、用户明确拒绝了建议的模板，或 signoz_import_dashboard 调用失败，则执行此流程。

步骤 3b-ii.1：收集需求

询问用户（如果意图已明确回答了某个问题，则跳过）：

1. 信号：指标、追踪、日志，或它们的组合。
2. 具体信号：哪些指标、哪些 span 属性、哪些日志严重级别最重要。
3. 资源范围：哪些服务、命名空间、集群或环境。
4. 变量：哪些内容应作为下拉选项，哪些应作为硬编码筛选条件（常见项：service.name、deployment.environment.name、 k8s.cluster.name）。
5. 分区：将面板分组为概览 / 延迟 / 错误 / 饱和度，或采用其他适合该领域的结构。

如果用户没有具体说明（“只要帮我为 X 做点有用的东西”），请应用下方的默认值表，并在预览中展示这些默认值。

步骤 3b-ii.2：发现名称并探测数据

适用 MCP 准则：始终优先使用资源属性筛选条件。 在编写面板之前，确认将使用的名称确实存在并且有数据：

1. 指标：调用 signoz_list_metrics，并使用与技术相关的 searchText（例如 searchText="postgresql"）获取准确的 OTel 指标名称。目录中存在指标 ≠ 数据正在流入；对于计划使用的任何指标，都要进一步调用 signoz_query_metrics，在有代表性的时间窗口内确认它确实有数据点。
2. 资源属性：针对相关信号，调用 signoz_get_field_keys 并设置 fieldContext=resource，列出可用属性；对于将用作变量的属性，调用 signoz_get_field_values，确认存在具体值。请注意，实时数据可能使用较旧的 OTel semconv（例如 deployment.environment 而非 deployment.environment.name）；始终以发现的键为准，而非默认值表中的键。

如果发现的所有信号都没有返回数据，请告知用户仪表板的数据尚未开始摄取，说明在设置好数据摄取之前，面板会显示“无数据”，并询问用户是继续构建还是停止。请等待用户选择后再开始构建。

第 3b-ii.3 步：读取仪表板 MCP 资源

这些资源是 JSON 架构、面板类型、查询构建器结构和布局规则的权威依据；不要将架构文本抄到此技能中，否则它会与服务端不同步。编写面板 JSON 之前，请先阅读核心资源。

MCP 资源读取器不可用时的备用方案 有些 MCP 客户端测试框架不提供资源读取工具。如果本次会话中无法读取 signoz://... URI，请改用 signoz_list_dashboards + signoz_get_dashboard，从具有相同信号类型（指标 / 追踪 / 日志）的现有仪表板中读取其 spec.panels 映射，以了解面板结构示例。

• signoz://dashboard/instructions：标题、标签、描述、布局、变量。
• signoz://dashboard/widgets-instructions：7 种面板类型及布局规则。
• signoz://dashboard/widgets-examples：包含所有必填字段的完整面板配置（最重要的资源；每个面板都必须包含 kind、spec.display、spec.plugin，并且只能包含一个查询）。
• signoz://dashboard/examples：组装了面板、布局和变量的完整创建请求负载。
• signoz://dashboard/query-builder-example：查询构建器参考。

根据需要添加特定信号的资源：

• 指标（PromQL）：signoz://promql/instructions。 已保存的 PromQL 可以引用已声明的仪表板 $var 变量，但 signoz_execute_builder_query 不会展开它们：仅在试运行时替换为具有代表性的字面值，已保存的面板中切勿替换。仅 Grafana 支持的 $__rate_interval / $__interval 无效。带点号的 OTel 指标名称使用 Prometheus 3.x UTF-8 选择器，例如 {"metric.name.with.dots"}。
• 指标（ClickHouse）：signoz://dashboard/clickhouse-schema-for-metrics
  • signoz://dashboard/clickhouse-metrics-example。
• 指标（查询构建器聚合规则）： signoz://metrics-aggregation-guide：选择适用于指标类型的 timeAggregation / spaceAggregation 时必须参考。
• 追踪（查询构建器）：signoz://traces/query-builder-guide。
• 日志（查询构建器）：signoz://logs/query-builder-guide。
• 追踪（ClickHouse）：signoz://dashboard/clickhouse-schema-for-traces
  • signoz://dashboard/clickhouse-traces-example。
• 日志（ClickHouse）：signoz://dashboard/clickhouse-schema-for-logs
  • signoz://dashboard/clickhouse-logs-example。

步骤 3b-ii.4：构建仪表板 JSON

遵循上述资源中记录的架构。在过滤器、groupBy 和变量中使用 OTel 语义属性名称（而非简写）。除非用户另有指定，否则应用以下默认值。

仪表板创建/更新载荷不会保存默认时间范围或刷新间隔。面板遵循查看者选择的全局范围。如果用户要求特定时间窗口，请在最终交接说明该范围，而不是自行添加 timeRange、defaultTimeRange 或 refresh 字段。不要在 Builder 查询中编码 PromQL 范围选择器。

严格使用 SigNoz 的 kind 和 JSON 类型。signoz/TimeSeriesPanel 表示时间序列（绝不能使用 Grafana 的 timeseries）；变量是携带 signoz/DynamicVariable、signoz/CustomVariable 或 signoz/QueryVariable 插件的 ListVariable / TextVariable。外层结构是 schemaVersion: "v6" 加上 spec，创建时顶层不得包含 name；服务器会从 spec.display.name 派生出不可变的机器标签。标签采用 {key, value} 对象；具体结构请参考资源。

保持面板 ID 与网格项一一对应；添加或移除时，两处都要同时处理。spec.panels 是一个以面板 ID 为键的映射，spec.layouts 则通过 content.$ref 定位这些 ID。在导入或重建时，删除任何 $ref 指向未保留面板的网格项。

该技能应用的默认值（并会在预览中显示）：

字段	默认值	何时覆盖
分区结构（APM/服务）	Overview / Latency / Errors / Throughput	使用特定领域结构（例如，DB：Overview / Connections / Throughput / Slow Queries）
分区结构（基础设施/运行时）	Overview / Saturation / Errors / Latency	使用特定领域结构
核心面板（服务）	请求速率、错误速率、p50/p95/p99 延迟、吞吐量	省略不适用的项目
核心面板（基础设施）	资源利用率（CPU、内存）、饱和度、错误/重启计数、吞吐量	根据技术类型调整
计数器显示单位（速率或计数）	每秒速率	对任何低频/突发/由人工操作驱动的计数器（请求、错误计数、重启、OOM 终止）使用较长时间窗口（24h–7d）内每个时间段的 increase 计数，适用于 /sec 显示为极小小数（例如 0.03/s）的情况；gauge（CPU/内存/队列深度）本身已是绝对值，不受影响；注意，increase 会随所选范围缩放 y 轴，因此应有意识地使用，而非习惯性使用
变量（服务）	service.name、deployment.environment（或 deployment.environment.name；使用 signoz_get_field_keys 验证哪个字段存在）	如果采用 k8s 风格，则添加 k8s.cluster.name / k8s.namespace.name
变量（k8s/基础设施）	k8s.cluster.name、k8s.namespace.name（或 hostmetrics 的 host.name）	删除 service.name；该字段在基础设施信号中很少填充
布局	2 列网格（width: 6），总宽 12 列；每个项目满足 0 <= x < 12、1 <= width <= 12、x + width <= 12	对表格和包含许多序列的时间序列使用全宽（x: 0, width: 12）
按服务面板分组	service.name 资源属性	如果筛选条件限定为单个服务，则删除

分区 一个分区是 spec.layouts 中的一个 Grid 条目，拥有自己的 spec.display.title 和 spec.items。每个分区对应一个 Grid，并按显示顺序排列；面板通过将网格项放入该 Grid 中归属相应分区。项目坐标以各自的 Grid 为准，因此在较早的分区中添加内容不会影响后续分区。

标题和描述 仪表板标题（spec.display.name）应清楚说明技术和范围：“PostgreSQL - prod-us-east-1”，而非仅写“PostgreSQL”。spec.display.description 应用一句话回答“这是做什么用的”。标签采用 {key, value}：技术类型 + 信号类型 + 已知时的环境。

步骤 3b-ii.5：保存前检查结构

signoz://dashboard/widgets-examples 是面板必填字段、特定面板类型的结构、插件 kind 名称以及常见写入结构错误的权威来源。序列化任何自定义面板 JSON 前，都要重新快速浏览一遍。

每个构建器查询和公式条目都必须带有正数 limit 和非空 order。原始列表和跟踪请求面板默认使用 100，并按时间戳降序排序（原始日志还会添加 id）；有意缩小列表页时可以降低 limit。聚合面板使用 100，并按主要聚合字段降序排序。公式输出使用 100 和 __result desc；每个被引用的基础查询使用 10000，因为基础查询的限制会在公式求值之前生效。检查每个公式表达式中的输入，包括 disabled: true 的公式，沿着引用逐层查找，直到找到所有 builder_query 基础叶节点。此依赖遍历仅用于确定限制，不会确定公式之间的确定性求值顺序，因此要对完整的复合载荷进行试运行。指标 order 键必须是组合表达式 spaceAggregation(timeAggregation(metricName))；裸指标名称会被拒绝，而 __result 和 groupBy 键可用。时间序列 Top-N 会按整个时间窗口对分组进行排序，因此可能会遗漏短暂的局部峰值。如果公式输入的基数可能超过 10000，应缩小过滤条件或分组范围。

widgets-examples 未提及但 signoz_create_dashboard 会强制执行的两条规则：不得对数组或对象使用 JSON.stringify（spec、panels、layouts、tags 和 variables 都是原生 JSON），并且每个面板只能有一个查询，因此，绘制两条序列的面板必须在一个 signoz/CompositeQuery 封装中包含两者。

步骤 3b-ii.6：保存前试运行（必须）

对于每个包含查询的面板，请遵循 signoz://dashboard/widgets-instructions 中的“试运行面板查询”说明。 面板已存储执行规范，因此应将其提取到外层封装中，并使用该载荷调用 signoz_execute_builder_query，绝不能传入面板 JSON。 使用较短的绝对 Unix 毫秒时间窗口进行试运行（通常为最近 30–60 分钟），切勿直接沿用面板的显示范围；在扩大范围或重试前，先遵循该节对空结果和超时的处理规则。在试运行副本中使用有代表性的变量值，并在 signoz_create_dashboard 中保留 $var。

如果执行器无法表示已保存的字段，应将面板报告为未经验证，并且只有在用户明确接受后才能继续。服务器或验证错误会阻止继续。意外的空结果也会阻止继续，除非用户已接受遥测数据缺失的情况。

步骤 3b-ii.7：预览、保存、报告

1. 预览 用一段通俗易懂的文字概述将要创建的内容；不要转储 JSON。包含 20–30 个面板的载荷会有数百行，用户在聊天中无法有效审阅。说明用户明确接受的任何验证缺口。

   摘要：此仪表板跟踪 [范围] 的 [信号]，包含 [列表] 部分。变量：[列表]。 试运行：[N] 个面板通过。未经验证：[无／已接受的缺口]。 数据：[已确认／根据用户明确选择等待摄取]。

2. 保存 使用该载荷调用 signoz_create_dashboard。

3. 报告 告知用户：

   • 已创建仪表板的 id 和标题。
   • 面板数量和各部分的分布。
   • 已接入的变量。
   • 提供以下两项后续操作：“要我调整面板、布局或变量吗？”以及“要我为这些信号中的任何一个接入告警吗？（signoz-creating-alerts）”。

防护措施

• 严格要求输入，避免猜测 自定义构建必须指定资源范围。如果缺少，请停止并询问用户（参见上文的 必需输入）。在共享仪表板上猜测范围，比先询问更难收拾。
• 始终对 signoz_list_dashboards 分页 停留在第 1 页会漏掉重复项，并造成杂乱。
• 先检查重复项 用户一开始只有两个选项：“修改现有仪表板”或“创建新仪表板”；绝不要把导入模板作为单独的顶层选项。
• 创建路径优先使用模板 用户选择创建后，务必先运行 signoz_list_dashboard_templates，再调用 signoz_create_dashboard。如果存在匹配的模板，通过 signoz_import_dashboard 导入（只需告知用户）；仅在没有匹配模板时才从头构建。
• 保存前必须探测是否有数据 在调用 signoz_import_dashboard / signoz_create_dashboard 前，运行预检探测（步骤 3b-i.1 / 3b-ii.2）。“无数据”仪表板的结果比多一次确认提示更糟。仅当用户明确选择本次跳过时才跳过。
• 保存前验证自定义构建 遵循步骤 3b-ii.6；绝不能将遗漏活动查询语义的试运行视为已验证。
• 自定义构建保存前先预览 在调用 signoz_create_dashboard 前，先用通俗语言给出摘要，让用户可以介入并确认意图。
• 优先使用 OTel 属性名称 使用 service.name，而非 service；使用 host.name，而非 host。名称错误会导致面板为空。请通过 signoz_get_field_keys 核对确切的键（例如 deployment.environment 与 deployment.environment.name），不要猜测；运行经典 OTel semconv 的安装会输出不带 .name 的形式。
• 不要猜测指标 对于自定义构建，编写前通过 signoz_list_metrics 验证指标名称。名称错误会导致面板为空，而用户之后才会发现。
• 只使用有效的 JSON 结构 遵循 signoz://dashboard/* MCP 资源中记录的架构。必需的面板和查询字段见 signoz://dashboard/widgets-instructions 和 signoz://dashboard/widgets-examples。绝不要用 JSON.stringify 包装数组/对象；请遵循步骤 3b-ii.4，确保面板与网格项一一对应、字段类型正确且插件类型有效。
• 范围边界 此技能用于创建仪表板。用户一旦要求修改、编辑、重新排列或扩展现有仪表板（包括刚导入后），就应转交给 signoz-modifying-dashboards。不要在此技能中调用 signoz_update_dashboard 或 signoz_patch_dashboard。

示例

四种标准流程（模板顺利创建、选择模板、发现重复项、自定义构建）见 references/examples.md。