Encuentra las trampas de importación antes de publicar el dashboard.

22 reglas sobre un parse real del dashboard: 7 errores, 11 advertencias y 4 notas. Los errores son los que cambian lo que hace Grafana — una variable de plantilla que nada declara, un placeholder ${DS_…} sin bloque __inputs, un panel AngularJS que no renderiza nada en Grafana 11–12, dos paneles con el mismo id, un repeat sobre una variable que no existe, un panel sin type, y una schemaVersion tan antigua que el JSON y el render son dos dashboards distintos. Las advertencias son los problemas de portabilidad y de revisión: un uid ausente, un id de base de datos dejado en un archivo commiteado, una datasource referenciada por nombre, un panel graph o singlestat obsoleto, un panel invisible de ancho cero, un rango de tiempo por defecto de más de un año, un refresh por debajo de diez segundos. Cada regla tiene su propia subsección en esta página, y los chips de regla del playground enlazan directamente ahí.

No. El parser y todas las reglas son JavaScript ejecutándose en tu pestaña — no hay servidor, ni llamada a una API, ni registro, así que se suben 0 bytes. Aquí importa más que en la mayoría de las herramientas: el JSON de un dashboard es un mapa de tu infraestructura interna. Nombres de métricas, uids de datasources, hostnames en formatos de leyenda, nombres de servicio en queries de variables, a veces una URL interna en un enlace de panel. Es exactamente el archivo que no deberías pegar en un formateador online cualquiera.

No, y lo dice en lugar de insinuar lo contrario. El esquema de dashboards de Grafana es grande, versionado y sigue moviéndose, así que una comprobación parcial presentada como comprobación de esquema sería peor que no comprobar nada. Lo que hace es un lint estructural: lee las formas que rompen importaciones y revisiones — variables, referencias a datasources, tipos de panel, ids, layout, tiempo y refresh — y nombra el path JSON de cada hallazgo. No parsea PromQL, no conoce tus plugins y no habla con ningún Grafana. La lista completa de lo que calla a propósito está arriba, en «Lo que no señala a propósito».

Porque el archivo lo produjo «Export for sharing externally». Esa exportación reemplaza cada referencia a datasource por un placeholder — ${DS_PROMETHEUS} — y añade un bloque «__inputs» que describe qué necesita cada uno. Solo el diálogo Dashboards → Import lee ese bloque y te pide elegir una datasource real. Provisionar el mismo archivo, hacerle POST a la API o dejarlo en una carpeta sincronizada con Git salta el diálogo por completo: el placeholder sobrevive al dashboard guardado y todos los paneles fallan al resolverlo. O lo importas por el diálogo, o sustituyes la { type, uid } real antes de provisionarlo. Este linter reporta el placeholder como error en ambos casos, porque el archivo no se puede provisionar tal cual.

El uid es el identificador que eliges tú. Forma parte de la URL del dashboard, es lo que direccionan el provisioning y la API, y debe vivir en control de versiones junto al JSON. El id es un número de fila en la base de datos de una instancia concreta de Grafana: fuera de ella no significa nada. Un archivo con uid actualiza el mismo dashboard en cada importación; uno sin él crea una copia nueva cada vez. Un archivo con un id obsoleto o falla al importar o apunta a un dashboard que no tiene nada que ver con el tuyo, y por eso una exportación debería llevar «id»: null.

Los paneles del núcleo graph, singlestat y table-old se migran automáticamente al cargar el dashboard, así que siguen funcionando — pero el JSON de tu repositorio no se migra, lo que significa que el archivo que revisas y el panel que Grafana renderiza son dos cosas distintas. Vuelve a guardar el dashboard desde Grafana 9 o posterior para escribir la migración en el archivo. Los PLUGINS de panel AngularJS son otra historia: grafana-piechart-panel, grafana-worldmap-panel y los demás no tienen migración automática, y el soporte de Angular quedó obsoleto en Grafana 9 y se eliminó a lo largo de Grafana 11–12, así que esos paneles no renderizan nada y hay que reemplazarlos a mano.

El conjunto de reglas está fijado a grafana-12 / schemaVersion 41, impreso en esta página y en cada informe copiado para que nunca haya ambigüedad sobre qué lo comprobó. Las reglas sensibles a la versión se expresan como rangos — «Grafana 9–12», «eliminado a lo largo de Grafana 11–12» — en lugar de como un release exacto, porque tu instancia está cerca de este punto y no exactamente en él. Si la schemaVersion de tu dashboard es mayor que 41, recibes una NOTA que lo dice y los hallazgos específicos del esquema quedan marcados como orientativos. Un esquema desconocido es un límite de este linter, no un defecto de tu dashboard, así que nunca se reporta como error.

Porque Grafana no falla: no interpola nada y ejecuta la query con el texto literal dentro. Un selector PromQL {env="$env"} no coincide con ninguna serie, así que el panel queda vacío; un selector con coincidencia por regex puede coincidir con MUCHAS más series de las que querías, así que el panel queda lleno y equivocado. Ninguno de los dos casos produce un mensaje en ninguna parte de la interfaz. La única excepción que hace este linter es una referencia dentro de un string que parece una expresión regular, donde «$» también es un ancla de fin de línea: ahí el hallazgo baja a advertencia, porque ese «$env» que escribiste pudo ser realmente un ancla seguida de texto.

Hasta 5.000.000 caracteres, lo que cubre un dashboard generado de varios miles de paneles; uno de 500 paneles se analiza en unos pocos milisegundos. Por encima de ese límite se niega con un mensaje en lugar de congelarte la pestaña, porque una entrada tan grande es un log o un archivo comprimido, no un dashboard. Los hallazgos también están limitados: 50 por regla y 400 en total, y el panel indica el límite y el número real cada vez que uno se aplica — una lista truncada que no dijera que está truncada sería exactamente el tipo de error silencioso que esta herramienta existe para cazar.