tweaks

Author: gianlucaborello

README.md

@@ -28,7 +28,20 @@ Usage
 
 _Note:_ in order to use this API you must obtain a Sysdig Cloud token. You can get your user's token in the _Sysdig Cloud API_ section of the [settings](https://app.sysdigcloud.com/#/settings/user) page.
 
-The library exports a single class, `SdcClient`, that is used to connect to Sysdig Cloud and execute actions.
+The library exports a single class, `SdcClient`, that is used to connect to Sysdig Cloud and execute actions. It can be instantiated like this:
+
+``` python
+from sdcclient import SdcClient
+
+sdc_token = "MY_API_TOKEN"
+
+#
+# Instantiate the SDC client
+#
+sdclient = SdcClient(sdc_token)
+```
+
+Once instantiated, all the methods documented below can be called on the object.
 
 ####Return Values
 Every method in the SdcClient class 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:
@@ -97,6 +110,21 @@ A dictionary showing the details of the new dashboard.
 **Example**  
 [examples/create_dashboard.py](examples/create_dashboard.py).  
 
+#### `create_sysdig_capture(self, hostname, capture_name, duration, capture_filter='', folder='/')`  
+**Description**  
+Create a new sysdig capture. The capture will be immediately started.  
+**Arguments**  
+- **hostname**: the hostname of the instrumented host where the capture will be taken.
+- **capture_name**: the name of the capture.
+- **duration**: the duration of the capture, in seconds.  
+- **capture_filter**: a sysdig filter expression.  
+- **folder**: directory in the S3 bucket where the capture will be saved.
+
+**Success Return Value**  
+A dictionary showing the details of the new capture.  
+**Example**  
+[examples/create_sysdig_capture.py](examples/create_sysdig_capture.py).  
+
 #### `delete_alert(self, alert)`  
 **Description**  
 Deletes an alert.  
@@ -200,13 +228,17 @@ A dictionary containing the list of available metrics.
 **Example**  
 [examples/list_metrics.py](examples/list_metrics.py).  
 
+#### `get_connected_agents(self)`  
+**Description**  
+Return the agents currently connected to Sysdig Cloud for the current user.  
+**Success Return Value**  
+A list of the agents with all their attributes.  
+
 #### `get_n_connected_agents(self)`  
 **Description**  
 Return the number of agents currently connected to Sysdig Cloud for the current user.  
 **Success Return Value**  
 An integer number.  
-**Example**  
-[examples/print_user_info.py](examples/print_user_info.py).  
 
 #### `get_notifications(self, from_ts, to_ts, state=None, resolved=None)`
 **Description**  
@@ -222,17 +254,13 @@ A dictionary containing the list of notifications.
 **Example**  
 [examples/list_alert_notifications.py](examples/list_alert_notifications.py). 
 
-#### `update_notification_resolution(self, notification, resolved)`
+#### `get_sysdig_captures(self)`
 **Description**  
-Updates the resolution status of an alert notification.  
-**Arguments**  
-- **notification**: notification object as returned by `get_notifications()`. 
-- **resolved**: new resolution status. Supported values are `True` and `False.
-
+Returns the list of sysdig captures for the user.  
 **Success Return Value**  
-The updated notification.  
+A dictionary containing the list of captures.  
 **Example**  
-[examples/resolve_alert_notifications.py](examples/resolve_alert_notifications.py). 
+[examples/list_sysdig_captures.py](examples/list_sysdig_captures.py). 
 
 #### `get_user_info(self)`  
 **Description**  
@@ -242,6 +270,17 @@ A dictionary containing information about the user, for example its email and th
 **Example**  
 [examples/print_user_info.py](examples/print_user_info.py).  
 
+#### `poll_sysdig_capture(self, capture)`  
+**Description**  
+Fetch the updates state of a sysdig capture. Can be used to poll the status of a capture that has been previously created and started with `create_sysdig_capture`.  
+**Arguments**  
+- **capture**: the capture object as returned by `get_sysdig_captures()` or `create_sysdig_capture()`.
+
+**Success Return Value**  
+A dictionary showing the updated details of the capture. Use the `status` field to check the progress of a capture.    
+**Example**  
+[examples/create_sysdig_capture.py](examples/create_sysdig_capture.py).  
+
 #### `post_event(self, name, description=None, severity=6, host=None, tags=None)`
 **Description**  
 You can use this method you use to send an event to Sysdig Cloud. The events you post are available in the Events tab in the Sysdig Cloud UI and can be overlied to charts.  
@@ -256,3 +295,15 @@ You can use this method you use to send an event to Sysdig Cloud. The events you
 A dictionary describing the new event.  
 **Example**  
 [examples/post_event.py](examples/post_event.py).  
+
+#### `update_notification_resolution(self, notification, resolved)`
+**Description**  
+Updates the resolution status of an alert notification.  
+**Arguments**  
+- **notification**: notification object as returned by `get_notifications()`. 
+- **resolved**: new resolution status. Supported values are `True` and `False.
+
+**Success Return Value**  
+The updated notification.  
+**Example**  
+[examples/resolve_alert_notifications.py](examples/resolve_alert_notifications.py). 

examples/create_sysdig_capture.py

@@ -37,15 +37,15 @@
 # Show the list of metrics
 #
 if res[0]:
-    capture = res[1]
+    capture = res[1]['dump']
 else:
     print res[1]
     sys.exit(1)
 
 while True:
     res = sdclient.poll_sysdig_capture(capture)
     if res[0]:
-        capture = res[1]
+        capture = res[1]['dump']
     else:
         print res[1]
         sys.exit(1)

examples/list_alert_notifications.py

@@ -9,6 +9,16 @@
 sys.path.insert(0, os.path.join(os.path.dirname(os.path.realpath(sys.argv[0])), '..'))
 from sdcclient import SdcClient
 
+def print_notifications(notifications):
+    for notification in notifications:
+        values = []
+        for entity in notification['entities']:
+            for value in entity['metricValues']:
+                values.append(str(value['value']))
+
+        print "#%s, State: %s, Severity: %s, Scope: %s, Condition: %s, Value: %s, Resolved: %s" % \
+            (notification['id'], notification['state'], notification['severity'], notification['filter'], notification['condition'], ','.join(values), notification['resolved'])
+
 #
 # Parse arguments
 #
@@ -29,7 +39,7 @@
 #
 res = sdclient.get_notifications(from_ts=int(time.time()-86400), to_ts=int(time.time()))
 
-print res[1]
+print_notifications(res[1]['notifications'])
 if not res[0]:
     sys.exit(1)
 
@@ -38,7 +48,7 @@
 #
 res = sdclient.get_notifications(from_ts=int(time.time()-86400), to_ts=int(time.time()), state='ACTIVE')
 
-print res[1]
+print_notifications(res[1]['notifications'])
 if not res[0]:
     sys.exit(1)
 
@@ -47,7 +57,7 @@
 #
 res = sdclient.get_notifications(from_ts=int(time.time()-86400), to_ts=int(time.time()), state='OK')
 
-print res[1]
+print_notifications(res[1]['notifications'])
 if not res[0]:
     sys.exit(1)
 
@@ -56,6 +66,6 @@
 #
 res = sdclient.get_notifications(from_ts=int(time.time()-86400), to_ts=int(time.time()), resolved=True)
 
-print res[1]
+print_notifications(res[1]['notifications'])
 if not res[0]:
     sys.exit(1)

examples/resolve_alert_notifications.py

@@ -28,7 +28,7 @@
 #
 # Get the unresolved notifications in the last day
 #
-res = sdclient.get_notifications(from_ts=int(time.time() - num_days_to_resolve * 86400),
+res = sdclient.get_notifications(from_ts=int(time.time() - int(num_days_to_resolve) * 86400),
                                  to_ts=int(time.time()), resolved=False)
 
 if not res[0]:

sdcclient/_client.py

@@ -601,7 +601,7 @@ def get_sysdig_captures(self):
         r = requests.get(self.url + '/api/sysdig', headers=self.hdrs)
         if not self.__checkResponse(r):
             return [False, self.lasterr]
-        return [True, r.json()['dumps']]
+        return [True, r.json()]
 
     def poll_sysdig_capture(self, capture):
         if 'id' not in capture:
@@ -610,7 +610,7 @@ def poll_sysdig_capture(self, capture):
         r = requests.get(self.url + '/api/sysdig/' + str(capture['id']), headers=self.hdrs)
         if not self.__checkResponse(r):
             return [False, self.lasterr]
-        return [True, r.json()['dump']]
+        return [True, r.json()]
 
     def create_sysdig_capture(self, hostname, capture_name, duration, capture_filter='', folder='/'):
         res = self.get_connected_agents()
@@ -639,4 +639,4 @@ def create_sysdig_capture(self, hostname, capture_name, duration, capture_filter
         r = requests.post(self.url + '/api/sysdig', headers=self.hdrs, data=json.dumps(data))
         if not self.__checkResponse(r):
             return [False, self.lasterr]
-        return [True, r.json()['dump']]
+        return [True, r.json()]

setup.py

@@ -1,7 +1,7 @@
 from setuptools import setup
 
 setup(name='sdcclient',
-      version='0.1.0',
+      version='0.2.0',
       description='Python client for Sysdig Cloud',
       url='http://github.com/draios/python-sdc-client',
       author='sysdig Inc.',