Back to Details

perses-dashboard-create

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Perses Dashboard Create

Perses 仪表盘创建

Guided workflow for creating Perses dashboards with validation and deployment.
带验证与部署功能的Perses仪表盘创建引导式工作流。

Operator Context

技能操作上下文

This skill operates as a guided workflow for Perses dashboard creation, from requirements gathering through validation and deployment.
本技能作为Perses仪表盘创建的引导式工作流，覆盖从需求收集到验证和部署的全流程。

Hardcoded Behaviors (Always Apply)

硬编码行为（始终生效）

  • Validate before deploy: Always run 
    percli lint
    on generated dashboard definitions before applying
  • MCP-first: Use Perses MCP tools when available, percli CLI as fallback
  • Scope-aware: Ask which project the dashboard belongs to. Create the project first if it doesn't exist
  • Plugin-aware: Only use panel/query/variable plugin kinds from the official 27 plugins
  • 部署前验证：在应用生成的仪表盘定义前，始终运行
    percli lint
  • 优先使用MCP：若有可用的Perses MCP工具则使用，否则回退到percli CLI
  • 感知项目范围：询问仪表盘所属的项目。若项目不存在则先创建
  • 感知插件：仅使用官方27种插件中的面板/查询/变量插件类型

Default Behaviors (ON unless disabled)

默认行为（默认开启，可关闭）

  • CUE output: Generate CUE definitions by default (can switch to JSON/YAML if requested)
  • Prometheus datasource: Default to Prometheus datasource if no datasource type specified
  • Grid layout: Use Grid layout with collapsible rows by default
  • Variable templating: Add common variables (job, instance, namespace) based on query patterns
  • CUE输出：默认生成CUE定义（可根据需求切换为JSON/YAML）
  • Prometheus数据源：若未指定数据源类型，默认使用Prometheus
  • 网格布局：默认使用带可折叠行的Grid布局
  • 变量模板：根据查询模式添加通用变量（job、instance、namespace）

Optional Behaviors (OFF unless enabled)

可选行为（默认关闭，需开启）

  • Go SDK output: Generate Go SDK code instead of CUE
  • Ephemeral mode: Create EphemeralDashboard with TTL for preview/CI
  • Bulk creation: Generate multiple dashboards from a specification
  • Go SDK输出：生成Go SDK代码而非CUE定义
  • 临时模式：创建带TTL的EphemeralDashboard用于预览/CI
  • 批量创建：根据规范生成多个仪表盘

What This Skill CAN Do

本技能可实现的功能

  • Create complete dashboard definitions in CUE, Go, JSON, or YAML format
  • Configure datasources (Prometheus, Tempo, Loki, Pyroscope, ClickHouse, VictoriaLogs)
  • Set up variables with proper chains and interpolation formats
  • Validate definitions with percli lint
  • Deploy to Perses via percli apply or MCP tools
  • Generate CI/CD config for Dashboard-as-Code workflows
  • 生成CUE、Go、JSON或YAML格式的完整仪表盘定义
  • 配置数据源（Prometheus、Tempo、Loki、Pyroscope、ClickHouse、VictoriaLogs）
  • 设置带有正确链和插值格式的变量
  • 使用percli lint验证定义
  • 通过percli apply或MCP工具部署到Perses
  • 为Dashboard-as-Code工作流生成CI/CD配置

What This Skill CANNOT Do

本技能无法实现的功能

  • Migrate Grafana dashboards (use perses-grafana-migrate)
  • Create custom panel plugins (use perses-plugin-create)
  • Deploy/configure Perses server itself (use perses-deploy)
  • 迁移Grafana仪表盘（请使用perses-grafana-migrate）
  • 创建自定义面板插件（请使用perses-plugin-create）
  • 部署/配置Perses服务器本身（请使用perses-deploy）

Instructions

操作步骤

Phase 1: GATHER Requirements

阶段1：收集需求

Goal: Understand what the dashboard should display.
  1. Identify metrics/data: What should the dashboard show? (CPU, memory, request rates, traces, logs)
  2. Identify datasource: Which backend? (Prometheus, Tempo, Loki, Pyroscope, ClickHouse, VictoriaLogs)
  3. Identify project: Which Perses project does this belong to?
  4. Identify layout: How many panels? How should they be organized?
  5. Identify variables: What filters should be available? (cluster, namespace, pod, job, instance)
If the user provides minimal info, make reasonable defaults:
  • Default datasource: Prometheus
  • Default variables: job, instance
  • Default layout: Grid with collapsible rows, 12-column width
  • Default panels: TimeSeriesChart for time series, StatChart for single values, Table for lists
Gate: Requirements gathered. Proceed to Phase 2.
目标：明确仪表盘需要展示的内容。
  1. 确定指标/数据：仪表盘需要展示什么内容？（CPU、内存、请求速率、链路追踪、日志）
  2. 确定数据源：使用哪个后端？（Prometheus、Tempo、Loki、Pyroscope、ClickHouse、VictoriaLogs）
  3. 确定项目：该仪表盘属于哪个Perses项目？
  4. 确定布局：需要多少个面板？如何组织这些面板？
  5. 确定变量：需要提供哪些筛选器？（集群、命名空间、Pod、job、instance）
若用户提供的信息有限，使用以下合理默认值：
  • 默认数据源：Prometheus
  • 默认变量：job、instance
  • 默认布局：带可折叠行的Grid布局，12列宽度
  • 默认面板：时间序列使用TimeSeriesChart，单值使用StatChart，列表使用Table
检查点：需求已收集完成，进入阶段2。

Phase 2: GENERATE Definition

阶段2：生成定义

Goal: Create the dashboard definition.
Step 1: Check for Perses MCP tools
Use ToolSearch("perses") to discover available MCP tools.
If perses_list_projects is available, use it to verify the target project exists.
If not, use percli get project to check.
Step 2: Generate dashboard definition
Generate a CUE definition by default. The structure follows:
yaml
kind: Dashboard
metadata:
  name: <dashboard-name>
  project: <project-name>
spec:
  display:
    name: <Display Name>
    description: <description>
  duration: 1h
  refreshInterval: 30s
  datasources:
    <name>:
      default: true
      plugin:
        kind: PrometheusDatasource
        spec:
          proxy:
            kind: HTTPProxy
            spec:
              url: <prometheus-url>
  variables:
    - kind: ListVariable
      spec:
        name: <var-name>
        display:
          name: <display-name>
        plugin:
          kind: PrometheusLabelValuesVariable
          spec:
            labelName: <label>
            datasource:
              kind: PrometheusDatasource
              name: <ds-name>
  panels:
    <panel-id>:
      kind: Panel
      spec:
        display:
          name: <Panel Title>
        plugin:
          kind: TimeSeriesChart
          spec: {}
        queries:
          - kind: TimeSeriesQuery
            spec:
              plugin:
                kind: PrometheusTimeSeriesQuery
                spec:
                  query: <promql-query>
  layouts:
    - kind: Grid
      spec:
        display:
          title: <Row Title>
          collapse:
            open: true
        items:
          - x: 0
            "y": 0
            width: 12
            height: 6
            content:
              "$ref": "#/spec/panels/<panel-id>"
Available panel plugin kinds: TimeSeriesChart, BarChart, GaugeChart, HeatmapChart, HistogramChart, PieChart, ScatterChart, StatChart, StatusHistoryChart, FlameChart, Table, TimeSeriesTable, LogsTable, TraceTable, Markdown, TracingGanttChart
Available variable plugin kinds: PrometheusLabelValuesVariable, PrometheusPromQLVariable, StaticListVariable, DatasourceVariable
Variable interpolation formats: 
$var
or 
${var:format}
where format is one of: csv, json, regex, pipe, glob, lucene, values, singlevariablevalue, doublequote, singlequote, raw
Gate: Definition generated. Proceed to Phase 3.
目标：生成仪表盘定义。
步骤1：检查Perses MCP工具
Use ToolSearch("perses") to discover available MCP tools.
If perses_list_projects is available, use it to verify the target project exists.
If not, use percli get project to check.
步骤2：生成仪表盘定义
默认生成CUE定义，结构如下：
yaml
kind: Dashboard
metadata:
  name: <dashboard-name>
  project: <project-name>
spec:
  display:
    name: <Display Name>
    description: <description>
  duration: 1h
  refreshInterval: 30s
  datasources:
    <name>:
      default: true
      plugin:
        kind: PrometheusDatasource
        spec:
          proxy:
            kind: HTTPProxy
            spec:
              url: <prometheus-url>
  variables:
    - kind: ListVariable
      spec:
        name: <var-name>
        display:
          name: <display-name>
        plugin:
          kind: PrometheusLabelValuesVariable
          spec:
            labelName: <label>
            datasource:
              kind: PrometheusDatasource
              name: <ds-name>
  panels:
    <panel-id>:
      kind: Panel
      spec:
        display:
          name: <Panel Title>
        plugin:
          kind: TimeSeriesChart
          spec: {}
        queries:
          - kind: TimeSeriesQuery
            spec:
              plugin:
                kind: PrometheusTimeSeriesQuery
                spec:
                  query: <promql-query>
  layouts:
    - kind: Grid
      spec:
        display:
          title: <Row Title>
          collapse:
            open: true
        items:
          - x: 0
            "y": 0
            width: 12
            height: 6
            content:
              "$ref": "#/spec/panels/<panel-id>"
可用面板插件类型：TimeSeriesChart、BarChart、GaugeChart、HeatmapChart、HistogramChart、PieChart、ScatterChart、StatChart、StatusHistoryChart、FlameChart、Table、TimeSeriesTable、LogsTable、TraceTable、Markdown、TracingGanttChart
可用变量插件类型：PrometheusLabelValuesVariable、PrometheusPromQLVariable、StaticListVariable、DatasourceVariable
变量插值格式：
$var
或 
${var:format}
，其中format可选值包括：csv、json、regex、pipe、glob、lucene、values、singlevariablevalue、doublequote、singlequote、raw
检查点：定义已生成，进入阶段3。

Phase 3: VALIDATE

阶段3：验证

Goal: Ensure the dashboard definition is valid.
Run validation:
bash
percli lint -f <file>
目标：确保仪表盘定义有效。
运行验证：
bash
percli lint -f <file>

OR with online validation against running server:

OR with online validation against running server:

percli lint -f <file> --online

If validation fails, fix the issues and re-validate.

**Gate**: Validation passes. Proceed to Phase 4.
percli lint -f <file> --online

若验证失败，修复问题后重新验证。

**检查点**：验证通过，进入阶段4。

Phase 4: DEPLOY

阶段4：部署

Goal: Deploy the dashboard to Perses.
Option A: MCP tools (preferred if available) Use 
perses_create_dashboard
MCP tool to create the dashboard directly.
Option B: percli CLI
bash
percli apply -f <file>
Option C: Dashboard-as-Code (if DaC workflow is requested)
bash
percli dac build -f <file> -ojson
percli apply -f built/<dashboard>.json
Verify deployment:
bash
percli describe dashboard <name> --project <project>
目标：将仪表盘部署到Perses。
选项A：MCP工具（若可用则优先使用） 使用
perses_create_dashboard
MCP工具直接创建仪表盘。
选项B：percli CLI
bash
percli apply -f <file>
选项C：Dashboard-as-Code（若要求使用DaC工作流）
bash
percli dac build -f <file> -ojson
percli apply -f built/<dashboard>.json
验证部署：
bash
percli describe dashboard <name> --project <project>

OR via MCP:

OR via MCP:

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

**Gate**: Dashboard deployed and verified. Task complete.
perses_get_dashboard_by_name(project=<project>, dashboard=<name>)

**检查点**：仪表盘已部署并验证，任务完成。