DEV Community

Cover image for Dashboards as code with Perses: an alternative to Grafana?
Span Observer
Span Observer

Posted on Originally published at span.observer

Dashboards as code with Perses: an alternative to Grafana?

An incident ends, and someone fixes « just one panel » in the UI. Three months later nobody can say why the production board differs from the staging one. Dashboards as code answers that drift: the definition lives in Git, gets reviewed like any change and ships through a pipeline. Perses, a CNCF project, makes this its headline feature.

This article starts from an operations decision: should you switch visualisation tools for that? The facts come from the perses/perses repository (README, VERSION, CHANGELOG and the docs/ folder), read on 11 November 2026, and from grafana/grafana for the licence. I did not install Perses for this piece: the screenshots reproduce real extracts from the project’s documentation.

This blog is independent. It does not compare these tools with Dynatrace here, and any Dynatrace feature mentioned elsewhere on the site points to docs.dynatrace.com.

What Perses is, and what it is not

  • A dashboard tool: the README calls it « first and foremost » a dashboard tool. It reads Prometheus metrics, Tempo traces, Loki logs and Pyroscope profiles, plus other sources through plugins.
  • Licence and governance: Apache 2.0 (LICENSE file), a Cloud Native Computing Foundation sandbox project. Grafana is distributed under AGPL-3.0 (README of grafana/grafana), with Apache-2.0 exceptions listed in its LICENSING.md.
  • Version read: 0.55.0, released on 21 October 2026 according to the CHANGELOG. A 0.x number is a reminder that the API can still move: this release breaks several things (React 17 dropped, Node 24 required, old specifications removed).
  • Not a full platform: no metric storage and no alerting in the pages I read. Perses displays; your sources stay Prometheus and friends.

I did not record the repository’s star count: the GitHub API was not reachable from my workstation. Popularity figures hardly matter for this choice anyway.

The starting problem: drift between the UI and the repository

When the UI is the source of truth, three problems keep coming back. Copies diverge between environments. Nobody reviews changes. And fixing one query across forty boards takes a day. The Perses README claims a « GitOps-friendly » approach: SDKs, CI/CD libraries, static validation and a native CLI.

Its documentation justifies code by scale: it pays off when you maintain many boards that must stay aligned. For five boards, a versioned JSON export is probably enough. Beyond that, you need reusable components.

How dashboards as code work with Perses

The principle has three steps: write in an SDK, build a Perses JSON or YAML file, then apply it to the API.

  1. Write with the CUE SDK or the Go SDK. The documentation compares them: CUE validates better and covers every plugin, while Go has a gentler learning curve and fits existing code.
  2. Build with percli dac build. The output lands in a built folder, as YAML by default or JSON with -ojson.
  3. Validate with percli lint. By default no server is needed; the --online flag asks a Perses server to check compatibility with its plugins.
  4. Deploy with percli apply -f built/my_dashboard.json.

The documentation advises one board per file and percli dac build -d my_folder to build everything at once. The prerequisites given for 0.55.0: percli 0.55.0 or later, and cue 0.17.1 or later for the CUE SDK.

Extract of the percli --help output: the apply, dac, lint, migrate and schema commands

The first screenshot sums up the tooling: dac, lint, apply and migrate cover the whole cycle. percli login accepts a token, a username and password, an OIDC provider or a kubeconfig file; per the documentation the login token expires after one hour.

A board written in CUE: reading the documentation example

The documentation offers a complete example. Here is its start: name the board, declare the project, a variable fed by the values of a Prometheus label, then the data source.

Extract of a CUE file using the Perses SDK: board name and project, a label-values variable, a Prometheus data source

Two details matter for operations. First, the data source is declared in the same file, so the board carries its dependency. Second, fields starting with # are parameters of the CUE builder: you factor once, then instantiate per team or environment. That is where maintenance cost drops: a change in the shared component reaches every board at the next build.

Note that the PromQL queries remain your job. Stable metric names help: see our advice on Prometheus recording rules and on Kubernetes metric cardinality, which drive the cost of each panel.

Migrating from Grafana: what the tool really promises

percli migrate translates a Grafana board into the Perses format. The documentation sets clear limits, worth reading before you promise a migration to your team:

  • only dashboards are migrated, not alerts or users;
  • migration is best effort: Perses is younger and does not cover every Grafana plugin;
  • supported Grafana versions: 9.0.0 to 11.x; the Grafana 12 model (v2 schema, apiVersion starting with dashboard.grafana.app/) is rejected, so export the classic JSON;
  • the « Regex » field of variables is not migrated.

Start of a Node Exporter Full dashboard migrated by percli migrate: kind Dashboard, 24h duration, job variable

My advice: migrate one pilot board, review the resulting YAML like code, then compare the panels on screen. Treat the output as a draft, not a guaranteed conversion.

Kubernetes: the Perses operator

Definitions can also live in the cluster. The perses/perses-operator repository (Apache 2.0) provides custom resources to deploy Perses instances, dashboards and data sources, with automatic synchronisation. It can target an instance through a selector and map a namespace to a Perses project for isolation. I have not tested the operator: read its guide before adopting it.

On security, the 0.55.0 CHANGELOG fixes many vulnerabilities, including critical ones exploitable without authentication under the default configuration, and requires an encryption key when authentication is on. The datasource proxy now denies loopback, cloud metadata and Kubernetes API addresses by default. If you deploy Perses, start from an up-to-date version and read the « security » page of the documentation.

Perses or Grafana: an honest comparison

  • Maturity: Grafana is older, with a larger plugin ecosystem. Perses admits to being younger; its 0.x versions and breaking releases show it.
  • Dashboard-as-Code: it is where Perses starts, with CLI, SDKs and validation built in. Grafana also offers ways to manage boards as code; I did not recheck them for this article, so I do not compare them feature by feature.
  • Scope: Grafana covers more ground. Perses focuses on display.
  • Licence: Apache 2.0 for Perses, AGPL-3.0 for Grafana. If your legal team avoids the AGPL, this weighs heavily; otherwise it is not decisive.
  • Switching cost: rebuilding boards and team habits costs more than any licence. A trial next to your current setup costs little.

To place the topic in a wider strategy, read OpenTelemetry and Prometheus and the setup of Grafana Tempo with kube-prometheus-stack, two building blocks a board as code reads from.

Good practice

  • One board per file, reviewed in a pull request, with percli lint in CI.
  • One shared component per service type, instantiated afterwards.
  • A pilot board before any migration batch.
  • Pin the percli and SDK versions, since the project is 0.x.
  • No secrets in the repository: data sources and tokens stay on the server.

Frequently asked questions

Does Perses replace Grafana?

Not at equal scope. Perses displays data stored elsewhere; it is younger and narrower. It suits a team whose main need is managing boards through code.

Do I need to learn CUE to use Perses?

No. A Go SDK exists, and boards can also be created in the UI or as JSON or YAML. The documentation says CUE validates better, at the price of a longer learning curve.

Will my Grafana boards migrate without loss?

No. The documentation describes best-effort migration, for versions 9.0.0 to 11.x and dashboards only. Test a real case first.

Conclusion

Perses answers a real drift and maintenance problem with complete tooling: SDKs, percli, validation and a Kubernetes operator. The project is still young and its 0.55.0 mostly fixed security flaws: try it next to your current tool. Repository and documentation: perses/perses and perses.dev.

span.observer is an independent community blog, not affiliated with Dynatrace LLC or with the Perses and Grafana projects. Brands mentioned belong to their owners. Tools change quickly: check commands and options in the official documentation.


Originally published on span.observer. French version: https://span.observer/fr/tableaux-de-bord-as-code-perses/.

Top comments (0)