Dashboards como código con Perses: ¿una alternativa a Grafana?

Dashboards como código con Perses: SDK de CUE y Go, percli, migración desde Grafana, operador de Kubernetes, licencia Apache 2.0 y sus límites.
Tableaux de bord as code avec Perses : une alternative à Grafana ?

Termina un incidente y alguien corrige «solo un panel» desde la interfaz. Tres meses después nadie sabe por qué el dashboard de producción no se parece al de preproducción. Los dashboards como código atacan esa deriva: la definición vive en Git, se revisa en una pull request y se despliega desde un pipeline. Perses, un proyecto de la CNCF, hace de esto su argumento principal.

Este artículo parte de una decisión operativa: ¿merece la pena cambiar de herramienta de visualización por esto? Los datos salen del repositorio perses/perses (README, VERSION, CHANGELOG y carpeta docs/), leído el 11 de noviembre de 2026, y del repositorio grafana/grafana para la licencia. No he instalado Perses para escribirlo: las capturas reproducen fragmentos reales de la documentación del proyecto.

El blog es independiente. Aquí no compara estas herramientas con Dynatrace, y cada función de Dynatrace que aparece en otras páginas del sitio remite a docs.dynatrace.com.

Qué es Perses y qué no es

  • Una herramienta de dashboards: el README la define «ante todo» así. Lee métricas de Prometheus, trazas de Tempo, logs de Loki y profiling de Pyroscope, y más fuentes mediante plugins.
  • Licencia y gobierno: Apache 2.0 (archivo LICENSE) y proyecto «sandbox» de la Cloud Native Computing Foundation. Grafana se distribuye con AGPL-3.0 (README de grafana/grafana), con excepciones Apache-2.0 detalladas en su LICENSING.md.
  • Versión leída: 0.55.0, publicada el 21 de octubre de 2026 según el CHANGELOG. Un 0.x avisa de que la API aún puede cambiar: esta versión rompe varias cosas (abandona React 17, exige Node 24 y elimina especificaciones antiguas).
  • No es una plataforma completa: en las páginas que leí no hay almacenamiento de métricas ni alertas. Perses muestra; tus fuentes siguen siendo Prometheus y compañía.

No anoté el número de estrellas del repositorio, porque la API de GitHub no era accesible desde mi equipo. De todos modos, la popularidad no pesa en esta decisión.

El problema de partida: la deriva entre interfaz y repositorio

Cuando la interfaz es la fuente de verdad, se repiten tres problemas. Las copias divergen entre entornos. Nadie revisa los cambios. Y corregir la misma consulta en cuarenta dashboards se come un día entero. El README de Perses presume de un enfoque «GitOps-friendly»: SDK, librerías para CI/CD, validación estática y una CLI nativa.

Su documentación justifica el código por la escala: compensa cuando mantienes muchos dashboards que deben seguir alineados. Con cinco, probablemente te baste un export JSON versionado. A partir de ahí hacen falta componentes reutilizables.

Cómo funcionan los dashboards como código con Perses

El flujo tiene tres tiempos: escribes con un SDK, generas un JSON o YAML de Perses y lo aplicas contra la API.

  1. Escribir con el SDK de CUE o el de Go. La documentación los compara: CUE valida mejor y cubre todos los plugins; Go se aprende antes y encaja mejor en código que ya tienes.
  2. Generar con percli dac build. El resultado cae en una carpeta built, en YAML por defecto o en JSON con -ojson.
  3. Validar con percli lint. Por defecto no necesita servidor; la opción --online consulta un servidor Perses para comprobar la compatibilidad con sus plugins.
  4. Desplegar con percli apply -f built/mon_tableau.json.

La documentación recomienda un dashboard por archivo y percli dac build -d mon_dossier para generarlos todos de una vez. Requisitos indicados para la 0.55.0: percli 0.55.0 como mínimo y cue 0.17.1 como mínimo para el SDK de CUE.

Fragmento de la salida de percli --help con los comandos apply, dac, lint, migrate y schema

La primera captura resume las herramientas: dac, lint, apply y migrate cubren el ciclo entero. percli login admite un token, usuario y contraseña, un proveedor OIDC o un archivo kubeconfig; según la documentación, el token de identificación caduca a la hora.

Un dashboard escrito en CUE: leer el ejemplo de la documentación

La documentación incluye un ejemplo completo. Este es el arranque: se pone nombre al dashboard, se declara el proyecto, una variable alimentada con los valores de una etiqueta de Prometheus y, por último, la fuente de datos.

Fragmento de un archivo CUE del SDK de Perses: nombre y proyecto del dashboard, variable de valores de etiqueta y fuente de datos Prometheus

Hay dos detalles que importan al operar. Primero, la fuente de datos se declara en el mismo archivo: el dashboard lleva consigo su dependencia. Segundo, los campos que empiezan por # son parámetros del constructor CUE: factorizas una vez e instancias por equipo o por entorno. Ahí baja el mantenimiento: un cambio en el componente común llega a todos los dashboards en el siguiente build.

Ojo, las consultas PromQL siguen siendo cosa tuya. Mantener nombres de métricas estables ayuda; mira nuestras notas sobre las recording rules de Prometheus y sobre la cardinalidad de las métricas en Kubernetes, que determinan lo que cuesta cada panel.

Migrar desde Grafana: lo que la herramienta promete de verdad

percli migrate convierte un dashboard de Grafana al formato de Perses. La documentación marca límites claros que conviene leer antes de prometer una migración a tu equipo:

  • solo se migran los dashboards, ni alertas ni usuarios;
  • es una migración «en la medida de lo posible»: Perses es más joven y no cubre todos los plugins de Grafana;
  • versiones de Grafana admitidas: de la 9.0.0 a la 11.x; el modelo de Grafana 12 (esquema v2, apiVersion con dashboard.grafana.app/) se rechaza, así que hay que exportar el JSON clásico;
  • el campo «Regex» de las variables no se migra.
Inicio de un dashboard Node Exporter Full migrado con percli migrate: kind Dashboard, duración 24h, variable job

Mi recomendación: migra un dashboard piloto, revisa el YAML resultante como si fuera código y compara los paneles en pantalla. Trata el resultado como un borrador, no como una conversión garantizada.

Kubernetes: el operador de Perses

Las definiciones también pueden vivir dentro del clúster. El repositorio perses/perses-operator (Apache 2.0) ofrece recursos personalizados para desplegar instancias de Perses, dashboards y fuentes de datos, con sincronización automática. Permite apuntar a una instancia con un selector y asociar un namespace a un proyecto de Perses para aislarlos. No he probado el operador: lee su guía antes de adoptarlo.

En seguridad, el CHANGELOG de la 0.55.0 corrige muchas vulnerabilidades, entre ellas críticas explotables sin autenticación con la configuración por defecto, y obliga a definir una clave de cifrado cuando la autenticación está activa. El proxy de fuentes de datos rechaza ahora por defecto las direcciones de loopback, de metadatos cloud y la API de Kubernetes. Si vas a desplegar Perses, parte de una versión actualizada y lee la página «security» de la documentación.

Perses o Grafana: una comparación honesta

  • Madurez: Grafana es más veterano y tiene un ecosistema de plugins mucho mayor. Perses reconoce que es más joven; sus 0.x y sus roturas entre versiones lo recuerdan.
  • Dashboard-as-Code: es el punto de partida de Perses, con CLI, SDK y validación integrados. Grafana también ofrece formas de gestionar sus dashboards como código; no las he revisado de nuevo para este artículo, así que no las comparo función por función.
  • Alcance: Grafana cubre más terreno. Perses se centra en visualizar.
  • Licencia: Apache 2.0 en Perses, AGPL-3.0 en Grafana. Si tu departamento legal evita la AGPL, el criterio pesa; si no, no es decisivo.
  • Coste del cambio: rehacer los dashboards y los hábitos del equipo cuesta más que la licencia. Probarlo junto a lo que ya tienes cuesta poco.

Para situar el tema en una estrategia más amplia, repasa OpenTelemetry y Prometheus y la instalación de Grafana Tempo con kube-prometheus-stack, dos piezas que un dashboard como código consulta.

Buenas prácticas

  • Un dashboard por archivo, revisado en pull request, con percli lint en la CI.
  • Un componente común por tipo de servicio, que luego se instancia.
  • Un dashboard piloto antes de cualquier lote de migración.
  • Versiones de percli y del SDK fijadas, porque el proyecto está en 0.x.
  • Ningún secreto en el repositorio: fuentes de datos y tokens se quedan en el servidor.

Preguntas frecuentes

¿Perses sustituye a Grafana?

No con el mismo alcance. Perses muestra datos que ya están almacenados; es más joven y más acotado. Encaja en un equipo cuya necesidad principal es gestionar sus dashboards desde el código.

¿Hace falta aprender CUE para usar Perses?

No. Existe el SDK de Go, y los dashboards también se crean desde la interfaz o en JSON o YAML. La documentación señala que CUE valida mejor, a cambio de una curva de aprendizaje más larga.

¿Mis dashboards de Grafana se migran sin pérdidas?

No: la documentación habla de migración en la medida de lo posible, para las versiones 9.0.0 a 11.x y solo para dashboards. Prueba antes con un caso real.

Conclusión

Los dashboards como código de Perses responden a un problema real de deriva y mantenimiento, con herramientas completas: SDK, percli, validación y operador de Kubernetes. El proyecto sigue siendo joven y su 0.55.0 sirvió sobre todo para cerrar fallos de seguridad: pruébalo junto a tu herramienta actual. Repositorio y documentación: perses/perses y perses.dev.

span.observer es un blog comunitario independiente, no afiliado a Dynatrace LLC ni a los proyectos Perses y Grafana. Las marcas citadas pertenecen a sus propietarios. Las herramientas evolucionan rápido: comprueba los comandos y las opciones en la documentación oficial.

Total
0
Shares
Leave a Reply

Your email address will not be published. Required fields are marked *

Previous Post
OpenCost Kubernetes : relier coûts et observabilité

OpenCost Kubernetes: relacionar costes y observabilidad

Next Post
OpenLIT OpenTelemetry : instrumenter une application LLM sans effort

OpenLIT OpenTelemetry: instrumenta una aplicación LLM sin esfuerzo

Related Posts