• 1:
• 1.1:
• 1.2:
• 2:
• 3:
• 4:
• 5:
• 6:
• 7:
• 7.1:
• 8:
• 8.1:
• 8.2:
• 8.3:
• 9:

1 -

Sysdig Python Client

Sysdig provides a Python client library and a collection of Python sample scripts to expose and use some of the most common Sysdig API functions, also known as the sdcclient. Typically, users either make minor modifications to a sample Python script to automate something simple, such as creating users or adding users to teams, or they work along with Sysdig professional services to customize samples and create more complex application integrations.

Learn more about using the sdcclient library and scripts:

• Sysdig Python Script Library and Sample Scripts

• Getting Started with SDCClient

1.1 -

Sysdig Python Script Library and Sample Scripts

The Python Script Library and Function List, as well as the collection of sample scripts, are stored on GitHub, as summarized below.

Script Library and Function List

Access the latest library at Sysdig SDK Library

Sample Scripts

Access the scripts on GitHub: https://github.com/draios/python-sdc-client/tree/master/examples.

Recent scripts include:

1.2 -

Getting Started with SDCClient

Follow the steps below to install and instantiate the Sysdig Python client library and scripts.

Prerequisites

• Python version 3.6 or above

• pip version 1.3 or above

  pip is installed as part of the Python package for versions 2.7 and later.

• virtualenv (recommended)

• Have your Sysdig API token on-hand

Retrieve the Sysdig API Token

When using the Sysdig API with custom scripts or applications, an API security token (specific to each team) must be supplied.

1. Log in to Sysdig Monitor or Sysdig Secure and select Settings.

2. Select User Profile.The Sysdig Monitor or Sysdig Secure API token is displayed (depending on which interface and team you logged in to).

3. You can Copy the token for use, or click the Reset Token button to generate a new one.

   When reset, the previous token issued will immediately become invalid and you will need to make appropriate changes to your programs or scripts.

Install the Python Client

The library and example scripts are available in the Sysdig GitHub repository.

Install the Sysdig Python client (sdcclient) using one of the following methods:

Option 1 Use Pip Command

Install the client by using pip. Run the following command:

pip install sdcclient

On-Premises Installs

For On-Premises Sysdig platform installations, additional configuration is necessary to point to your API server rather than the default SaaS-based one, and also to easily connect when using a self-signed certificate for SSL.

One way to handle this is by setting environment variables before running your Python scripts:

export SDC_URL='https://<YOUR-API-SERVER-HOSTNAME-OR-IP>'
export SDC_SSL_VERIFY='false'

Alternatively, you can specify the additional arguments in your Python scripts as you instantiate the SDC client:

client = SdMonitorClient(api_token, sdc_url='https://<YOUR-API-SERVER-HOSTNAME-OR-IP>', ssl_verify=False)

Instantiate the Library Classes

The library exports two classes, SdMonitorClient and SdSecureClient which are used to connect to the Sysdig Monitor/Secure back end and execute actions. (For backwards compatibility purposes, a third class SdcClient is exported which is an alias of SdMonitorClient.)

They can be instantiated like this:

from sdcclient import SdMonitorClient

api_token ="MY_API_TOKEN"

#
# Instantiate the Sysdig Monitor client
#
client = SdMonitorClient(api_token)

Once instantiated, all the methods documented in the Python Script Library can be called on the object.

Return Values

Every method in the SdMonitorClient/SdSecureClient classes returns a list with two entries. The first one is a boolean value indicating if the call was successful. The second entry depends on the result:

• If the call was successful, it’s a dictionary reflecting the json returned by the underlying REST call

• If the call failed, it’s a string describing the error

For an example on how to parse this output, take a look at a simple example like get_data_simple.py

Using Logs for Learning Purposes

If your goal is to interact with the REST API directly, you can use the Python client library to understand the REST interactions by logging the actions it takes. This is useful because full documentation of the REST API has not yet been created; it also provides a complete example of known working operations.

• Use or modify an example, or write a new script against the Python sdcclient module.

• Log the HTTP requests made by the script.

To log all the requests made by your script in significant detail, add to your script:

import logging
import httplib
httplib.HTTPConnection.debuglevel = 1

logging.basicConfig() # you need to initialize logging, otherwise you will not see anything from requests
logging.getLogger().setLevel(logging.DEBUG)
requests_log = logging.getLogger("requests.packages.urllib3")
requests_log.setLevel(logging.DEBUG)
requests_log.propagate = True

Then run as normal.

Next Steps

• Explore the script library and function list.

• Explore the sample Python scripts provided.

2 -

Sysdig CLI for Sysdig Monitor and Secure

Learn a basic introduction to the Python client CLI for Sysdig Monitor and Sysdig Secure.

Access the CLI Docs

The core documents are housed and updated here: https://sysdiglabs.github.io/sysdig-platform-cli/.

Notes

• To find the SDC_MONITOR_TOKEN or SDC_SECURE_TOKEN: Log in to the appropriate product in the Sysdig Platform and follow the instructions to Find Sysdig API Token.

• For SDC_MONITOR_URL and SDC_SECURE_URL: Use the endpoint for where your Sysdig Secure is deployed:

  • Default SaaS (US East): Monitor https://app.sysdigcloud.com or Secure https://secure.sysdig.com

  • SaaS US West: Monitor and Secure https://us2.app.sysdig.com

  • SaaS EU: Monitor and Secure https://eu1.app.sysdig.com

  • On-Premises: Self-defined

3 -

Sysdig REST API Conventions

Because public exposure of the Sysdig REST API is still in beta and is not fully documented, most developers use the Python client and the Python script library to automate/integrate basic functions into their Sysdig implementation. However, the REST API may be necessary or useful when experienced developers:

• Don’t want to use Python, for whatever reason

• Need more customization than the scripts and library functions of the Python client permit

In these cases, you may work with a Sysdig support engineer, and use the introductory material in this guide to get started.

Prerequisites

• Familiarity with the RESTful programming language of your choice (cURL, Javascript, Wget, etc.)

• Have your Sysdig API token on hand. See Retrieve the Sysdig API Token for details.

Conventions

Access | Send | Receive

API access is over HTTPS and accessed from:

• SaaS: See SaaS Regions and IP Ranges for the URLs corresponding to different regions.

  For example:

  • Sysdig Secure for US East: https://secure.sysdig.com

  • Sysdig Monitor for US West:[ https://us2.app.sysdig.com](http:// https://us2.app.sysdig.com)

  • Sysdig Secure for EU Central: https://eu1.app.sysdig.com

  • Sysdig Monitor for EU Central: https://eu1.app.sysdig.com

• On-Prem: through your Sysdig application server address

Data is sent and received using JSON format.

Authorization

The Sysdig API token must be passed to the HTTPS server via the Authorization header with the format:

Authorization: Bearer [token]

Encoding

The request should set the HTTP header:

Accept: application/json

Every response is returned with the HTTP header

Content-Type: application/json;charset=UTF-8

To reduce the size of the request and (primarily) the response, you can set the header to compress HTTP body and response:

Accept-Encoding:gzip, deflate, sdch

Conventions used to Handle Resources

The REST API allows you to do two things:

1. Handle resources

2. Execute operations

A resource can be a piece of configuration, a user, a dashboard, an alert, and so on.

List Resources

The URL uses the plural name for the resource, e.g:

GET /api/alerts
 {
     "alerts": [ ... ]
 }

Create Resources

The URL uses the plural name and the request envelop uses the singular name, e.g.:

POST /api/alerts
{
    "alert": { ... }
}

Get One Resource

The URL uses the plural name, and the response envelop uses the singular name, e.g.:

GET /api/alerts/123

 {
     "alert": { ... }
 }

4 -

Creating Access Keys

The Access Key is a token that you must configure Sysdig agents to successfully forward data from your monitored environment to the Sysdig Monitor instance. If the access key is compromised or you have the policy to renew it, you can generate a new access key and disable the old one. This topic helps you to do so.

Creating an Access Key

To create an access key:

1. Retrieve the Sysdig API token from the Sysdig Monitor UI.

   For more information, see Retrieve the Sysdig API Token.

2. Issue a curl POST request against the Sysdig endpoint to generate a new access key:

   $ curl -XGET -H 'Authorization: Bearer API_TOKEN' https://<region>.app.sysdig.com/api/customers/accessKeys

   Replace the following:

   • API_TOKEN with the token you retrieved in step 1.

   • <region> with your Sysdig endpoint associated with your region.

   The output will provide the newly generated access key in the response.

   {
     "customerAccessKey": {
         "enabled": true,
         "accessKey": "87654321-1234-1234-1234-123456789012",
         "dateCreated": 2263852422114,
         "dateDisabled": null
     }
   }
   

   The access key can now be used in the Sysdig agent configuration files.

Viewing the Available Access Keys

To view all of the access keys for your Sysdig Monitor instance, do the following:

1. Retrieve the API token from the Sysdig Monitor UI.

   For more information, see Retrieve the Sysdig API Token.

2. Issue a curl GET request against the Sysdig Monitor endpoint to enable the given access key:

   $ curl -XGET -H 'Authorization: Bearer API_TOKEN' https://<region>.app.sysdig.com/api/customer/accessKeys

   Replace the following:

   • API_TOKEN with the token you retrieved in step 1.

   • <region> with your Sysdig endpoint associated with your region.

   The output will provide a list of the access keys in the response and indicates whether they are enabled.

   {
     "customerAccessKeys": [
         {
             "enabled": true,
             "accessKey": "12345678-1234-4321-1234-123456789000",
             "dateCreated": 5242096409000,
             "dateDisabled": null
         },
         {
             "enabled": false,
             "accessKey": "87654321-1234-1234-1234-123456789012",
             "dateCreated": 2553849361000,
             "dateDisabled": 2553849367000
         }
     ]
   }
   

Disabling an Access Key

To disable an existing access key for your Sysdig Monitor instance, do the following:

1. Retrieve the API token from the Sysdig Monitor UI.

   For more information, see Retrieve the Sysdig API Token.

2. Issue a curl POST request against the Sysdig Monitor endpoint to disable the given access key.

   $ curl -XPOST -H 'Authorization: Bearer API_TOKEN' https://<region>.app.sysdig.com/api/customer/accessKeys/ACCESS_KEY/disable

   Replace the following:

   • API_TOKEN with the token you retrieved in step 1.

   • <region > with your Sysdig endpoint associated with your region.

   • ACCESS_KEY with the access key that you wish to disable.

   Once you disable the Sysdig access key, the agents connected with the access key will be immediately blocked from sending metrics to your Sysdig Monitoring instance.

   Deleting access keys is not supported at this time.

Enabling an Access Key

To enable an existing access key for a Sysdig Monitor instance, do the following:

1. Retrieve the API token from the Sysdig Monitor UI.

   For more information, see Retrieve the Sysdig API Token.

2. Issue a curl POST request against the Sysdig Monitor endpoint to enable the given access key.

   $ curl -XPOST -H 'Authorization: Bearer API_TOKEN' https://<region>.app.sysdig.com/api/customer/accessKeys/ACCESS_KEY/enable

   Replace the following:

   • API_TOKEN with the token you retrieved in step 1.

   • <region > with your Sysdig endpoint associated with your region.

   • ACCESS_KEY with the access key that you wish to disable.

3. Restart the agents for the new connection to work as expected.

   The agent that connects with a disabled access key will be terminated.

5 -

[BETA] Auditing Sysdig Platform Activities

Sysdig allows administrators to view a log of user activities and modifications to the components in the system. Audit logs refer to chronologically cataloged events to provide a history of operational actions and to mitigate challenges. The ability to trace an event back to their origin provides proof of compliance and operational integrity, and protection from unsolicited use. An audit log contains:

• What the event was about.

• What user, service, system, or application launched the event.

• The date and time the event occurred

Sysdig maintains audit logs in the database for 14 days and removes them in a first-in, first-out basis. The event retention limit is 100 K events per day.

Prerequisites

At this time, this feature is available only for Sysdig Secure On-Premises.

Usecases

• View user logins happened on a specific day for compliance purposes. 

• Investigate issues such as the “Messaging Service - Health” Dashboard showing no data.

• View if something has changed.

• Investigate security incidents, such as Sysdig collecting sensitive data.

• View who accessed the capture on Sysdig Monitor side.

• Keep a record of removing a user from the system who is no longer with the organization.

Accessing Audit APIs

Use the conventions described in REST API Conventions to access Audit APIs.

Methods

• GET

• POST

Available Audit APIs

The following APIs are available to support the audit log feature.

• AppAttributes

• AuditEvents

AppAttributes

AppAttributes enables registering audit logs in Sysdig.

Base URL

https://<ip>/api/admin/appAttributes

Request Parameters

Request Parameters

Response Parameters

See table_title

Sample  Request

Fire a request as follows to enable audit log:

curl -k --header "Content-Type: application/json" -H "X-Sysdig-Product: SDC" -H "Authorization: Bearer <token>"\
  --request POST \
  --data '{"id":"auditLogEnabled","value":"true"}' \
  https://<url>/api/admin/appAttributes

Sample Response

The response looks as follows:

{"id": "auditLogEnabled","value": "true"}

auditEvents

auditEvents returns a list of auditable events.

Request Parameters

Request Parameters of auditEvents

Response Parameters

Response Parameters

Sample Request to Query by Date Range

The request parameters show the start and end time of the interval in which events are observed and registered.

curl -k --header "Content-Type: application/json" -H "X-Sysdig-Product: SDC" -H "Authorization: Bearer <token>"\ --request GET \ 'http://localhost:9000/api/audit/events?from=2019-06-25 11:00:00&to=2019-06-25 12:41:00'

Sample Response

{
    "auditEvents": [
        {
            "customerId": 1,
            "username": "test@draios.com",
            "requestMethod": "POST",
            "requestUri": "/api/admin/appAttributes",
            "queryString": "",
            "responseStatus": 200,
            "responseReasonPhrase": "OK",
            "dateCreated": "2019-06-25 11:07:32",
            "lastUpdated": "2019-06-25 11:07:32"
        },
        {
            "customerId": 1,
            "username": "test@draios.com",
            "requestMethod": "GET",
            "requestUri": "/api/history/timelines/",
            "queryString": "",
            "responseStatus": 200,
            "responseReasonPhrase": "OK",
            "dateCreated": "2019-06-25 11:07:42",
            "lastUpdated": "2019-06-25 11:07:42"
        }
}

Sample Request to Query by Date Range, Username, and methodType

curl -k --header "Content-Type: application/json" -H "X-Sysdig-Product: SDC" -H "Authorization: Bearer <token>"\ --request GET \ 'http://localhost:9000/api/audit/events?from=2019-06-25 11:00:00&to=2019-06-25 12:41:00&methodType=POST&username=test@draios.com'

Sample Response

{
    "auditEvents": [
        {
            "customerId": 1,
            "username": "test@draios.com",
            "requestMethod": "POST",
            "requestUri": "/api/admin/appAttributes",
            "queryString": "",
            "responseStatus": 200,
            "responseReasonPhrase": "OK",
            "dateCreated": "2019-06-25 11:07:32",
            "lastUpdated": "2019-06-25 11:07:32"
        }
}

Disable Audit Log

To disable audit log, get the current version of the API, then pass the new value and the current version field as follows:

curl -sk  -H "Content-Type: application/json" -H "Authorization: Bearer <TOKEN>" --request PUT --data '{"value":"false", "version": 1}' "https:// <HOSTNAME>/api/admin/appAttributes/auditLogEnabled" | jq
{
  "appAttribute": {
    "id": "auditLogEnabled",
    "version": 2,
    "createdOn": 1564743383000,
    "modifiedOn": 1565115934000,
    "value": "false"
  }
}

6 -

User Provisioning API

The Provisioning API allows administrators to automate creating and provisioning user and service accounts, and enable Sysdig applications at scale for users.

For example, you can programmatically onboard users and configure their accounts by using a method of your choice without having to verify their email addresses.

Prerequisites

• Requires Administrator permissions (the admin role).

• An API client is installed.

  The examples in this topic use simple HTTP calls.

Overview

When this API call is made, the following happens:

• If the call is successful, the user is created as specified.

• The user is added to the default team with the role defined in the team.

REST Resource: Provisioning

POST /api/user/provisioning/
Authorization: {{token}}
Content-Type: application/json

{
   "username": "user@company",
}

See Sysdig REST API Conventions for generic conventions and authentication.

Request Parameters

Response Parameters

Sample Request: REST

REST

POST /api/user/provisioning/
Authorization: {{token}}
Content-Type: application/json

{
   "username": "testuser@company",
}

Python SDK

from <sdc_url> import SdMonitorClient

api_token = "<your_api_token>"

client = SdMonitorClient(token=api_token,sdc_url="https://app-staging.sysdigcloud.com")

ok, user = client.create_user(user_email='test2user@company')

if ok:
  print(user['token'])

Sample Response

The response consists of a standard user model response and the API token for the user.

{

  "user": {

...<user data: ...see JSON Representation>

  },
  "token": {

    "key": "<user_key>"
  }
}

JSON Representation

The samples given below describes the user Provisioning API response in JSON format.

HTTP/1.1 201 Created
Content-Type: application/json;charset=utf-8
Transfer-Encoding: chunked
Connection: close
Date: Mon, 01 Feb 2021 17:55:02 GMT
Vary: Origin, Access-Control-Request-Method, Access-Control-Request-Headers, Accept-Encoding, User-Agent
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Encoding: gzip
Strict-Transport-Security: max-age=15768000
Set-Cookie: INGRESSCOOKIEAPI=0190df6e720daaa9; path=/; HttpOnly
X-Cache: Miss from cloudfront
Via: 1.1 3b6239c61689b2727182c34a97307648.cloudfront.net (CloudFront)
X-Amz-Cf-Pop: BUD50-C1
X-Amz-Cf-Id: MM6SIVal3FXYfjQ4Z0ohK76GCZBa4DBhxQg5AHwRVOMkhcgjbx4OhA==

{

  "user": {

    "termsAndConditions": false,
    "timezone": "+00:00",
    "pictureUrl": "http://www.gravatar.com/avatar/fec77cc55cf4ba4176609cfec69a25d6",
    "customerSettings": {

      "sysdig": {

        "enabled": false,
        "enabledSSE": false,
        "buckets": []
      },
      "plan": {

        "maxAgents": 0,
        "onDemandAgents": 0,
        "maxTeams": -1,
        "timelines": [

          {

            "from": null,
            "to": null,
            "sampling": 10000000
          },
          {

            "from": null,
            "to": null,
            "sampling": 60000000
          },
          {

            "from": null,
            "to": null,
            "sampling": 600000000
          },
          {

            "from": null,
            "to": null,
            "sampling": 3600000000
          },
          {

            "from": null,
            "to": null,
            "sampling": 86400000000
          }
        ],
        "metricsSettings": {

          "enforce": false,
          "showExperimentals": false,
          "limits": {

            "jmx": 500,
            "statsd": 1000,
            "appCheck": 500,
            "prometheus": 1000,
            "prometheusPerProcess": 500,
            "connections": 80,
            "progAggregationCount": 12,
            "appCheckAggregationCount": 12,
            "promMetricsWeight": 0.0,
            "topFilesCount": 10,
            "topDevicesCount": 10,
            "hostServerPorts": 10,
            "containerServerPorts": 5,
            "limitKubernetesResources": false,
            "kubernetesPods": 10000,
            "kubernetesJobs": 10000,
            "containerDensity": 200,
            "meerkatSuited": false
          },
          "enforceAgentAggregation": false,
          "enablePromCalculatedIngestion": true
        },
        "secureEnabled": true,
        "monitorEnabled": true,
        "allocatedAgentsCount": 25,
        "subscriptionState": "active",
        "paymentsIntegrationId": {

          "id": "19656859",
          "ttl": {

            "ttl": 3
          }
        },
        "pricingPlan": "pro",
        "indirectCustomer": true,
        "trialPlanName": "monitor-14",
        "partner": "None",
        "overageAssessmentEligible": true
      },
      "environment": {}
    },
    "customer": {

      "id": 1,
      "name": "sdc-admin",
      "accessKey": "7a412697-3ac6-421a-a901-0d07c2eb6071",
      "externalId": "a6742502-9cf0-4595-a9d4-8247bd29c6a0",
      "dateCreated": 1428687374000
    },
    "oauth": false,
    "agentInstallParams": {

      "accessKey": "7a412697-3ac6-421a-a901-0d07c2eb6071",
      "collectorAddress": "collector-static.sysdigcloud.com",
      "collectorPort": 6443,
      "checkCertificate": true,
      "sslEnabled": true
    },
    "properties": {

      "has_been_invited": true
    },
    "resetPassword": false,
    "additionalRoles": [],
    "teamRoles": [

      {

        "teamId": 2674,
        "teamName": "Full Infrastructure",
        "teamTheme": "#7BB0B2",
        "userId": 48199,
        "userName": "testuser@company",
        "role": "ROLE_TEAM_EDIT",
        "admin": false
      }
    ],
    "lastUpdated": 1612202103000,
    "dateActivated": 1612202103000,
    "accessKey": "7a412697-3ac6-421a-a901-0d07c2eb6071",
    "intercomUserIdHash": "80d29ebc391c94718fc0fb28f3d80df973741fb1765675fd69420cf314ed2cdf",
    "uniqueIntercomUserId": "48199.a6742502-9cf0-4595-a9d4-8247bd29c6a0",
    "enabled": false,
    "version": 1,
    "id": 48199,
    "products": [

      "SDC"
    ],
    "systemRole": "ROLE_USER",
    "username": "testuser@company",
    "status": "registered",
    "dateCreated": 1612202103000
  },
  "token": {

    "key": "<user_key>"
  }
}

7 -

Working with Alert APIs

• Silencing Rules API

7.1 -

Silencing Rules API

The Silencing Rules Management API provides programmatic access to silence Sysdig Alert notifications.

REST Resource: silencingRules

See Sysdig REST API Conventions  for generic conventions and authentication.

List Alert Silence Rules

List all the active silencing rules for a user or team.

GET api/v1/silencingRules

No request parameters.

Create Alert Silence Rule

Create a new alert silence rule.

POST /api/v1/silencingRules

Request Parameters

{
  "id" : 69256,
  "version" : 1,
  "createdOn" : 1621613672203,
  "modifiedOn" : 1621613672203,
  "customerId" : 12,
  "teamId" : 9129,
  "name" : "test",
  "enabled" : true,
  "startTs" : 1621613669000,
  "durationInSec" : 3600,
  "scope" : "access_mode in (\"ReadWrite\")",
  "notificationChannelIds" : [ 365234 ]
}

List a Silence Rule

List a specific silence rule.

GET /api/v1/silencingRules/{silencingRuleId}

Request Variables

[ {
  "id" : 3452,
  "version" : 4,
  "createdOn" : 1617723973937,
  "modifiedOn" : 1617727511021,
  "customerId" : 1,
  "teamId" : 919,
  "name" : "Holidays",
  "enabled" : false,
  "startTs" : 1617723900000,
  "durationInSec" : 3600,
  "scope" : "cluster in (\"demoenv\")",
  "notificationChannelIds" : [ 95623 ]
}]

Update a Silence Rule

Update a specific silence rule.

PUT /api/v1/silencingRules/{silencingRuleId}

Request Variables

{
  "id" : 69256,
  "version" : 1,
  "createdOn" : 1621613672203,
  "modifiedOn" : 1621613672203,
  "customerId" : 12,
  "teamId" : 9129,
  "name" : "test",
  "enabled" : true,
  "startTs" : 1621613669000,
  "durationInSec" : 3600,
  "scope" : "access_mode in (\"ReadWrite\")",
  "notificationChannelIds" : [ 365234 ]
}

Delete a Silencing Rule

Delete a silencing rule.

DELETE /api/v1/silencingRules/{silencingRuleId}

Request Variables

Delete All the Silencing Rules

Delete all the requested silencing rules.

POST /api/v1/silencingRules/delete

Request Variables

{
  "silencingRules": {
    "ids": [
      c
    ]
  }
}

Disable Silencing Rules

Disable all the requested silencing rules.

PATCH /api/v1/silencingRules/disable

Request Variables

{
  "silencingRules": {
    "ids": [
      9256, 34, 2345
    ]
  }
}

Enable Silencing Rules

Enable all the requested silencing rules.

PATCH /api/v1/silencingRules/enable

Request Variables

{
  "silencingRules": {
    "ids": [
      6920, 23
    ]
  }
}

8 -

Working with Dashboards

Learn how to programmatically interact with Sysdig Dashboards:

• Dashboard APIs

• Save and Restore Dashboards with Scripts

8.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
    }
}

8.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.

8.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.

9 -

Working with the Data API

The data API provides access to the labels and metrics data captured by Sysdig agents and stored in the Sysdig datastores. Sysdig agents capture process, network, system and other infrastructure data with a 1-second resolution, and sends them to the Sysdig worker service with a 10-second resolution.

The data API allows you to fetch data at the native resolution of 10-second or lower. You can specify the resolution to return data via the sampling parameter. Each resolution has different data retention periods. Since native data capturing is performed with a 1-second resolution, for each metric you need to specify a time aggregation.Data Retention

Similarly, data associated with individual pods, processes, and so can be aggregated at a higher level. For example, at the host or namespace level. This type of aggregation depends on the list of labels you specify. For instance, you could aggregate data at the host level by specifying a host label. For this to work, you need to specify a group aggregation.

To learn more about data aggregation, see Data Aggregation.

General Guidelines for Using the Data API

• The maximum number of samples you can fetch via the data API is 600. Consequently, the larger the time window for the data retrieval, the lower the resolution will be.

• The API enforces a response timeout of 30 seconds. Larger time windows, a higher number of metrics, multiple segments (higher number of columns and rows) might cause a longer response time.

• Some labels might not apply to certain entities. When those labels are retrieved, the label value will be null.

• Due to a current limitation, the same metric name cannot be specified more than once independent of the aggregations.

REST Resource: Data

See Sysdig REST API Conventions for generic conventions and authentication.

Request Variables

(not) label operator value

POST /api/data
{
"filter": "kubernetes.node.name = 'n1'",
…

"metrics": [
    {"id": "container.name"},
    {
      "id": "cpu.cores.used",
      "aggregations": { "time": "avg", "group": "avg" }
    }

Response Variables

Sample Request and Response

In this example, CPU cores for containers are retrieved.

POST /api/data

{
  "last": 600,
  "sampling": 600,
  "filter": null,
  "metrics": [
    {
      "id": "cpu.cores.used",
      "aggregations": { "time": "avg", "group": "sum" }
    }
  ],
  "dataSourceType": "container",
  "paging": {
    "from": 0,
    "to": 99
  }
}

Given below is a sample response :

{
    "data": [
        {
            "t": 1582756200,
            "d": [
                6.481
            ]
        }
    ],
    "start": 1582755600,
    "end": 1582756200
}

Python Script Library for Data API

Sysdig Python client for interacting with the Data API. See Python SDC Client for comprehensive examples and documentation.

Function: sysdig_api.get_data

sdclient.get_data(metrics,start_ts,end_ts,sampling_s,filter,paging,datasource_type)

Returns the requested metrics data.

Arguments

Successful Return Value

Returns the requested metrics data in a JSON file.

Sample Script

ok, res = sysdig_api.get_data(
  start_ts = -600,
  end_ts = 0,
  sampling_s = 600,
  filter = None,
  metrics = [
    {
      "id": "cpu.cores.used",
      "aggregations": {
          "time": "avg",
          "group": "sum"
      }
    }
  ],
  datasource_type = "container",
  paging = {"from": 0, "to": 99}
)