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.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.
Log in to Sysdig Monitor or Sysdig Secure and select Settings.
Select User Profile.The Sysdig Monitor or Sysdig Secure API token
is displayed (depending on which interface and team you logged in
to).
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:
Use the Pip Command
Install the client by using pip:
Identify Your API Server
SAAS
Check the drop-down to verify the API URL you should use in the client installation script.
The default region is US East and the URL is app.sysdig.cloud.com.
On-Premises
For the On-Premises Sysdig platform installations, you need to use the hostame or IP where your Sysdig API server is running.
Option 1
To do so, set the following environment variables before running your Python scripts:
export SDC_URL='https://<YOUR-API-SERVER-HOSTNAME-OR-IP>'
If you are using a self-signed certificate, set following variable:
export SDC_SSL_VERIFY='false'
Disable the SSL verification only if you don’t have a valid certificate.
Option 2
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 the output, see 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
4 - 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:
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:
Handle resources
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": { ... }
}
5 - Creating Access Keys
The Access Key is a token that you must configure on Sysdig agents to
successfully forward data from your environment to the Sysdig
backend. 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:
Retrieve the Sysdig API token from the Sysdig UI.
For more information, see Retrieve the Sysdig API
Token.
Issue a request against the Sysdig endpoint to generate a
new access key:
$ curl -XPOST -H 'Authorization: Bearer API_TOKEN' https://<your_endpoint>/api/customer/accessKeys
Replace the following:
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 instance, do the
following:
Retrieve the API token from the Sysdig UI.
For more information, see Retrieve the Sysdig API
Token.
Issue a curl GET request against the Sysdig Monitor endpoint to
enable the given access key:
$ curl -XGET -H 'Authorization: Bearer API_TOKEN' https://<your_endpoint>/api/customer/accessKeys
Replace the following:
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:
Retrieve the API token from the Sysdig UI.
For more information, see Retrieve the Sysdig API
Token.
Issue a curl POST request against the Sysdig Monitor or Secure endpoint to
disable the given access key.
$ curl -XPOST -H 'Authorization: Bearer API_TOKEN' https://<your_endpoint>/api/customer/accessKeys/ACCESS_KEY/disable
Replace the following:
API_TOKEN with the token you retrieved in step 1.
<your_endpoint > 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 data to the Sysdig backend.
Deleting access keys is not supported at this time.
Enabling an Access Key
To enable an existing access key:
Retrieve the API token from the Sysdig UI.
For more information, see Retrieve the Sysdig API
Token.
Issue a curl POST request against the Sysdig Monitor endpoint to
enable the given access key.
$ curl -XPOST -H 'Authorization: Bearer API_TOKEN' https://<your_endpoint>/api/customer/accessKeys/ACCESS_KEY/enable
Replace the following:
API_TOKEN with the token you retrieved in step 1.
<your_endpoint > with your Sysdig
endpoint associated
with your region.
ACCESS_KEY with the access key that you wish to disable.
Restart the agents for the new connection to work as expected.
The agent that connects with a disabled access key will be
terminated.
6 - [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
Available Audit APIs
The following APIs are available to support the audit log feature.
AppAttributes
AppAttributes enables registering audit logs in Sysdig.
Base URL
https://<ip>/api/admin/appAttributes
Request Parameters
Request ParametersID | 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 auditEventscustomerId | 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 ParameterscustomerId | 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"
}
}
7 - 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.
The two primary flows for add passwords are:
Provision a user that is a real person:
- Create the user
- Leave the password blank
- Tell the user to login and reset the password
Provision a user as a service account, someone that doesn’t login
- Create the user
- Put a password in that only the admin knows, or is stored in something like Vault
- Use that password to build an api service without ever logging in
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
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. |
First and Last Name (optional) | String The first and last name of the account. |
Response Parameters
| Field | Description |
|---|
| User data | The user data such as user plan. |
| Token | The 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>"
}
}
Example Account Creation without Activation Email
Sample Curl Command
curl -k -XPOST -H 'Authorization: Bearer 69a4a069-f743-4f3b-a441-4e9424011ae2' \
-H 'Content-Type: application/json' \
-d '{"username": "andrew.d+1@sysdig.com", "password": "abc123"}' \
https://sysdig.f.lan:30001/api/user/provisioning/
Sample Result
{
"user":{
"termsAndConditions":true,
"timezone":"+00:00",
"pictureUrl":"http://www.gravatar.com/avatar/4b760b68a17be552fcc8b04503af80ca",
"customerSettings":{
"sysdig":{
"enabled":false,
"enabledSSE":false,
"buckets":[
]
},
"plan":{
"maxAgents":50,
"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":true,
"enablePromScrapeV2":true
},
"secureEnabled":true,
"monitorEnabled":true,
"allocatedAgentsCount":15,
"paymentsIntegrationId":{
"id":"not migrated",
"ttl":{
"ttl":50
}
},
"pricingPlan":"onpremise",
"indirectCustomer":false,
"trialPlanName":"monitor-14",
"partner":"None",
"trackingCustomerId":"001j000000nA0ICAA0",
"licenseExpirationDate":1677888000000,
"migratedToV2Direct":false,
"overageAssessmentEligible":false
},
"environment":{
}
},
"customer":{
"id":1,
"name":"andrew_dean_lab7a",
"accessKey":"87cfcbbf-b0a8-47ee-afcb-f7b6eab7e53d",
"externalId":"a79da4ff-c11d-44a7-9024-2da0f75d3e6b",
"dateCreated":1646363720071
},
"oauth":false,
"agentInstallParams":{
"accessKey":"87cfcbbf-b0a8-47ee-afcb-f7b6eab7e53d",
"collectorAddress":"sysdig.f.lan",
"collectorPort":6443,
"checkCertificate":true,
"sslEnabled":true
},
"properties":{
"has_been_invited":true
},
"resetPassword":false,
"additionalRoles":[
],
"teamRoles":[
{
"teamId":2,
"teamName":"Secure Operations",
"teamTheme":"#7BB0B2",
"userId":3,
"userName":"andrew.d+1@sysdig.com",
"role":"ROLE_TEAM_EDIT",
"admin":false
}
],
"lastUpdated":1647395152277,
"dateActivated":1647395152231,
"accessKey":"87cfcbbf-b0a8-47ee-afcb-f7b6eab7e53d",
"intercomUserIdHash":"0bd0606ccad9e877024d6f11a371663a1c3134b7660a3419f1b15dda844cfe45",
"uniqueIntercomUserId":"3.a79da4ff-c11d-44a7-9024-2da0f75d3e6b",
"enabled":true,
"version":1,
"status":"confirmed",
"systemRole":"ROLE_USER",
"products":[
"SDS"
],
"username":"andrew.d+1@sysdig.com",
"dateCreated":1647395152238,
"name":"andrew.d+1@sysdig.com",
"id":3
},
"token":{
"key":"61d42285-5f36-4cc9-82da-b124ede9434d"
}
}
8 - Working with Alert APIs
Alert APIs
Sysdig provides some REST APIs to perform CRUD (create, read, update, and delete) operations with alerts. Both
admin and non-admin users can use these APIs hosted on Swagger to create, update, list, read, and delete alerts. See https://app.sysdigcloud.com/api/public/docs/index.html#tag/Alerts-V2 for the API documentation. Replace app.sysdig.com with the URL associated with your region to access the API endpoints and documentation in your region.
For information on Sysdig users and system-based privileges, see User and Team Administration.
Silencing Rules API
The Silencing Rules Management API provides programmatic access to silence Sysdig Alert notifications. See the https://app.sysdigcloud.com/api/public/docs/index.html#tag/Silencing-Rules for the API documentation. Replace app.sysdig.com with the URL associated with your region.
REST Resource: silencingRules
See Sysdig REST API
Conventions for generic
conventions and authentication.
9 - Working with Dashboards
Dashboard APIs
Sysdig provides REST APIs to perform CRUD (create, read, update, and delete) operations with Dashboards. Both
admin and non-admin users can use these APIs hosted on Swagger to create, update, list, read, and delete Dashboards. See https://app.sysdigcloud.com/api/public/docs/index.html#tag/Dashboard-V3 for the API documentation. Replace app.sysdigcloud.com with the URL associated with your region to access the API endpoints and documentation in your region.
For information on Sysdig users and system-based privileges, see User and Team Administration.
Migrate Dashboards from V2 to V3
To convert a dashboard in V2 to V3, you can use the convertV2ToV3 API.
To convert Dashboad widgets in V2 to Dashboard V3 panels, you can use the convertWidgetsToPanels API. Replace app.sysdig.com with the URL associated with your region.
10 - 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.
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
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; |
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: value is one of the following:
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
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 https://<your-Sysdig-URL>/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
}
}
Ensure that you replace with your Sysdig URL associated with your region. For example:
POST https://us2.app.sysdig.com/api/data/
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
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}
)
