This the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

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

                          Developer Tools

                          Sysdig provides some REST APIs and a Python Script Library to extend the functions of the Sysdig Monitor and Secure capabilities over a public API. Sysdig also provides a basic CLI for both products.

                          This section covers:

                          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.

                          The Sysdig Platform is built on the Sysdig REST API, a few functions of which have been documented for public consumption. Until the REST API is more formally documented, we just provide some basic conventions; see Sysdig REST API Conventions.

                          Learn more about using the sdcclient library and scripts:

                          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:

                          add_notification_email.py
                          add_policy.py
                          add_users_to_secure.py
                          create_alert.py
                          create_dashboard.py
                          create_default_policies.py
                          create_sysdig_capture.py
                          dashboard.py
                          dashboard_save_load.py
                          delete_alert.py
                          delete_all_policies.py
                          delete_dashboard.py
                          delete_event.py
                          delete_policy.py
                          download_dashboards.py
                          flip_alerts_enabled.py
                          get_agents_config.py
                          get_data_advanced.py
                          get_data_datasource.py
                          get_data_simple.py
                          get_policy.py
                          get_secure_default_falco_rules_files.py
                          get_secure_policy_events.py
                          get_secure_system_falco_rules.py
                          get_secure_user_falco_rules.py
                          list_admins.py
                          list_alert_notifications.py
                          list_alerts.py
                          list_dashboards.py
                          list_events.py
                          list_hosts.py
                          list_metrics.py
                          list_policies.py
                          list_sysdig_captures.py
                          list_users.py
                          notification_channels.py
                          post_event.py
                          post_event_simple.py
                          print_conn_table.py
                          print_data_retention_info.py
                          print_explore_grouping.py
                          print_user_info.py
                          resolve_alert_notifications.py
                          restore_alerts.py
                          restore_dashboards.py
                          set_agents_config.py
                          set_explore_group_configuration.py
                          set_policy_order.py
                          set_secure_default_falco_rules_files.py
                          set_secure_system_falco_rules.py
                          set_secure_user_falco_rules.py
                          update_alert.py
                          update_policy.py
                          user_team_mgmt.py
                          user_team_mgmt_extended.py

                          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

                          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

                          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:

                          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

                          Parameters

                          Description

                          ID

                          Unique ID of the feature: auditLogEnabled

                          Value

                          True indicates audit log is turned on.

                          False indicates audit log is turned off.

                          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

                          Parameters

                          Description

                          customerId

                          The unique ID of the user.

                          username

                          The username of the account that accessed the system.

                          requestMethod

                          Type of request method.

                          Supported methods are GET and PUT.

                          requestUri

                          /api/admin/appAttributes

                          queryString

                          A set of characters passed to retrieve specific information.

                          responseStatus

                          HTTP Response status code.

                          responseReasonPhrase

                          The response from the API server.

                          dateCreated

                          The date on which the event is created.

                          lastUpdated

                          The date when the event was last modified.

                          From

                          Indicates the date and time when Sysdig started recording auditable events.

                          Date format is YYYY-MM-DD HH:MM:SS.

                          To

                          Indicates the date and time when Sysdig stopped recording auditable events.

                          Date format is YYYY-MM-DD HH:MM:SS.

                          Request Parameters of auditEvents

                          Response Parameters

                          Response Parameters

                          Parameters

                          Description

                          customerId

                          The unique ID of the user.

                          username

                          The username of the account that accessed the system.

                          requestMethod

                          Type of request method.

                          Supported methods are GET and PUT.

                          requestUri

                          The URI to identify the resource.

                          /api/admin/appAttributes

                          queryString

                          A set of characters passed to retrieve specific information.

                          responseStatus

                          The HTTP Response status code.

                          responseReasonPhrase

                          The response from the API server.

                          dateCreated

                          The date on which the event is created.

                          lastUpdated

                          The date when the event was last modified.

                          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

                          Field

                          Description

                          Username

                          (mandatory)

                          String

                          The username should be in the format of an email address. The email address need not be functional.

                          Password

                          (optional)

                          String

                          The password associated with the username you have provided. If not specified, a password is auto-generated by using a secure random generator.

                          First and Last Name

                          (optional)

                          String

                          The first and last name of the account.

                          Response Parameters

                          FieldDescription
                          User dataThe user data such as user plan.
                          TokenThe unique token string association with the user created.

                          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

                          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.

                          api/v1/silencingRules
                          

                          No request parameters.

                          Create Alert Silence Rule

                          Create a new alert silence rule.

                          POST /api/v1/silencingRules
                          

                          Request Parameters

                          Field

                          Description

                          SilencingRuleDTO

                          Specify the following:

                          • customerId: The unique ID of the user. An Integer value.

                          • createdOn: The timestamp at which the silencing rule is created. An Integer value.

                          • durationInSec: The duration of silence rule in second. An Integer value.

                          • enabled: Indicate if the silencing rule is enabled or not. A Boolean value.

                          • modifiedOn: Indicate when the rule is modified. An Integer value.

                          • name: The unique name of the silencing rule. A String value.

                          • notificationChannelIds: The unique IDs of the notification channel. An Integer value.

                          • Id: The unique ID of the silence rule. An Integer value.

                          • startTs: The start time of the silence rule in milliseconds. An Integer value.

                          • scope: The unique ID of the infrastructure entity to apply the scope as. For example, a particular workload or namespace, from environments that may include thousands of entities. An String value.

                          • teamId: The unique ID of the team that this silencing rule belongs to. An Integer value.

                          • version: The version number corresponding to the revision of the silencing rule. An Integer value.

                          For example:

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

                          Field

                          Description

                          silencingRuleId

                          The unique ID of a silence rule.

                          An example:

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

                          Field

                          Description

                          alertId

                          Int 64

                          The unique ID of the alert.

                          alertSilencingRuleDTO

                          Specify the following:

                          • customerId: The unique ID of the user. An Integer value.

                          • createdOn: The timestamp at which the silencing rule is created. An Integer value.

                          • durationInSec: The duration of silence rule in second. An Integer value.

                          • enabled: Indicate if the silencing rule is enabled or not. A Boolean value.

                          • modifiedOn: Indicate when the rule is modified. An Integer value.

                          • name: The unique name of the silencing rule. A String value.

                          • notificationChannelIds: The unique IDs of the notification channel. An Integer value.

                          • Id: The unique ID of the silence rule. An Integer value.

                          • startTs: The start time of the silence rule in milliseconds. An Integer value.

                          • scope: The unique ID of the infrastructure entity to apply the scope as. For example, a particular workload or namespace, from environments that may include thousands of entities. An String value.

                          • teamId: The unique ID of the team that this silencing rule belongs to. An Integer value.

                          • version: The version number corresponding to the revision of the silencing rule. An Integer value.

                          For example:

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

                          FieldDescription
                          silencingRuleIdThe unique ID of a silence rule.

                          Delete All the Silencing Rules

                          Delete all the requested silencing rules.

                          POST /api/v1/silencingRules/delete
                          

                          Request Variables

                          Field

                          Description

                          bulkRequestWrappe

                          Specify the unique IDs of the silence rules.

                          For example:

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

                          Disable Silencing Rules

                          Disable all the requested silencing rules.

                          POST /api/v1/silencingRules/disable
                          

                          Request Variables

                          Field

                          Description

                          bulkRequestWrappe

                          Specify the unique IDs of the silence rules.

                          For example:

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

                          Enable Silencing Rules

                          Enable all the requested silencing rules.

                          POST /api/v1/silencingRules/enable
                          

                          Request Variables

                          Field

                          Description

                          bulkRequestWrappe

                          Specify the unique IDs of the silence rules.

                          For example:

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

                          8 -

                          Working with Dashboards

                          Learn how to programmatically interact with Sysdig Dashboards:

                          8.1 -

                          Dashboard APIs

                          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.

                          REST Resource: Dashboard

                          List all Dashboards

                          GET /api/v2/dashboards
                          
                          Request Parameters

                          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 light parameter is true, in the response body each object will only have the following attributes: id, version, name, teamId, username, schema, autoCreated, shared, public, publicToken, createdOn, modifiedOn

                          Request Parameters

                          Sample Response

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

                          Status Codes

                          CodeDescription
                          200Indicates if the Dashboard has been successfully created.
                          401Indicates that the requested resource is restricted and requires authentication, but you failed to provide any such authentication.
                          403Indicates you are unauthorized to access the Dashboard.
                          404Indicates the Dashboard is not found.

                          Get a Dashboard by ID

                          GET /api/v2/dashboards/{id}
                          
                          Request Parameters

                          Field

                          Description

                          id

                          Integer (int64)

                          The unique ID of the Dashboard.

                          Request Parameters

                          Sample Response

                          See JSON Representation

                          Status Codes

                          CodesDescription
                          200Indicates if the Dashboard has been successfully created.
                          401Indicates that the requested resource is restricted and requires authentication, but you failed to provide any such authentication.
                          403Indicates you are unauthorized to access the Dashboard.
                          404Indicates a Dashboard is not found.

                          Create a Dashboard

                          Create a new Dashboard.

                          POST /api/v2/dashboards
                          
                          Request and Response Parameters

                          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:

                          • displayName

                          • isVaribale

                          • operator

                          • operand

                          • value

                          • variable

                          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:

                          • customDisplayOptions

                          • valueLimit

                          • xAxis

                          • yAxisLeftDomain

                          • yAxisRightDomain

                          • yAxisScale

                          • gridConfiguration

                          • name

                          • showAs

                          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

                          CodeDescription
                          200Indicates if the Dashboard has been successfully created.
                          401Indicates that the requested resource is restricted and requires authentication, but you failed to provide any such authentication.
                          403Indicates you are unauthorized to access the Dashboard.
                          422Indicates validation errors.

                          Update a Dashboard

                          PUT /api/v2/dashboards/{id}
                          
                          Request Parameters

                          Field

                          Description

                          ID

                          Integer (int64)

                          The unique ID of the dashboard.

                          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

                          CodeDescription
                          200Indicates if the Dashboard has been successfully updated.
                          401Indicates that the requested resource is restricted and requires authentication, but you failed to provide any such authentication.
                          403Indicates you are unauthorized to access the Dashboard.
                          404Indicates a Dashboard is not found.
                          406Indicates validation errors.
                          422Indicates conflicts while saving the Dashboard.

                          Delete a Dashboard

                          You can delete a Dashboard by a customer ID.

                          DELETE /api/v2/dashboards/{id}
                          
                          Request Parameters

                          Field

                          Description

                          Id

                          Integer (int32)

                          The unique identification code of the Dashboard.

                          Request Parameters

                          Sample Response

                          See JSON Representation.

                          Status Codes

                          CodeDescription
                          200Indicates if the Dashboard has been successfully deleted.
                          401Indicates that the requested resource is restricted and requires authentication, but you failed to provide any such authentication.
                          403Indicates you are unauthorized to access the Dashboard.
                          404Indicates a Dashboard is not found.

                          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.

                          Restoring dashboards will not override the user’s existing dashboards. Instead, new dashboards will be added to the list.

                          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

                          V1 Fields

                          Schema Changes

                          V2 Fields

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

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

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

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

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

                            • Set isVariable to false.

                            • Set displayName to an empty string.

                          scopeExpressionList

                          Show Dashboard Events

                          V1 Fields

                          Schema Changes

                          V2 Fields

                          eventsFilter

                          Rename to eventsOverlaySettings.

                          The following properties are deprecated:

                          • showNotificationsDoNotFilterSameMetrics

                          • showNotificationsDoNotFilterSameScope

                          eventsOverlaySettings

                          Share Dashboard with Team

                          V1 Fields

                          Schema Changes

                          V2 Fields

                          isShared

                          Rename to shared.

                          shared

                          Share Public URL

                          V1 Fields

                          Schema Changes

                          V2 Fields

                          isPublic

                          Rename to public.

                          public

                          Dashboard Panels

                          V1 Fields

                          Schema Changes

                          V2 Fields

                          items

                          Rename to widgets.

                          widgets

                          General Changes

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

                          Panel Elements

                          V1 Fields

                          Schema Changes

                          V2 Fields

                          items
                          • Rename to widgets

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

                          • The showAsType and id properties are deprecated.

                          • The sorting and paging properties are deprecated.

                          • The yAxisScaleFactor property inside customDisplayOptions is deprecated.

                          widgets

                          metrics

                          • Change metricId to id.

                          • Chane aggregation to timeAggregation.

                          metrics

                          All the Panels Except Topology

                          V1 FieldsSchema ChangesV2 Fields
                          widgets without showAs=mapThe group property is deprecated.widgets without showAs=map

                          Number Panel

                          V1 Fields

                          Schema Changes

                          V2 Fields

                          widgets with showAs set to summary

                          In V1, an array is formed as follows:

                          • Includes exactly three objects.

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

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

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

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

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

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

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

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

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

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

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

                          For V2 schema, do the following:

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

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

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

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

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

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

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

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

                          widgets with showAs=summary

                          Topology Panel

                          VI Fields

                          Schema Changes

                          V2 Fields

                          widgets with showAs=map

                          Rename group to groupingLabelIds and do the following:

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

                          [{ labelId: "host.mac" }]

                          widgets with showAs=map

                          Text Panel

                          VI Fields

                          Schema Changes

                          V2 Fields

                          widgets with showAs=text

                          • Change hasTransparentBackground to transparentBackground.

                          • Change isPanelTitleVisible to panelTitleVisible.

                          • Change isTextAutosized to textAutosized.

                          widgets with showAs=text

                          Learn More

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

                          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

                          Field

                          Description

                          last

                          Specifies the time window. The timestamp is expressed in seconds.

                          start

                          end

                          An alternative to last to specify the time window.

                          The timestamp is expressed in seconds.

                          sampling

                          Data resolution expressed in seconds. Sampling gives a single aggregated value across the entire window. It's value can be one of the following;

                          • end - start

                          • last

                          filter

                          Specifies the scope for the data to be returned. The simple expression to filter out data is:

                          (not) label operator value

                          The filter can also be a set of expressions, for instance, expr1 AND expr2 OR expr3.

                          • label: Any label that allows for segmentation

                          • operator: Supported operators are:

                            • =

                            • !=

                            • in

                            • contains

                            • starts with

                          • value is one of the following:

                            • single value

                            • list of values

                            • null (supported with = and != operators only)

                          For example:

                          POST /api/data
                          

                          { "filter": "kubernetes.node.name = 'n1'", …

                          metrics

                          Specifies labels or metrics, or both, to be returned. Labels require only the ID, whereas metrics require ID as well as the time and group aggregations.

                          Time aggregations: timeAvg (rate), average, minimum, maximum, sum

                          Group aggregations: average, minimum, maximum, sum

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

                          The first metric requested in the query is the container name. This is a segmentation metric, and therefore, no aggregation criteria is specified. This second metrics queries for CPU utilization of each container separately. The metric is aggregated as an average.

                          dataSourceType

                          Specifies the type of entity for which metrics are retrieved. This is particularly useful when the same metric name, for instance cpu.cores.used, is used for different sources.

                          Accepted values: host and container.

                          paging

                          Specifies the number of rows of data to be returned. By default, rows from 0 to 9 (10 rows) are returned. Pagination is applied to the sorted rows according to the following criteria:

                          • If a metric is available, sort by first metric value (descending)

                          • If a metric is unavailable, sort by first label value (descending)

                          Response Variables

                          Field

                          Description

                          data

                          Returns a list of data points.

                          Each data point is uniquely identified by timestamp and a list of label values.

                          t: timestamp expressed in seconds.

                          d: list of values representing labels and metrics, sorted as given in the request.

                          start

                          end

                          Returns the actual time window of the drawn data.

                          It may be different from the time when the API requested for data (eg. to align to timelines)

                          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

                          Arguments

                          Description

                          start_ts

                          Start of a query time window. The timestamp is expressed in seconds.

                          end_ts

                          End of a query time window. The timestamp is expressed in seconds.

                          sampling_s

                          Data resolution expressed in seconds.

                          filter

                          Specifies the scope for the data to be returned.

                          metrics

                          List of metrics to query.

                          datasource_type

                          The source for the metrics.

                          Accepted values: host and container.

                          paging

                          Specifies the number of rows of data to be returned. By default, rows from 0 to 9 (10 rows) are returned.

                          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}
                          )