Dashboard Migrations: V20 variable syntax migration for data links and field options (#109203)

Co-authored-by: Ivan Ortega <ivanortegaalba@gmail.com>
Co-authored-by: Haris Rozajac <haris.rozajac12@gmail.com>
This commit is contained in:
Dominik Prokop
2025-08-08 11:46:34 +02:00
committed by GitHub
parent 8f2d27044d
commit 09d6d97535
5 changed files with 871 additions and 1 deletions
@@ -5,7 +5,7 @@ import (
)
const (
MIN_VERSION = 20
MIN_VERSION = 19
LATEST_VERSION = 41
)
@@ -38,6 +38,7 @@ type PanelPluginInfoProvider interface {
func GetMigrations(dsInfoProvider DataSourceInfoProvider, panelProvider PanelPluginInfoProvider) map[int]SchemaVersionMigrationFunc {
return map[int]SchemaVersionMigrationFunc{
20: V20,
21: V21,
22: V22,
23: V23,
@@ -0,0 +1,163 @@
package schemaversion
import (
"regexp"
"github.com/grafana/grafana/apps/dashboard/pkg/migration/utils"
)
// V20 migrates legacy variable syntax in data links and field options.
// This migration updates variable names from old syntax to new dotted syntax
// used in data links URLs and field option titles.
//
// Variable syntax changes:
// - __series_name → __series.name
// - $__series_name → ${__series.name}
// - __value_time → __value.time
// - __field_name → __field.name
// - $__field_name → ${__field.name}
//
// Example before migration:
//
// "panels": [
// {
// "options": {
// "dataLinks": [
// {
// "url": "http://example.com?series=$__series_name&time=__value_time"
// }
// ],
// "fieldOptions": {
// "defaults": {
// "title": "Field: __field_name",
// "links": [
// {
// "url": "http://example.com?field=$__field_name"
// }
// ]
// }
// }
// }
// }
// ]
//
// Example after migration:
//
// "panels": [
// {
// "options": {
// "dataLinks": [
// {
// "url": "http://example.com?series=${__series.name}&time=__value.time"
// }
// ],
// "fieldOptions": {
// "defaults": {
// "title": "Field: __field.name",
// "links": [
// {
// "url": "http://example.com?field=${__field.name}"
// }
// ]
// }
// }
// }
// }
// ]
func V20(dashboard map[string]interface{}) error {
dashboard["schemaVersion"] = 20
panels, ok := dashboard["panels"].([]interface{})
if !ok {
return nil
}
for _, p := range panels {
panel, ok := p.(map[string]interface{})
if !ok {
continue
}
// Update data links and field options in panel options
if options, ok := panel["options"].(map[string]interface{}); ok {
updateDataLinksVariableSyntax(options)
updateFieldOptionsVariableSyntax(options)
}
}
return nil
}
// updateDataLinksVariableSyntax updates variable syntax in panel data links
func updateDataLinksVariableSyntax(options map[string]interface{}) {
dataLinks, ok := options["dataLinks"].([]interface{})
if !ok || !utils.IsArray(dataLinks) {
return
}
for _, link := range dataLinks {
if linkMap, ok := link.(map[string]interface{}); ok {
if url, ok := linkMap["url"].(string); ok {
linkMap["url"] = updateVariablesSyntax(url)
}
}
}
}
// updateFieldOptionsVariableSyntax updates variable syntax in field options
func updateFieldOptionsVariableSyntax(options map[string]interface{}) {
fieldOptions, ok := options["fieldOptions"].(map[string]interface{})
if !ok {
return
}
defaults, ok := fieldOptions["defaults"].(map[string]interface{})
if !ok {
return
}
// Update field option title
if title, ok := defaults["title"].(string); ok {
defaults["title"] = updateVariablesSyntax(title)
}
// Update field option links
links, ok := defaults["links"].([]interface{})
if !ok || !utils.IsArray(links) {
return
}
for _, link := range links {
if linkMap, ok := link.(map[string]interface{}); ok {
if url, ok := linkMap["url"].(string); ok {
linkMap["url"] = updateVariablesSyntax(url)
}
}
}
}
// Define the regex pattern to match legacy variable names
// Pattern matches: __series_name, $__series_name, __value_time, __field_name, $__field_name
// Defined here to avoid compilation for every function call
var legacyVariableNamesRegex = regexp.MustCompile(`(__series_name)|(\$__series_name)|(__value_time)|(__field_name)|(\$__field_name)`)
// updateVariablesSyntax updates legacy variable names to new dotted syntax
// This function replicates the frontend updateVariablesSyntax behavior
func updateVariablesSyntax(text string) string {
return legacyVariableNamesRegex.ReplaceAllStringFunc(text, func(match string) string {
switch match {
case "__series_name":
return "__series.name"
case "$__series_name":
return "${__series.name}"
case "__value_time":
return "__value.time"
case "__field_name":
return "__field.name"
case "$__field_name":
return "${__field.name}"
default:
return match
}
})
}
@@ -0,0 +1,322 @@
package schemaversion_test
import (
"testing"
"github.com/grafana/grafana/apps/dashboard/pkg/migration/schemaversion"
)
func TestV20(t *testing.T) {
tests := []migrationTestCase{
{
name: "panel with data links gets variable syntax migrated",
input: map[string]interface{}{
"title": "V20 Data Links Variable Syntax Migration Test Dashboard",
"schemaVersion": 19,
"panels": []interface{}{
map[string]interface{}{
"type": "timeseries",
"title": "Panel with data links",
"id": 1,
"options": map[string]interface{}{
"dataLinks": []interface{}{
map[string]interface{}{
"url": "http://mylink.com?series=$__series_name&time=__value_time&field=__field_name",
},
map[string]interface{}{
"url": "http://another.com?series=${__series_name}&field=${__field_name}",
},
},
},
},
},
},
expected: map[string]interface{}{
"title": "V20 Data Links Variable Syntax Migration Test Dashboard",
"schemaVersion": 20,
"panels": []interface{}{
map[string]interface{}{
"type": "timeseries",
"title": "Panel with data links",
"id": 1,
"options": map[string]interface{}{
"dataLinks": []interface{}{
map[string]interface{}{
"url": "http://mylink.com?series=${__series.name}&time=__value.time&field=__field.name",
},
map[string]interface{}{
"url": "http://another.com?series=${__series.name}&field=${__field.name}",
},
},
},
},
},
},
},
{
name: "panel with field options title gets variable syntax migrated",
input: map[string]interface{}{
"title": "V20 Field Options Title Migration Test Dashboard",
"schemaVersion": 19,
"panels": []interface{}{
map[string]interface{}{
"type": "stat",
"title": "Panel with field options title",
"id": 2,
"options": map[string]interface{}{
"fieldOptions": map[string]interface{}{
"defaults": map[string]interface{}{
"title": "Series: __series_name, Field: $__field_name, Time: __value_time",
},
},
},
},
},
},
expected: map[string]interface{}{
"title": "V20 Field Options Title Migration Test Dashboard",
"schemaVersion": 20,
"panels": []interface{}{
map[string]interface{}{
"type": "stat",
"title": "Panel with field options title",
"id": 2,
"options": map[string]interface{}{
"fieldOptions": map[string]interface{}{
"defaults": map[string]interface{}{
"title": "Series: __series.name, Field: ${__field.name}, Time: __value.time",
},
},
},
},
},
},
},
{
name: "panel with field options links gets variable syntax migrated",
input: map[string]interface{}{
"title": "V20 Field Options Links Migration Test Dashboard",
"schemaVersion": 19,
"panels": []interface{}{
map[string]interface{}{
"type": "gauge",
"title": "Panel with field options links",
"id": 3,
"options": map[string]interface{}{
"fieldOptions": map[string]interface{}{
"defaults": map[string]interface{}{
"links": []interface{}{
map[string]interface{}{
"url": "http://example.com?series=__series_name&field=$__field_name",
},
map[string]interface{}{
"url": "http://test.com?time=__value_time",
},
},
},
},
},
},
},
},
expected: map[string]interface{}{
"title": "V20 Field Options Links Migration Test Dashboard",
"schemaVersion": 20,
"panels": []interface{}{
map[string]interface{}{
"type": "gauge",
"title": "Panel with field options links",
"id": 3,
"options": map[string]interface{}{
"fieldOptions": map[string]interface{}{
"defaults": map[string]interface{}{
"links": []interface{}{
map[string]interface{}{
"url": "http://example.com?series=__series.name&field=${__field.name}",
},
map[string]interface{}{
"url": "http://test.com?time=__value.time",
},
},
},
},
},
},
},
},
},
{
name: "panel with both data links and field options gets variable syntax migrated",
input: map[string]interface{}{
"title": "V20 Combined Migration Test Dashboard",
"schemaVersion": 19,
"panels": []interface{}{
map[string]interface{}{
"type": "table",
"title": "Panel with both data links and field options",
"id": 4,
"options": map[string]interface{}{
"dataLinks": []interface{}{
map[string]interface{}{
"url": "http://datalink.com?series=$__series_name",
},
},
"fieldOptions": map[string]interface{}{
"defaults": map[string]interface{}{
"title": "Field Name: __field_name",
"links": []interface{}{
map[string]interface{}{
"url": "http://fieldlink.com?field=$__field_name&time=__value_time",
},
},
},
},
},
},
},
},
expected: map[string]interface{}{
"title": "V20 Combined Migration Test Dashboard",
"schemaVersion": 20,
"panels": []interface{}{
map[string]interface{}{
"type": "table",
"title": "Panel with both data links and field options",
"id": 4,
"options": map[string]interface{}{
"dataLinks": []interface{}{
map[string]interface{}{
"url": "http://datalink.com?series=${__series.name}",
},
},
"fieldOptions": map[string]interface{}{
"defaults": map[string]interface{}{
"title": "Field Name: __field.name",
"links": []interface{}{
map[string]interface{}{
"url": "http://fieldlink.com?field=${__field.name}&time=__value.time",
},
},
},
},
},
},
},
},
},
{
name: "panel without data links or field options remains unchanged",
input: map[string]interface{}{
"title": "V20 No Links Migration Test Dashboard",
"schemaVersion": 19,
"panels": []interface{}{
map[string]interface{}{
"type": "singlestat",
"title": "Panel without links",
"id": 5,
"options": map[string]interface{}{
"someOtherOption": "value",
},
},
},
},
expected: map[string]interface{}{
"title": "V20 No Links Migration Test Dashboard",
"schemaVersion": 20,
"panels": []interface{}{
map[string]interface{}{
"type": "singlestat",
"title": "Panel without links",
"id": 5,
"options": map[string]interface{}{
"someOtherOption": "value",
},
},
},
},
},
{
name: "dashboard without panels remains unchanged",
input: map[string]interface{}{
"title": "V20 No Panels Migration Test Dashboard",
"schemaVersion": 19,
},
expected: map[string]interface{}{
"title": "V20 No Panels Migration Test Dashboard",
"schemaVersion": 20,
},
},
{
name: "panel with empty data links array remains unchanged",
input: map[string]interface{}{
"title": "V20 Empty Data Links Migration Test Dashboard",
"schemaVersion": 19,
"panels": []interface{}{
map[string]interface{}{
"type": "graph",
"title": "Panel with empty data links",
"id": 6,
"options": map[string]interface{}{
"dataLinks": []interface{}{},
},
},
},
},
expected: map[string]interface{}{
"title": "V20 Empty Data Links Migration Test Dashboard",
"schemaVersion": 20,
"panels": []interface{}{
map[string]interface{}{
"type": "graph",
"title": "Panel with empty data links",
"id": 6,
"options": map[string]interface{}{
"dataLinks": []interface{}{},
},
},
},
},
},
{
name: "panel with legacy variables that don't need migration",
input: map[string]interface{}{
"title": "V20 No Legacy Variables Migration Test Dashboard",
"schemaVersion": 19,
"panels": []interface{}{
map[string]interface{}{
"type": "text",
"title": "Panel with modern variables",
"id": 7,
"options": map[string]interface{}{
"dataLinks": []interface{}{
map[string]interface{}{
"url": "http://modern.com?series=${__series.name}&field=${__field.name}",
},
},
},
},
},
},
expected: map[string]interface{}{
"title": "V20 No Legacy Variables Migration Test Dashboard",
"schemaVersion": 20,
"panels": []interface{}{
map[string]interface{}{
"type": "text",
"title": "Panel with modern variables",
"id": 7,
"options": map[string]interface{}{
"dataLinks": []interface{}{
map[string]interface{}{
"url": "http://modern.com?series=${__series.name}&field=${__field.name}",
},
},
},
},
},
},
},
}
runMigrationTests(t, tests, schemaversion.V20)
}
@@ -0,0 +1,152 @@
{
"title": "V20 Variable Syntax Migration Test Dashboard",
"schemaVersion": 19,
"panels": [
{
"type": "timeseries",
"title": "Panel with data links using legacy variable syntax",
"id": 1,
"gridPos": {
"h": 8,
"w": 12,
"x": 0,
"y": 0
},
"options": {
"dataLinks": [
{
"title": "Link with series name",
"url": "http://example.com?series=$__series_name&timestamp=__value_time",
"targetBlank": true
},
{
"title": "Link with field name",
"url": "http://grafana.com/dashboard?field=__field_name&series=$__series_name",
"targetBlank": false
}
]
}
},
{
"type": "stat",
"title": "Panel with field options using legacy variable syntax",
"id": 2,
"gridPos": {
"h": 8,
"w": 12,
"x": 12,
"y": 0
},
"options": {
"fieldOptions": {
"defaults": {
"title": "Series: __series_name, Field: $__field_name, Time: __value_time",
"links": [
{
"title": "Field link",
"url": "http://monitoring.com?field=$__field_name&series=__series_name",
"targetBlank": true
},
{
"title": "Time-based link",
"url": "http://logs.com?time=__value_time&field=__field_name",
"targetBlank": false
}
]
}
}
}
},
{
"type": "gauge",
"title": "Panel with both data links and field options",
"id": 3,
"gridPos": {
"h": 8,
"w": 24,
"x": 0,
"y": 8
},
"options": {
"dataLinks": [
{
"title": "Combined link",
"url": "http://combined.com?series=$__series_name&field=$__field_name&time=__value_time",
"targetBlank": true
}
],
"fieldOptions": {
"defaults": {
"title": "Complete: __series_name / __field_name / __value_time",
"links": [
{
"title": "Comprehensive link",
"url": "http://comprehensive.com?s=$__series_name&f=__field_name&t=__value_time",
"targetBlank": false
}
]
}
}
}
},
{
"type": "table",
"title": "Panel with no legacy variables (should remain unchanged)",
"id": 4,
"gridPos": {
"h": 8,
"w": 12,
"x": 0,
"y": 16
},
"options": {
"dataLinks": [
{
"title": "Modern link",
"url": "http://modern.com?series=${__series.name}&field=${__field.name}&time=${__value.time}",
"targetBlank": true
}
],
"fieldOptions": {
"defaults": {
"title": "Modern: ${__series.name} / ${__field.name} / ${__value.time}",
"links": [
{
"title": "Modern field link",
"url": "http://modern-field.com?s=${__series.name}&f=${__field.name}",
"targetBlank": false
}
]
}
}
}
},
{
"type": "text",
"title": "Panel with no data links or field options",
"id": 5,
"gridPos": {
"h": 8,
"w": 12,
"x": 12,
"y": 16
},
"options": {
"content": "This panel has no data links or field options to migrate."
}
}
],
"time": {
"from": "now-6h",
"to": "now"
},
"timepicker": {},
"timezone": "",
"tags": [
"migration-test"
],
"style": "dark",
"refresh": "5s",
"version": 0,
"uid": "v20-migration-test"
}
@@ -0,0 +1,232 @@
{
"panels": [
{
"datasource": {
"apiVersion": "v1",
"type": "prometheus",
"uid": "default-ds-uid"
},
"gridPos": {
"h": 8,
"w": 12,
"x": 0,
"y": 0
},
"id": 1,
"options": {
"dataLinks": [
{
"targetBlank": true,
"title": "Link with series name",
"url": "http://example.com?series=${__series.name}\u0026timestamp=__value.time"
},
{
"targetBlank": false,
"title": "Link with field name",
"url": "http://grafana.com/dashboard?field=__field.name\u0026series=${__series.name}"
}
]
},
"targets": [
{
"datasource": {
"apiVersion": "v1",
"type": "prometheus",
"uid": "default-ds-uid"
},
"refId": "A"
}
],
"title": "Panel with data links using legacy variable syntax",
"type": "timeseries"
},
{
"datasource": {
"apiVersion": "v1",
"type": "prometheus",
"uid": "default-ds-uid"
},
"gridPos": {
"h": 8,
"w": 12,
"x": 12,
"y": 0
},
"id": 2,
"options": {
"fieldOptions": {
"defaults": {
"links": [
{
"targetBlank": true,
"title": "Field link",
"url": "http://monitoring.com?field=${__field.name}\u0026series=__series.name"
},
{
"targetBlank": false,
"title": "Time-based link",
"url": "http://logs.com?time=__value.time\u0026field=__field.name"
}
],
"title": "Series: __series.name, Field: ${__field.name}, Time: __value.time"
}
},
"justifyMode": "auto",
"percentChangeColorMode": "standard",
"showPercentChange": false,
"textMode": "auto",
"wideLayout": true
},
"targets": [
{
"datasource": {
"apiVersion": "v1",
"type": "prometheus",
"uid": "default-ds-uid"
},
"refId": "A"
}
],
"title": "Panel with field options using legacy variable syntax",
"type": "stat"
},
{
"datasource": {
"apiVersion": "v1",
"type": "prometheus",
"uid": "default-ds-uid"
},
"gridPos": {
"h": 8,
"w": 24,
"x": 0,
"y": 8
},
"id": 3,
"options": {
"dataLinks": [
{
"targetBlank": true,
"title": "Combined link",
"url": "http://combined.com?series=${__series.name}\u0026field=${__field.name}\u0026time=__value.time"
}
],
"fieldOptions": {
"defaults": {
"links": [
{
"targetBlank": false,
"title": "Comprehensive link",
"url": "http://comprehensive.com?s=${__series.name}\u0026f=__field.name\u0026t=__value.time"
}
],
"title": "Complete: __series.name / __field.name / __value.time"
}
}
},
"targets": [
{
"datasource": {
"apiVersion": "v1",
"type": "prometheus",
"uid": "default-ds-uid"
},
"refId": "A"
}
],
"title": "Panel with both data links and field options",
"type": "gauge"
},
{
"datasource": {
"apiVersion": "v1",
"type": "prometheus",
"uid": "default-ds-uid"
},
"gridPos": {
"h": 8,
"w": 12,
"x": 0,
"y": 16
},
"id": 4,
"options": {
"dataLinks": [
{
"targetBlank": true,
"title": "Modern link",
"url": "http://modern.com?series=${__series.name}\u0026field=${__field.name}\u0026time=${__value.time}"
}
],
"fieldOptions": {
"defaults": {
"links": [
{
"targetBlank": false,
"title": "Modern field link",
"url": "http://modern-field.com?s=${__series.name}\u0026f=${__field.name}"
}
],
"title": "Modern: ${__series.name} / ${__field.name} / ${__value.time}"
}
}
},
"targets": [
{
"datasource": {
"apiVersion": "v1",
"type": "prometheus",
"uid": "default-ds-uid"
},
"refId": "A"
}
],
"title": "Panel with no legacy variables (should remain unchanged)",
"type": "table"
},
{
"datasource": {
"apiVersion": "v1",
"type": "prometheus",
"uid": "default-ds-uid"
},
"gridPos": {
"h": 8,
"w": 12,
"x": 12,
"y": 16
},
"id": 5,
"options": {
"content": "This panel has no data links or field options to migrate."
},
"targets": [
{
"datasource": {
"apiVersion": "v1",
"type": "prometheus",
"uid": "default-ds-uid"
},
"refId": "A"
}
],
"title": "Panel with no data links or field options",
"type": "text"
}
],
"refresh": "5s",
"schemaVersion": 41,
"style": "dark",
"tags": [
"migration-test"
],
"time": {
"from": "now-6h",
"to": "now"
},
"timepicker": {},
"timezone": "",
"title": "V20 Variable Syntax Migration Test Dashboard",
"uid": "v20-migration-test",
"version": 0
}