Dashboards & Panels
Relevant source files
The following files were used as context for generating this wiki page:
- apps/dashboard/pkg/migration/README.md
- apps/dashboard/pkg/migration/schemaversion/README.md
- apps/dashvalidator/pkg/generated/manifestdata/dashvalidator_manifest.go
- public/app/features/provisioning/components/Dashboards/SaveProvisionedDashboardForm.test.tsx
- packages/grafana-runtime/src/services/pluginMeta/test-fixtures/v0alpha1Response.ts
- contribute/style-guides/frontend.md
Dashboards are the primary architectural unit for data visualization within Grafana, serving as containers for organized collections of Panels. A Dashboard defines the layout, variables (templating), time ranges, and metadata required to contextualize data visualizations. Panels are the individual building blocks within a dashboard, each responsible for executing queries against data sources and rendering the results through specific visualization plugins (e.g., Time series, Bar chart, Table).
The system maintains a complex versioning and migration strategy to ensure backward compatibility as the underlying data model evolves. This involves multiple API versions (ranging from legacy v0alpha1 to structured v2beta1) and sequential schema versions (currently up to v42).
Sources: apps/dashboard/pkg/migration/README.md:10-25, apps/dashboard/pkg/migration/schemaversion/README.md:20-30
Dashboard Data Model & API Versions
Grafana utilizes a multi-tiered API versioning system for dashboards to transition from legacy JSON blobs to modern, structured formats.
API Versioning Matrix
| API Version | Format Type | Description |
|---|---|---|
v0alpha1 | Legacy JSON | Original unstructured dashboard format used in older Grafana versions. |
v1beta1 | Migrated JSON | Intermediate format representing dashboards that have passed through schema migrations. |
v2alpha1 / v2beta1 | Structured | Modern, typed schema designed for Kubernetes-native storage and stable type definitions. |
Sources: apps/dashboard/pkg/migration/README.md:28-40, apps/dashvalidator/pkg/generated/manifestdata/dashvalidator_manifest.go:88-92
Dashboard Structure
A dashboard object consists of several high-level components defined in the spec:
- Metadata: Includes
uid,name,namespace, and annotations likefolderUid. - Panels: An array of visualization objects. v1 dashboards use a "panels" array, while v2 transitions toward structured "elements".
- Templating: Variables used for dynamic dashboard filtering.
- Annotations & Links: Global dashboard-level event overlays and navigation links.
Sources: apps/dashvalidator/pkg/generated/manifestdata/dashvalidator_manifest.go:88-95, public/app/features/provisioning/components/Dashboards/SaveProvisionedDashboardForm.test.tsx:103-120
Migration Architecture
The migration system ensures that older dashboard formats can be upgraded to work with current Grafana releases through a sequential conversion pipeline.
Conversion Flow
The conversion process follows a strict chain: v0alpha1 (Legacy) → v1beta1 (Migrated) → v2beta1 (Structured).
The diagram shows the standard flow from legacy formats to structured v2 formats, as well as the capability to convert back for compatibility.
Sources: apps/dashboard/pkg/migration/README.md:14-25
Schema Version Migrations (v13 - v42)
Schema versions are specific to v0 and v1 dashboards. Each migration transforms properties from one version to the next (e.g., v14 → v15).
- Backend Location:
apps/dashboard/pkg/migration/schemaversion/ - Frontend Location:
public/app/features/dashboard/state/DashboardMigrator.ts - Finality: Schema version 42 is designated as the final version for the v1 dashboard API.
Sources: apps/dashboard/pkg/migration/schemaversion/README.md:21-27, apps/dashboard/pkg/migration/schemaversion/README.md:215-220
Panels & Visualization Components
Panels are the functional units of a dashboard. They are defined by a type (referencing a plugin ID) and specific targets (queries).
Angular Panel Migrations
Legacy panels built on the Angular framework require specialized handling during the v1 to v2 conversion. The system uses a temporary data field called __angularMigration to preserve original panel data.
- Detection: The backend identifies panels with an
autoMigrateFromfield or known Angular types. - Preservation: The original panel configuration is stored in
vizConfig.spec.options.__angularMigration. - Frontend Execution: When the dashboard is loaded in the browser, the frontend extracts this data and triggers the plugin's
onPanelTypeChanged()logic to map old options to modern field configurations.
Sources: apps/dashboard/pkg/migration/README.md:61-100
This sequence illustrates how legacy panel data is passed through the structured API to be modernized by the specific plugin in the frontend.
Sources: apps/dashboard/pkg/migration/README.md:85-98
Monitoring and Validation
The migration system includes automated checks to prevent regressions or data loss during format conversions.
Data Loss Detection
Every conversion executes runtime checks to compare counts of essential components between the source and target. If any count decreases, a conversion_data_loss_error is triggered.
| Component | Description |
|---|---|
| Panel Count | Total visualization panels and library panels. |
| Query Count | Total data source queries (refIds A, B, C, etc.). |
| Annotations | Dashboard-level annotation overlays. |
| Links | Navigation and drill-down links. |
| Variables | Templating variables defined in the dashboard. |
Sources: apps/dashboard/pkg/migration/README.md:255-275
Metrics and Logging
Conversion operations are instrumented with Prometheus metrics to track health:
grafana_dashboard_migration_conversion_success_total: Incremented on successful version upgrades.grafana_dashboard_migration_conversion_failure_total: Labeled byerror_type(e.g.,schema_version_migration_error,conversion_data_loss_error).
Sources: apps/dashboard/pkg/migration/README.md:183-210
Summary
Dashboards and Panels in Grafana represent a sophisticated balance between a flexible visualization UI and a strictly versioned data model. The architecture relies on a backend migration pipeline to standardize legacy JSON into structured v2 formats, while specialized handlers preserve data for legacy Angular panels. This transition is supported by automated data loss detection and comprehensive metrics to ensure reliability across thousands of dashboard variations.
Sources: apps/dashboard/pkg/migration/README.md:14-25, apps/dashboard/pkg/migration/README.md:310-315