Sysdig Documentation

Migrate Saved Dashboards from V1 to V2

Sysdig Dashboard V2 was introduced in SaaS release dated April 14, 2019. This topic describes the schematic changes introduced to JSON objects in Dashboard V2 and provides the necessary instructions to help restore V1 JSON objects as Dashboards at a later point.

Please note that all dashboards stored within the application are automatically migrated and no manual intervention is needed. After the migration, /api/v2/dashboards will be the new default root endpoint for Sysdig dashboards. We recommend referring to Sysdig Python client for creation, deletion, and migrating dashboard examples.

Intended Audience

Sysdig Monitor users who have the archives of dashboard JSON objects corresponding to prior releases.

About Dashboard V2

The new format signifies a major upgrade to how JSON objects corresponding to dashboards are denoted. The V2 JSON schema asserts stringent validation checks to ensure you have an improved visual experience. All your dashboards are automatically migrated to the new format and expected to work as before. The Python client library and Grafana data source are updated to work seamlessly with the new dashboard format. You can continue using the save and restore scripts provided by the Python client library to store dashboards locally and restore from the archive file. However, restoring dashboards from the previous version of JSON object archives requires you to edit them to match the new schema. Because several changes are introduced in the V2 schema, you must migrate the existing JSON objects in V1 to V2, before restoring them to the list of dashboards.

Sample Dashboard JSON Objects

The samples given below describe JSON schema corresponding to Dashboard V1 and V2 respectively.

Dashboard Payload V1 Expand source

{
    "dashboard":{
        "teamId":1,
        "autoCreated":false,
        "isShared":false,
        "isPublic":false,
        "schema":1,
        "layout":[
            {
                "col":1,
                "row":1,
                "size_x":6,
                "size_y":4
            },
            {
                "col":7,
                "row":1,
                "size_x":6,
                "size_y":4
            }
        ],
        "scopeExpressionList":[
            {
                "operator":"notContains",
                "operand":"host.mac",
                "value":[
                    "test"
                ],
                "isVariable":false,
                "displayName":"Host"
            }
        ],
        "name":"V1 dashboard",
        "filterExpression":"not host.mac contains \"test\"",
        "items":[
            {
                "id":1,
                "showAs":"summary",
                "showAsType":"summary",
                "name":"Summary",
                "scope":"not host.mac contains \"test\"",
                "overrideFilter":false,
                "gridConfiguration":{
                    "col":1,
                    "row":1,
                    "size_x":6,
                    "size_y":4
                },
                "customDisplayOptions":{
                    "valueLimit":{
                        "count":10,
                        "direction":"desc"
                    },
                    "yAxisScale":"linear",
                    "yAxisLeftDomain":{
                        "from":0,
                        "to":null
                    },
                    "yAxisRightDomain":{
                        "from":0,
                        "to":null
                    },
                    "histogram":{
                        "numberOfBuckets":10
                    },
                    "xAxis":{
                        "from":0,
                        "to":null
                    }
                },
                "compareToConfig":null,
                "limitToScope":false,
                "metrics":[
                    {
                        "metricId":"cpu.used.percent",
                        "propertyName":"v0",
                        "aggregation":"avg",
                        "groupAggregation":"avg",
                        "metricFormattingUnit":null,
                        "metricFormattingDecimals":null
                    }
                ],
                "colorCoding":{
                    "active":true,
                    "thresholds":[
                        {
                            "color":"best",
                            "min":null,
                            "max":20
                        },
                        {
                            "color":"ok",
                            "min":20,
                            "max":50
                        },
                        {
                            "color":"worst",
                            "min":50,
                            "max":null
                        }
                    ]
                }
            },
            {
                "id":2,
                "showAs":"timeSeries",
                "showAsType":"line",
                "name":"Time Series",
                "scope":"not host.mac contains \"test\"",
                "overrideFilter":false,
                "gridConfiguration":{
                    "col":7,
                    "row":1,
                    "size_x":6,
                    "size_y":4
                },
                "customDisplayOptions":{
                    "valueLimit":{
                        "count":10,
                        "direction":"desc"
                    },
                    "yAxisScale":"linear",
                    "yAxisLeftDomain":{
                        "from":0,
                        "to":null
                    },
                    "yAxisRightDomain":{
                        "from":0,
                        "to":null
                    },
                    "histogram":{
                        "numberOfBuckets":10
                    },
                    "xAxis":{
                        "from":0,
                        "to":null
                    }
                },
                "compareToConfig":null,
                "limitToScope":false,
                "metrics":[
                    {
                        "metricId":"timestamp",
                        "propertyName":"k0"
                    },
                    {
                        "metricId":"container.id",
                        "propertyName":"k1"
                    },
                    {
                        "metricId":"cpu.used.percent",
                        "propertyName":"v0",
                        "aggregation":"avg",
                        "groupAggregation":"avg",
                        "metricFormattingUnit":null,
                        "metricFormattingDecimals":null
                    }
                ],
                "sorting":[
                    {
                        "id":"v0",
                        "mode":"desc"
                    }
                ],
                "paging":{
                    "from":0,
                    "to":9
                }
            }
        ],
        "username":"test@domain.com"
    }
}

Dashboard Payload V2 Expand source

{
    "dashboard":{
        "id":131,
        "teamId":1,
        "username":"test@domain.com",
        "schema":2,
        "autoCreated":false,
        "shared":false,
        "name":"V2 dashboard",
        "widgets":[
            {
                "showAs":"summary",
                "name":"Summary",
                "gridConfiguration":{
                    "col":1,
                    "row":1,
                    "size_x":6,
                    "size_y":4
                },
                "customDisplayOptions":{
                    "valueLimit":{
                        "count":10,
                        "direction":"desc"
                    },
                    "histogram":{
                        "numberOfBuckets":10
                    },
                    "yAxisScale":"linear",
                    "yAxisLeftDomain":{
                        "from":0,
                        "to":null
                    },
                    "yAxisRightDomain":{
                        "from":0,
                        "to":null
                    },
                    "xAxis":{
                        "from":0,
                        "to":null
                    }
                },
                "scope":null,
                "overrideScope":false,
                "metrics":[
                    {
                        "id":"cpu.used.percent",
                        "propertyName":"v0",
                        "timeAggregation":"avg",
                        "groupAggregation":"avg"
                    }
                ],
                "compareToConfig":null,
                "colorCoding":{
                    "active":true,
                    "thresholds":{
                        "worst":50,
                        "best":20
                    }
                }
            },
            {
                "showAs":"timeSeries",
                "name":"Time series",
                "gridConfiguration":{
                    "col":7,
                    "row":1,
                    "size_x":6,
                    "size_y":4
                },
                "customDisplayOptions":{
                    "valueLimit":{
                        "count":10,
                        "direction":"desc"
                    },
                    "histogram":{
                        "numberOfBuckets":10
                    },
                    "yAxisScale":"linear",
                    "yAxisLeftDomain":{
                        "from":0,
                        "to":null
                    },
                    "yAxisRightDomain":{
                        "from":0,
                        "to":null
                    },
                    "xAxis":{
                        "from":0,
                        "to":null
                    }
                },
                "scope":null,
                "overrideScope":false,
                "metrics":[
                    {
                        "id":"timestamp",
                        "propertyName":"k0"
                    },
                    {
                        "id":"container.id",
                        "propertyName":"k1"
                    },
                    {
                        "id":"cpu.used.percent",
                        "propertyName":"v0",
                        "timeAggregation":"avg",
                        "groupAggregation":"avg"
                    }
                ],
                "compareToConfig":null
            }
        ],
        "scopeExpressionList":[
            {
                "operand":"host.mac",
                "operator":"notContains",
                "displayName":"Host",
                "value":[
                    "test"
                ],
                "isVariable":false
            }
        ],
        "eventsOverlaySettings":{
            "showNotificationsEnabled":true,
            "filterNotificationsUserInputFilter":"",
            "eventOverlayLimit":1000,
            "filterNotificationsTypeFilter":"all",
            "filterNotificationsStateFilter":"all",
            "filterNotificationsSeverityFilter":"all",
            "filterNotificationsResolvedFilter":"all"
        },
        "public":false
    }
}

Compare Two Versions of JSON Schema

The tables summarize the major differences between the two versions of JSON schema:

Deprecated Fields

  • filterExpression

  • layout

  • group property is deprecated in all panel types except for Topology (widgets item with showAs=map).

Dashboard Scope

V1 Fields

Schema Changes

V2 Fields

scopeExpressionList
  • If filterExpression is not defined in V1, leave it undefined in V2.

  • Split filterExpression into individual expressions (by removing all the AND operators). For each expression, build an expression object with the following properties:

    • Set operand to label id, for example, host.mac.

    • Set operator to one of the following: equals, notEquals, in, notIn, contains, notContains, startsWith. Map them from the corresponding operator given in standard scope syntax: =, !=, in, not in, contains, not contains, and starts with. For example, host.mac = 'foo' becomes { operand: 'host.mac', operator: 'equals', value: ['foo'] }

    • Ensure value is an array with the values of the expression. For every operator except the in and notIn operators, value contains only one element.

    • Set isVariable to false.

    • Set displayName to an empty string.

scopeExpressionList

Show Dashboard Events

V1 Fields

Schema Changes

V2 Fields

eventsFilter

Rename to eventsOverlaySettings.

The following properties are deprecated:

  • showNotificationsDoNotFilterSameMetrics

  • showNotificationsDoNotFilterSameScope

eventsOverlaySettings

Share Dashboard with Team

V1 Fields

Schema Changes

V2 Fields

isShared

Rename to shared.

shared

Share Public URL

V1 Fields

Schema Changes

V2 Fields

isPublic

Rename to public.

public

Dashboard Panels

V1 Fields

Schema Changes

V2 Fields

items

Rename to widgets.

widgets

General Changes

The following sections describe the changes that apply to each panel (widget field):

Panel Elements

V1 Fields

Schema Changes

V2 Fields

items
  • Rename to widgets

  • Change overrideFilter to overrideScope. Setting its value to false causes to ignore the scope property. The panel then uses the Dashboard scope.

  • The showAsType and id properties are deprecated.

  • The sorting and paging properties are deprecated.

  • The yAxisScaleFactor property inside customDisplayOptions is deprecated.

widgets

metrics

  • Change metricId to id.

  • Chane aggregation to timeAggregation.

metrics

All the Panels Except Topology

V1 Fields

Schema Changes

V2 Fields

widgets without showAs=map

The group property is deprecated.

widgets without showAs=map

Number Panel

V1 Fields

Schema Changes

V2 Fields

widgets with showAs set to summary

In V1, an array is formed as follows:

  • Includes exactly three objects.

  • Each object with the { color, min, max } format.

  • Color is set to best, ok, worst respectively for the three objects.

  • If the lower values are set to best, format the min and max properties as follows:

    • { color: best, min: null, max: 30 }

    • { color: ok, min: 30, max: 50 }

    • { color: worst, min: 50, max: null }

  • If the upper values are best, format the min and max properties as follows:

    • { color: best, min: 50, max: null }

    • { color: ok, min: 30, max: 50 }

    • { color: worst, min: null, max: 30 }

  • If neither of the aforementioned is respected, the configuration is incorrect.

For V2 schema, do the following:

If colorCoding is defined in V1, migrate the thresholds property as follows:

  • The format is simple. For example: { best: 30, worst: 50 }

    • If the lower values are set to best in V1, build the new object as follows:

      • Set best to the max value of the object with color=best.

      • Set worst to the min value of the object with color=worst.

    • If the lower values are set to worst in V1, build the new object as follows:

      • Set best to the min value of the object with color=best.

      • Set worst to the max value of the object with color=worst.

widgets with showAs=summary

Topology Panel

VI Fields

Schema Changes

V2 Fields

widgets with showAs=map

Rename group to groupingLabelIds and do the following:

The group property in V1 has an array of objects similar to { metric: "host.mac"} nested under layers of objects: group.configuration.groups[0].groupBy. Change that for the groupingLabelIds to a simple array of objects:

[{ labelId: "host.mac" }]

widgets with showAs=map

Text Panel

VI Fields

Schema Changes

V2 Fields

widgets with showAs=text

  • Change hasTransparentBackground to transparentBackground.

  • Change isPanelTitleVisible to panelTitleVisible.

  • Change isTextAutosized to textAutosized.

widgets with showAs=text

Learn More

Use the Sysdig Python client to create, edit, delete dashboards.