Working with Dashboards
Learn how to programmatically interact with Sysdig Dashboards:
This the multi-page printable view of this section. Click here to print.
Learn how to programmatically interact with Sysdig Dashboards:
Dashboard APIs are no longer supported by Sysdig SaaS v3.2.6 (June 17, 2020) and Sysdig On-Prem v3.5.0. This page remains only for reference. We suggest that you use Sysdig CLI for Sysdig Monitor and Secure or Sysdig Python Client to manage dashboards programmatically. If you have any questions, contact support@sysdig.com.
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.
GET /api/v2/dashboards
Field | Description |
---|---|
Team | Integer (int32) Gets Dashboards for a specific team. If not provided, fetches the Dashboards owned by the team that the current user belongs to. |
Shared | Boolean Supported values are true and false. The default is False. If true, shows all the shared Dashboards owned by the team the current user belongs to. |
AutoCreated | Boolean Supported values are true and false. The default is False. If true, shows all the auto-created Dashboards. |
light | If true, Dashboards payload in response will be a smaller version as shown below. The performance will be superior because it is loading fewer data. When the |
Request Parameters
{
dashboards: [
{
"id":131,
"teamId":1,
"username":"test@domain.com",
...see JSON Representation
}
]
}
Code | Description |
---|---|
200 | Indicates if the Dashboard has been successfully created. |
401 | Indicates that the requested resource is restricted and requires authentication, but you failed to provide any such authentication. |
403 | Indicates you are unauthorized to access the Dashboard. |
404 | Indicates the Dashboard is not found. |
GET /api/v2/dashboards/{id}
Field | Description |
---|---|
id | Integer (int64) The unique ID of the Dashboard. |
Request Parameters
Codes | Description |
---|---|
200 | Indicates if the Dashboard has been successfully created. |
401 | Indicates that the requested resource is restricted and requires authentication, but you failed to provide any such authentication. |
403 | Indicates you are unauthorized to access the Dashboard. |
404 | Indicates a Dashboard is not found. |
Create a new Dashboard.
POST /api/v2/dashboards
Field | Description |
---|---|
AutoCreated | Boolean Supported values are true and false. The default value is False. Indicates whether the Dashboard is created automatically or not. |
CreatedOn | The date the Dashboard is created. |
CustomerId | Unique ID of the user. |
domain | The domain name associated with the Dashboard. |
eventsOverlaySettings | The Event overlay settings. |
ID | The unique ID of the Dashboard. |
migrationErrors | Returns migration errors if any. |
ModifiedOn | The date when the Dashboard was last modified. |
Schema | The version of the Schema associated with the Dashboard. |
Scope | The scope of the Dashboard. |
scopeExpressionList | Identifies the following:
|
Shared | Boolean Supported values are true and false. Indicates if the Dashboard is shared or not. |
teamid | The unique identification code of the team that owns the Dashboard. |
userid | The unique identification code of the user that created the Dashboard. |
username | The username of the user that created the Dashboard. |
version | The version number of the Dashboard schema. |
widget | The widgets associated with the Dashboard. Identifies the following:
|
Request and Response Parameters
{
"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"
}
]
}
}
Code | Description |
---|---|
200 | Indicates if the Dashboard has been successfully created. |
401 | Indicates that the requested resource is restricted and requires authentication, but you failed to provide any such authentication. |
403 | Indicates you are unauthorized to access the Dashboard. |
422 | Indicates validation errors. |
PUT /api/v2/dashboards/{id}
Field | Description |
---|---|
ID | Integer (int64) The unique ID of the dashboard. |
Request Parameters
{
dashboards: [
{
"id":131,
"teamId":1,
"username":"test@domain.com",
...see JSON Representation
}
],
"public":true
}
{
dashboards: [
{
"id":131,
"teamId":1,
"username":"test@domain.com",
...see JSON Representation
}
],
"public":true
}
Code | Description |
---|---|
200 | Indicates if the Dashboard has been successfully updated. |
401 | Indicates that the requested resource is restricted and requires authentication, but you failed to provide any such authentication. |
403 | Indicates you are unauthorized to access the Dashboard. |
404 | Indicates a Dashboard is not found. |
406 | Indicates validation errors. |
422 | Indicates conflicts while saving the Dashboard. |
You can delete a Dashboard by a customer ID.
DELETE /api/v2/dashboards/{id}
Field | Description |
---|---|
Id | Integer (int32) The unique identification code of the Dashboard. |
Request Parameters
See JSON Representation.
Code | Description |
---|---|
200 | Indicates if the Dashboard has been successfully deleted. |
401 | Indicates that the requested resource is restricted and requires authentication, but you failed to provide any such authentication. |
403 | Indicates you are unauthorized to access the Dashboard. |
404 | Indicates a Dashboard is not found. |
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
}
}
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.
Restoring dashboards will not override the user’s existing dashboards. Instead, new dashboards will be added to the list.
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.
To save the dashboards:
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.
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.
Ensure that all current dashboards in Sysdig Monitor were downloaded locally as JSON objects in a .zip file.
To restore dashboards from a .zip archive:
In a terminal, access the virtual environment set up in Getting Started with SDCClient
Note that you will have obtained your API token.
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.
If necessary, manually delete any duplicates created.
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.
Sysdig Monitor users who have the archives of dashboard JSON objects corresponding to prior releases.
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.
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
}
}
The tables summarize the major differences between the two versions of JSON schema:
filterExpression
layout
group
property is deprecated in all panel types except for
Topology (widgets
item with showAs=map
).
V1 Fields | Schema Changes | V2 Fields |
---|---|---|
|
|
|
V1 Fields | Schema Changes | V2 Fields |
---|---|---|
| Rename to The following properties are deprecated:
|
|
V1 Fields | Schema Changes | V2 Fields |
---|---|---|
| Rename to |
|
V1 Fields | Schema Changes | V2 Fields |
---|---|---|
| Rename to |
|
V1 Fields | Schema Changes | V2 Fields |
---|---|---|
| Rename to |
|
The following sections describe the changes that apply to each panel
(widget
field):
V1 Fields | Schema Changes | V2 Fields |
---|---|---|
|
|
|
|
|
|
V1 Fields | Schema Changes | V2 Fields |
---|---|---|
widgets without showAs=map | The group property is deprecated. | widgets without showAs=map |
V1 Fields | Schema Changes | V2 Fields |
---|---|---|
| In V1, an array is formed as follows:
For V2 schema, do the following: If
|
|
VI Fields | Schema Changes | V2 Fields |
---|---|---|
| Rename The
|
|
VI Fields | Schema Changes | V2 Fields |
---|---|---|
|
|
|
Use the Sysdig Python client to create, edit, delete dashboards.