• 1:
• 2:
• 3:

1 -

Dashboard APIs

Sysdig provides some REST APIs to perform CRUD (create, read, update, and delete) operations with Dashboards. This section details how users (both admin and non-admin users) can use the APIs to create, update, list, read, and delete Dashboards.

For information on Sysdig users and system-based privileges, see User and Team Administration.

REST Resource: Dashboard

List all Dashboards

GET /api/v2/dashboards

Request Parameters

Sample Response

{
      dashboards: [
          {
            "id":131,
          "teamId":1,
          "username":"test@domain.com",
          ...see JSON Representation
          }
      ]
  }

Status Codes

Get a Dashboard by ID

GET /api/v2/dashboards/{id}

Request Parameters

Sample Response

See JSON Representation

Status Codes

Create a Dashboard

Create a new Dashboard.

POST /api/v2/dashboards

Request and Response Parameters

Sample Request

{
  "dashboard": {
    "autoCreated": true,
    "createdOn": 0,
    "customerId": 0,
    "domain": "string",
    "eventsOverlaySettings": {
      "eventOverlayLimit": 0,
      "filterNotificationsResolvedFilter": "all",
      "filterNotificationsScopeFilter": true,
      "filterNotificationsSeverityFilter": "all",
      "filterNotificationsStateFilter": "all",
      "filterNotificationsTypeFilter": "all",
      "filterNotificationsUserInputFilter": "string",
      "showNotificationsEnabled": true
    },
    "id": 0,
    "migrationErrors": [
      "string"
    ],
    "modifiedOn": 0,
    "name": "string",
    "public": true,
    "publicToken": "string",
    "schema": 0,
    "scope": "string",
    "scopeExpressionList": [
      {
        "displayName": "string",
        "isVariable": true,
        "operand": "string",
        "operator": "equals",
        "value": [
          "string"
        ],
        "variable": true
      }
    ],
    "shared": true,
    "teamId": 0,
    "userId": 0,
    "username": "string",
    "version": 0,
    "widgets": [
      {
        "customDisplayOptions": {
          "histogram": {
            "numberOfBuckets": 0
          },
          "valueLimit": {
            "count": 0,
            "direction": "desc"
          },
          "xAxis": {
            "from": 0,
            "to": 0
          },
          "yAxisLeftDomain": {
            "from": 0,
            "to": 0
          },
          "yAxisRightDomain": {
            "from": 0,
            "to": 0
          },
          "yAxisScale": "linear"
        },
        "gridConfiguration": {
          "col": 0,
          "row": 0,
          "size_x": 0,
          "size_y": 0
        },
        "name": "string",
        "showAs": "timeSeries"
      }
    ]
  }
}

Status Codes

Update a Dashboard

PUT /api/v2/dashboards/{id}

Request Parameters

Sample Request

{
      dashboards: [
          {
            "id":131,
          "teamId":1,
          "username":"test@domain.com",
          ...see JSON Representation
          }


      ],
       "public":true
  }

Sample Response

{
      dashboards: [
          {
            "id":131,
          "teamId":1,
          "username":"test@domain.com",
          ...see JSON Representation
          }


      ],
       "public":true
  }

Status Codes

Delete a Dashboard

You can delete a Dashboard by a customer ID.

DELETE /api/v2/dashboards/{id}

Request Parameters

Sample Response

See JSON Representation.

Status Codes

JSON Representation

The samples given below describe the JSON schema of a Dashboard.

{
    "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
    }
}

2 -

Save and Restore Dashboards with Scripts

Sysdig Monitor allows a user to save all existing dashboards to a locally controlled file and to create new dashboards identical to the saved ones. This is done using two of the Sysdig’s Python example scripts:

• download_dashboards.py: Stores all current dashboards for the active account in a .zip archive of JSON objects. Each JSON object in the archive corresponds to a dashboard. The dashboard JSON objects are named after the corresponding dashboard IDs.

• restore_dashboards.py: Import the JSON objects in the archive as dashboards and add them to the list of dashboards. **Restore_dashboards.py **does not have to target the same account as download_dashboards.py. This allows dashboards to be saved from one user account and restored to multiple user accounts. If this script is used in a strictly backup/restore capacity, manually delete the dashboards from the account, either before or after the restore action is completed.

Prerequisites

Follow the instructions in Get Started with the SDC Client, and do the following:

• Install the Python client.

• Instantiate the library classes.

• Retrieve the API token needed to use the functions.

Save All Dashboards with download_dashboards.py

To save the dashboards:

1. In a terminal, access the virtual environment set up in Get Started with the SDC Client.

   Note that you will have obtained your API token.

2. Run the script:

   $ python examples/download_dashboards.py API_TOKEN SAVED_DASHBOARDS.ZIP
   Dashboard name: JVM, # Charts: 5
   Finished writing dashboard data in zip format to SAVED_DASHBOARDS.ZIP
   

   Replace API_TOKEN with the API token for the relevant user. Replace SAVED_DASHBOARDS.ZIP with the desired name of the zip file.

3. Ensure that all current dashboards in Sysdig Monitor were downloaded locally as JSON objects in a .zip file.

Restore Archived Dashboards with restore_dashboards.py

To restore dashboards from a .zip archive:

1. In a terminal, access the virtual environment set up in Getting Started with SDCClient

   Note that you will have obtained your API token.

2. Run the script:

   $ python examples/restore_dashboards.py API_TOKEN SAVED_DASHBOARDS.ZIP
   Dashboards pushed.
   $ user@server:~/python-sdc-client$
   

   Replace API_TOKEN with the API token for the relevant user, and SAVED_DASHBOARDS.ZIP with the correct zip file.

   The archived dashboards will be added to the user’s dashboard list in Sysdig Monitor.

3. If necessary, manually delete any duplicates created.

3 -

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

scopeExpressionList

Show Dashboard Events

eventsFilter

Share Dashboard with Team

isShared

shared

Share Public URL

isPublic

public

Dashboard Panels

items

widgets

General Changes

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

Panel Elements

items

widgets

All the Panels Except Topology

Number Panel

Topology Panel

Text Panel

Learn More

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