perses-dashboard-review

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Perses Dashboard Review

Perses 仪表盘审查

Analyze and improve existing Perses dashboards through structured review of layout, queries, variables, and datasource configuration.

通过对布局、查询、变量和数据源配置的结构化审查，分析并优化现有Perses仪表盘。

Operator Context

操作上下文

This skill operates as a non-destructive auditor of Perses dashboards, fetching definitions via MCP tools or percli CLI, then systematically analyzing them against quality criteria.

本技能作为Perses仪表盘的非破坏性审计工具，通过MCP工具或percli CLI获取定义，然后根据质量标准进行系统性分析。

Hardcoded Behaviors (Always Apply)

硬编码行为（始终生效）

Non-destructive by default -- never modify dashboards without explicit
```
--fix
```
flag or user confirmation
MCP-first retrieval -- attempt
```
perses_get_dashboard_by_name
```
before falling back to percli CLI
Structured findings -- every finding must have a severity (critical, warning, info) and a concrete recommendation
Full-scope analysis -- check all five review areas (layout, queries, variables, datasources, metadata) on every review
Preserve dashboard identity -- never change dashboard name, project assignment, or display metadata unless explicitly requested

默认非破坏性——除非使用明确的
```
--fix
```
标志或获得用户确认，否则绝不修改仪表盘
优先MCP获取——先尝试
```
perses_get_dashboard_by_name
```
，失败后再回退到percli CLI
结构化发现结果——每个发现结果必须包含严重级别（critical、warning、info）和具体改进建议
全范围分析——每次审查都要检查所有五个维度（布局、查询、变量、数据源、元数据）
保留仪表盘标识——除非明确要求，否则绝不修改仪表盘名称、项目分配或显示元数据

Default Behaviors (ON unless disabled)

默认行为（启用状态，可禁用）

Severity-sorted output -- report findings from critical to info
Query validation -- check PromQL/LogQL syntax and common anti-patterns (missing rate intervals, unbounded selectors)
Variable chain analysis -- trace variable dependencies and verify ordering
Layout audit -- flag orphan panels, empty rows, and width overflows

按严重级别排序输出——报告结果从critical到info排序
查询验证——检查PromQL/LogQL语法和常见反模式（缺少rate间隔、无界选择器等）
变量链分析——追踪变量依赖关系并验证顺序
布局审计——标记孤立面板、空行和宽度溢出问题

Optional Behaviors (OFF unless enabled)

可选行为（禁用状态，可启用）

Fix mode (
```
--fix
```
) -- apply recommended improvements and redeploy
Performance scoring -- assign a numeric quality score (0-100) to the dashboard
Cross-dashboard analysis -- compare variable/datasource usage across multiple dashboards in the same project

修复模式（
```
--fix
```
）——应用建议的改进并重新部署
性能评分——为仪表盘分配0-100的质量分数
跨仪表盘分析——比较同一项目中多个仪表盘的变量/数据源使用情况

What This Skill CAN Do

本技能可执行的操作

Fetch dashboard definitions via MCP tools or percli CLI
Analyze panel grid layout for organization and efficiency
Audit PromQL and LogQL queries for correctness and performance
Validate variable chains for dependency ordering and circular references
Check datasource scoping and reachability
Identify unused panels, missing descriptions, and unclear titles
Generate a structured findings report with severity levels
Apply fixes when
```
--fix
```
mode is enabled

通过MCP工具或percli CLI获取仪表盘定义
分析面板网格布局的合理性与效率
审计PromQL和LogQL查询的正确性与性能
验证变量链的依赖顺序和循环引用
检查数据源的范围和可达性
识别未使用的面板、缺失的描述和不清晰的标题
生成带有严重级别的结构化发现报告
在
```
--fix
```
模式下应用修复

What This Skill CANNOT Do

本技能不可执行的操作

Create new dashboards from scratch (use
```
perses-dashboard-create
```
)
Develop or modify Perses plugins (use
```
perses-plugin-create
```
)
Deploy or configure Perses server instances (use
```
perses-deploy
```
)
Manage Perses projects, roles, or RBAC configuration

从头创建新仪表盘（请使用
```
perses-dashboard-create
```
）
开发或修改Perses插件（请使用
```
perses-plugin-create
```
）
部署或配置Perses服务器实例（请使用
```
perses-deploy
```
）
管理Perses项目、角色或RBAC配置

Error Handling

错误处理

MCP Tools Not Available

MCP工具不可用

Symptom:

perses_get_dashboard_by_name

perses_list_dashboards

calls fail or are not registered. Action: Fall back to percli CLI. Run

percli describe dashboard <name> --project <project> -ojson

. If percli is also unavailable, ask the user to provide the dashboard JSON directly or check MCP server configuration.

症状：

perses_get_dashboard_by_name

或

perses_list_dashboards

调用失败或未注册。操作：回退到percli CLI。执行

percli describe dashboard <name> --project <project> -ojson

。如果percli也不可用，请用户直接提供仪表盘JSON或检查MCP服务器配置。

Dashboard Not Found

仪表盘未找到

Symptom: MCP or percli returns 404 or empty result for the dashboard name. Action: List available dashboards with

perses_list_dashboards(project=<project>)

percli get dashboard --project <project>

. Confirm the project name and dashboard name with the user. Dashboard names are case-sensitive and use kebab-case by convention.

症状：MCP或percli针对仪表盘名称返回404或空结果。操作：使用

perses_list_dashboards(project=<project>)

或

percli get dashboard --project <project>

列出可用仪表盘。与用户确认项目名称和仪表盘名称。仪表盘名称区分大小写，通常使用短横线分隔格式（kebab-case）。

Datasource Unreachable

数据源不可达

Symptom: Datasource referenced in panels returns connection errors, proxy failures, or auth rejections during validation. Action: Log the unreachable datasource as an info-level finding (not a dashboard quality issue). Note which panels are affected. Do not block the review -- continue analyzing query syntax and structure without live validation. Suggest the user verify network/proxy/auth configuration separately.

症状：面板引用的数据源在验证期间返回连接错误、代理失败或认证拒绝。操作：将不可达的数据源标记为info级发现结果（不属于仪表盘质量问题）。记录受影响的面板。不要中断审查——继续分析查询语法和结构，无需实时验证。建议用户单独检查网络/代理/认证配置。

Variable Chain Circular Dependency

变量链循环依赖

Symptom: Variable A depends on variable B which depends on variable A (directly or transitively). Action: Flag as a critical finding. Map the full dependency cycle and include it in the report. In

--fix

mode, propose breaking the cycle by making one variable static or removing the circular matcher. Never auto-fix circular dependencies without user confirmation.

症状：变量A依赖变量B，而变量B又依赖变量A（直接或间接）。操作：标记为critical级发现结果。绘制完整的依赖循环图并包含在报告中。在

--fix

模式下，建议通过将其中一个变量设为静态或移除循环匹配器来打破循环。未经用户确认，绝不自动修复循环依赖。

Malformed Dashboard JSON

仪表盘JSON格式错误

Symptom: Dashboard definition fails to parse or is missing required fields (

kind

metadata

spec

). Action: Report the structural error and halt analysis. Do not attempt partial review of a malformed definition -- the results would be unreliable.

症状：仪表盘定义解析失败或缺少必填字段（

kind

、

metadata

、

spec

）。操作：报告结构错误并停止分析。不要尝试对格式错误的定义进行部分审查——结果会不可靠。

Anti-Patterns

反模式

Reviewing Only Panel Queries Without Checking Layout

仅审查面板查询而忽略布局

Wrong: Jump straight to PromQL/LogQL analysis and ignore how panels are organized. Right: Always start with layout review (Phase 2, Step 1). A dashboard with correct queries but chaotic layout is still a poor dashboard. Check grid positioning, row grouping, collapsible sections, and panel widths before diving into queries.

错误做法：直接跳到PromQL/LogQL分析，忽略面板的组织方式。 正确做法：始终从布局审查开始（第2阶段第1步）。查询正确但布局混乱的仪表盘仍然是劣质仪表盘。在深入查询之前，检查网格定位、行分组、可折叠区域和面板宽度。

Not Checking Variable Dependency Ordering

不检查变量依赖顺序

Wrong: Review variables in isolation without tracing which variables feed into others. Right: Build a dependency graph of all variables. Verify that variables are defined in topological order (parents before children). Check that matchers like

$variable_name

reference variables that are already resolved. Variable

sort_order

spec.display

affects the rendered dropdown but not dependency resolution -- don't confuse the two.

错误做法：孤立地审查变量，不追踪变量之间的依赖关系。 正确做法：构建所有变量的依赖图。验证变量按拓扑顺序定义（父变量在子变量之前）。检查

$variable_name

等匹配器是否引用已解析的变量。

spec.display

中的

sort_order

仅影响渲染后的下拉菜单，不影响依赖解析——不要混淆两者。

Ignoring Datasource Scope Mismatches

忽略数据源范围不匹配

Wrong: Assume all panels can reach all datasources because they're "in the same Perses instance." Right: Datasources in Perses have explicit scope (global or project-level). A panel referencing a project-scoped datasource from another project will fail silently at render time. Verify that every panel's datasource reference resolves within the dashboard's project scope or is globally available.

错误做法：假设所有面板都能访问所有数据源，因为它们“在同一个Perses实例中”。 正确做法：Perses中的数据源有明确的范围（全局或项目级）。引用其他项目的项目级数据源的面板会在渲染时静默失败。验证每个面板的数据源引用是否在仪表盘的项目范围内可解析，或者是否为全局可用。

Treating All Findings as Equal Severity

将所有发现结果视为同一严重级别

Wrong: List every finding as a flat bullet list without distinguishing between broken queries and cosmetic suggestions. Right: Assign severity levels. Critical = dashboard is broken or produces wrong data. Warning = dashboard works but has performance or usability issues. Info = cosmetic or best-practice suggestions.

错误做法：将所有发现结果作为扁平项目列表列出，不区分查询错误和外观建议。 正确做法：分配严重级别。Critical=仪表盘损坏或返回错误数据；Warning=仪表盘可用但存在性能或可用性问题；Info=外观或最佳实践建议。

Anti-Rationalization

反合理化

Rationalization	Reality	Required Action
"The queries look correct to me"	Visual inspection misses rate interval mismatches, label collisions, and unbounded selectors	Parse and validate each query against known anti-patterns
"Variable ordering doesn't matter"	Perses evaluates variables top-to-bottom; misordered dependencies cause empty dropdowns	Build the dependency graph and verify topological order
"Only a few panels -- quick scan is enough"	Small dashboards still have datasource scoping, variable chains, and layout issues	Run the full 4-phase pipeline regardless of dashboard size
"The dashboard renders fine so it must be correct"	Rendering without errors does not mean queries return correct data or layout is optimal	Analyze query semantics and layout structure, not just render success

合理化借口	实际情况	要求操作
“我觉得查询看起来是正确的”	视觉检查会遗漏rate间隔不匹配、标签冲突和无界选择器	解析并验证每个查询，检查已知反模式
“变量顺序不重要”	Perses从上到下评估变量；顺序错误的依赖会导致下拉菜单为空	构建依赖图并验证拓扑顺序
“只有几个面板——快速扫描就够了”	小型仪表盘仍然可能存在数据源范围、变量链和布局问题	无论仪表盘大小，都要运行完整的四阶段流程
“仪表盘能正常渲染，所以肯定没问题”	无错误渲染不代表查询返回正确数据或布局最优	分析查询语义和布局结构，而不仅仅是渲染成功

FORBIDDEN Patterns

禁止模式

NEVER modify a dashboard without
```
--fix
```
mode or explicit user confirmation
NEVER delete panels, variables, or datasources during review -- only flag them as findings
NEVER skip the FETCH phase and work from stale or assumed dashboard state
NEVER report on dashboard quality without actually retrieving the current definition
NEVER auto-fix circular variable dependencies without user approval
NEVER change datasource assignments -- only report scope mismatches

绝不在未启用
```
--fix
```
模式或未获得明确用户确认的情况下修改仪表盘
绝不在审查期间删除面板、变量或数据源——仅标记为发现结果
绝不跳过FETCH阶段，使用陈旧或假设的仪表盘状态进行操作
绝不在未获取当前定义的情况下报告仪表盘质量
绝不未经用户批准自动修复变量循环依赖
绝不更改数据源分配——仅报告范围不匹配问题

Blocker Criteria

阻塞标准

The review MUST NOT proceed past the FETCH phase if:

Dashboard definition cannot be retrieved (MCP + percli both fail, no JSON provided)
Dashboard JSON is malformed and fails structural validation
Project does not exist or user lacks read permissions

The review MUST flag as critical blockers:

Circular variable dependency chains
Panels referencing non-existent datasources
Queries that fail syntactic validation (malformed PromQL/LogQL)
Grid layout with panels exceeding the 24-column width limit

如果出现以下情况，审查绝对不能超过FETCH阶段：

无法获取仪表盘定义（MCP和percli均失败，且未提供JSON）
仪表盘JSON格式错误，无法通过结构验证
项目不存在或用户缺乏读取权限

审查必须标记为critical阻塞问题的情况：

变量循环依赖链
面板引用不存在的数据源
查询语法验证失败（格式错误的PromQL/LogQL）
网格布局中面板宽度超过24列限制

Instructions

操作步骤

Phase 1: FETCH

阶段1：FETCH（获取）

Goal: Retrieve the current dashboard definition.

Attempt MCP retrieval:

perses_get_dashboard_by_name(project=<project>, dashboard=<name>)

If MCP unavailable, fall back to percli:

bash

percli describe dashboard <name> --project <project> -ojson

If both fail, ask the user to provide the dashboard JSON directly.

Parse and validate the JSON structure (

kind: Dashboard

metadata.name

spec.panels

spec.layouts

spec.variables

spec.datasources

Gate: Dashboard definition retrieved and structurally valid. Proceed to Phase 2.

目标：获取当前仪表盘定义。

尝试通过MCP获取：

perses_get_dashboard_by_name(project=<project>, dashboard=<name>)

如果MCP不可用，回退到percli：

bash

percli describe dashboard <name> --project <project> -ojson

如果两者都失败，请用户直接提供仪表盘JSON。

解析并验证JSON结构（

kind: Dashboard

、

metadata.name

、

spec.panels

、

spec.layouts

、

spec.variables

、

spec.datasources

）。

准入条件：成功获取仪表盘定义且结构有效。进入阶段2。

Phase 2: ANALYZE

阶段2：ANALYZE（分析）

Goal: Systematically audit all dashboard components.

目标：系统性审计所有仪表盘组件。

Step 1: Layout Review

步骤1：布局审查

Verify grid layout uses 24-column system correctly (no panel exceeds width 24)
Check for collapsible rows with logical grouping
Identify orphan panels (defined in
```
spec.panels
```
but absent from
```
spec.layouts
```
)
Flag empty rows or sections with no panels

验证网格布局是否正确使用24列系统（无面板宽度超过24）
检查是否有逻辑分组的可折叠行
识别孤立面板（在
```
spec.panels
```
中定义但未出现在
```
spec.layouts
```
中）
标记空行或无面板的区域

Step 2: Query Analysis

步骤2：查询分析

Parse each panel's query (PromQL, LogQL, TraceQL, or SQL depending on plugin)
Check for common anti-patterns:
- Missing
```
$__rate_interval
```
  or hardcoded rate intervals
- Unbounded label selectors (e.g.,
```
{__name__=~".+"}
```
  )
- ```
rate()
```
  without appropriate range vector
- Recording rule candidates (complex expressions used in multiple panels)
Verify query references to variables use correct interpolation format (
```
$variable
```
or
```
${variable}
```
)

解析每个面板的查询（根据插件类型，可能是PromQL、LogQL、TraceQL或SQL）
检查常见反模式：
- 缺少
```
$__rate_interval
```
  或硬编码的rate间隔
- 无界标签选择器（例如
```
{__name__=~".+"}
```
  ）
- ```
rate()
```
  未使用合适的范围向量
- 可转换为记录规则的复杂表达式（在多个面板中使用）
验证查询对变量的引用是否使用正确的插值格式（
```
$variable
```
或
```
${variable}
```
）

Step 3: Variable Chain Analysis

步骤3：变量链分析

Build dependency graph from variable definitions
Verify topological ordering (parent variables defined before children)
Check for circular dependencies
Validate
```
matchers
```
reference existing variables
Check interpolation formats are appropriate for the context:
```
csv
```
,
```
regex
```
,
```
json
```
,
```
pipe
```
,
```
glob
```
,
```
lucene
```
, etc.
Confirm
```
spec.display.name
```
and
```
spec.display.description
```
are set for user-facing variables

根据变量定义构建依赖图
验证拓扑顺序（父变量在子变量之前定义）
检查循环依赖
验证
```
matchers
```
引用的变量是否存在
检查插值格式是否符合上下文要求：
```
csv
```
、
```
regex
```
、
```
json
```
、
```
pipe
```
、
```
glob
```
、
```
lucene
```
等（通过
```
spec.display.format
```
设置）

确认面向用户的变量已设置

spec.display.name

和

spec.display.description

Step 4: Datasource Scoping

步骤4：数据源范围检查

Map each panel to its datasource reference
Verify datasource scope (global vs. project-level) matches the dashboard's project
Check for datasources referenced but not defined in the dashboard's
```
spec.datasources
```
Flag proxy configuration issues if datasource URLs are internal-only

映射每个面板对应的数据源引用
验证数据源范围（全局或项目级）与仪表盘项目匹配
检查是否存在引用但未在仪表盘
```
spec.datasources
```
中定义的数据源
如果数据源URL为内部地址，标记代理配置问题

Step 5: Metadata and Usability

步骤5：元数据与可用性

Check for missing panel titles or descriptions
Verify dashboard-level
```
spec.display
```
has a meaningful name
Flag panels with identical titles (confusing for users)
Check
```
spec.duration
```
(default time range) is set appropriately

Gate: All five analysis steps completed. Proceed to Phase 3.

检查是否缺少面板标题或描述
验证仪表盘级别的
```
spec.display
```
是否有有意义的名称
标记标题相同的面板（易造成用户混淆）
检查
```
spec.duration
```
（默认时间范围）是否设置合理

准入条件：完成所有五个分析步骤。进入阶段3。

Phase 3: REPORT

阶段3：REPORT（报告）

Goal: Generate a structured findings report.

Output format:

undefined

目标：生成结构化发现报告。

输出格式：

undefined

Dashboard Review: <name> (project: <project>)

仪表盘审查：<name>（项目：<project>）

Critical Findings

Critical 严重问题

[CRITICAL] <description> -- <recommendation>

[CRITICAL] <问题描述> -- <改进建议>

Warnings

Warnings 警告

[WARNING] <description> -- <recommendation>

[WARNING] <问题描述> -- <改进建议>

Info

Info 信息

[INFO] <description> -- <recommendation>

[INFO] <问题描述> -- <改进建议>

Summary

总结

Panels reviewed: N
Variables reviewed: N
Datasources reviewed: N
Critical: N | Warnings: N | Info: N


**Gate**: Report generated with all findings categorized. If `--fix` not requested, task complete.

已审查面板数量：N
已审查变量数量：N
已审查数据源数量：N
Critical：N | Warnings：N | Info：N


**准入条件**：生成包含所有分类发现结果的报告。如果未请求`--fix`，任务完成。

Phase 4: FIX (optional, requires --fix)

阶段4：FIX（修复，可选，需启用--fix）

Goal: Apply recommended improvements.

Present the list of proposed fixes to the user for confirmation
Apply approved fixes to the dashboard JSON

Deploy the updated dashboard:

perses_update_dashboard(project=<project>, dashboard=<name>, body=<updated_json>)
# OR
percli apply -f <updated_dashboard.json> --project <project>

Re-run Phase 2 ANALYZE on the updated dashboard to verify fixes resolved the findings

Gate: Fixes applied and verified. Task complete.

目标：应用建议的改进。

向用户展示拟修复的列表并请求确认
将已批准的修复应用到仪表盘JSON

部署更新后的仪表盘：

perses_update_dashboard(project=<project>, dashboard=<name>, body=<updated_json>)
# 或
percli apply -f <updated_dashboard.json> --project <project>

对更新后的仪表盘重新运行阶段2的ANALYZE，验证修复是否解决了问题

准入条件：修复已应用并验证。任务完成。

References

参考资料

Perses Dashboard Spec: Dashboard JSON structure, panel plugins, layout system
27 Official Plugins: TimeSeriesChart, GaugeChart, StatChart, MarkdownPanel, ScatterChart, BarChart, StatusHistoryChart, TextVariable, ListVariable, LabelNamesVariable, LabelValuesVariable, PrometheusLabelNamesVariable, PrometheusLabelValuesVariable, PrometheusPromQLVariable, StaticListVariable, PrometheusTimeSeriesQuery, PrometheusDatasource, HTTPProxy, TempoDatasource, TempoTraceQuery, LogsPanel, LokiDatasource, LokiLogsQuery, SQLDatasource, SQLQuery, and more
Variable Interpolation Formats: csv, regex, json, pipe, glob, lucene (applied via
```
spec.display.format
```
)

MCP Tools:

perses_get_dashboard_by_name

perses_list_dashboards

perses_update_dashboard

percli CLI:

percli describe dashboard

percli get dashboard

percli apply

Grid Layout: 24-column system with collapsible row support

Perses仪表盘规范：仪表盘JSON结构、面板插件、布局系统
27个官方插件：TimeSeriesChart、GaugeChart、StatChart、MarkdownPanel、ScatterChart、BarChart、StatusHistoryChart、TextVariable、ListVariable、LabelNamesVariable、LabelValuesVariable、PrometheusLabelNamesVariable、PrometheusLabelValuesVariable、PrometheusPromQLVariable、StaticListVariable、PrometheusTimeSeriesQuery、PrometheusDatasource、HTTPProxy、TempoDatasource、TempoTraceQuery、LogsPanel、LokiDatasource、LokiLogsQuery、SQLDatasource、SQLQuery等
变量插值格式：csv、regex、json、pipe、glob、lucene（通过
```
spec.display.format
```
设置）

MCP工具：

perses_get_dashboard_by_name

、

perses_list_dashboards

、

perses_update_dashboard

percli CLI：

percli describe dashboard

、

percli get dashboard

、

percli apply

网格布局：支持可折叠行的24列系统