Perses Dashboard Create

Operator Context

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

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

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

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

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)

Instructions

Phase 1: GATHER Requirements

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)

• 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

Phase 2: GENERATE Definition

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.

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>"

$var

${var:format}

Phase 3: VALIDATE

percli lint -f <file>
# OR with online validation against running server:
percli lint -f <file> --online

Phase 4: DEPLOY

perses_create_dashboard

percli apply -f <file>

percli dac build -f <file> -ojson
percli apply -f built/<dashboard>.json

percli describe dashboard <name> --project <project>
# OR via MCP:
perses_get_dashboard_by_name(project=<project>, dashboard=<name>)