datasource_type documentation

Author: gianlucaborello

README.md

@@ -122,17 +122,17 @@ A dictionary showing the details of the new dashboard.
 **Description**  
 This is the method you use to export metric data. It's flexible enough to offer both time-series and table-based data export.  
 **Arguments**  
-- **metrics**: a list of dictionaries, specifying the metrics and grouping keys that the query will return. A metric is any of the entries that can be found in the _Metrics_ section of the Explore page in sysdig cloud. Metric entries require an _aggregations_ section specifying how to aggregate the metric across time and containers/host. A grouping key is any of the entries that can be found in the _Show_ or _Segment By_ sections of the Explore page in sysdig cloud. These entries are use to apply single or hierarchical segmentation to the returned data and don't require the aggregations section. Refer to the examples section below for ready to use code snippets.  
+- **metrics**: a list of dictionaries, specifying the metrics and grouping keys that the query will return. A metric is any of the entries that can be found in the _Metrics_ section of the Explore page in sysdig cloud. Metric entries require an _aggregations_ section specifying how to aggregate the metric across time and containers/host. A grouping key is any of the entries that can be found in the _Show_ or _Segment By_ sections of the Explore page in sysdig cloud. These entries are used to apply single or hierarchical segmentation to the returned data and don't require the aggregations section. Refer to the examples section below for ready to use code snippets.  
 - **start_ts**: the UTC time (in seconds) of the beginning of the data window. A negative value can be optionally used to indicate a relative time in the past from now. For example, -3600 means "one hour ago".
 - **end_ts**: the UTC time (in seconds) of the end of the data window, or 0 to indicate "now". A negative value can also be optionally used to indicate a relative time in the past from now. For example, -3600 means "one hour ago".
 - **sampling_s**: the duration of the samples that will be returned. 0 Means that the whole data will be returned as a single sample.
 - **filter**: a boolean expression combining Sysdig Cloud segmentation criteria defines what the query will be applied to. For example: _kubernetes.namespace.name='production' and container.image='nginx'_.
-- **datasource_type**: XXX gianluca edit this with an example or two.
+- **datasource_type**: specify the metric source for the request, can be `container` or `host`. Most metrics, for example `cpu.used.percent` or `memory.bytes.used`, are reported by hosts and containers. By default, metrics reported by the host are used, but if the request contains a grouping key in the metric list/filter which is container-specific (e.g. `container.name`), then the container source is used. In cases where grouping keys are missing or grouping keys apply to both hosts and containers (e.g. `tag.Name`), the datasource_type can be explicitly set to avoid any ambiguity and allow the user to select precisely what kind of data should be used for the request. [examples/get_data_datasource.py](examples/get_data_datasource.py) contains a few examples that should clarify the use of this argument.  
 
 **Success Return Value**  
 A dictionary with the requested data. Data is organized in a list of time samples, each of which includes a UTC timestamp and a list of values, whose content and order reflect what was specified in the _metrics_ argument.  
 **Examples**  
-[examples/get_data_simple.py](examples/get_data_simple.py), [examples/get_data_advanced.py](examples/get_data_advanced.py), [examples/list_hosts.py](examples/list_hosts.py).  
+[examples/get_data_simple.py](examples/get_data_simple.py), [examples/get_data_advanced.py](examples/get_data_advanced.py), [examples/list_hosts.py](examples/list_hosts.py), [examples/get_data_datasource.py](examples/get_data_datasource.py).  
 
 #### `get_data_retention_info(self)`  
 **Description**  

examples/get_data_datasource.py

@@ -0,0 +1,109 @@
+#!/usr/bin/env python
+#
+# This script shows the basics of getting data out of Sysdig Cloud by crating a
+# very simple request that has no filter an no segmentation.
+#
+# The request queries for the average CPU across all of the instrumented hosts for
+# the last 10 minutes, with 1 minute data granularity
+#
+
+import sys
+sys.path.insert(0, '../')
+from sdcclient import SdcClient
+
+#
+# Parse arguments
+#
+if len(sys.argv) != 2:
+    print 'usage: %s <sysdig-token>' % sys.argv[0]
+    print 'You can find your token at https://app.sysdigcloud.com/#/settings/user'
+    sys.exit(0)
+
+sdc_token = sys.argv[1]
+
+#
+# Instantiate the SDC client
+#
+sdclient = SdcClient(sdc_token)
+
+cpu_metric = [
+    {"id": "cpu.used.percent",
+     "aggregations": {
+         "time": "avg",
+         "group": "avg"
+     }
+    }]
+
+#
+# First example: CPU by host name
+# datasource_type is not necessary since it's infered from the grouping key host.hostName
+#
+req = [{"id": "host.hostName"}]
+req.extend(cpu_metric)
+res = sdclient.get_data(req, # metrics list
+                        -600,    # start_ts = 600 seconds ago
+                        0)       # end_ts = now
+
+if res[0]:
+    data = res[1]
+else:
+    print res[1]
+    sys.exit(0)
+
+print "\n\nCPU by host:"
+print data
+
+#
+# Second example: CPU by container name
+# datasource_type is not necessary since it's infered from the grouping key container.name
+#
+req = [{"id": "container.name"}]
+req.extend(cpu_metric)
+res = sdclient.get_data(req, # metrics list
+                        -600,    # start_ts = 600 seconds ago
+                        0)       # end_ts = now
+
+if res[0]:
+    data = res[1]
+else:
+    print res[1]
+    sys.exit(0)
+
+print "\n\nCPU by container:"
+print data
+
+#
+# Third example: CPU average across all hosts
+# datasource_type is set to host since no grouping keys or filters are specified (default would be host anyway)
+#
+res = sdclient.get_data(cpu_metric, # metrics list
+                        -600,    # start_ts = 600 seconds ago
+                        0,       # end_ts = now
+                        datasource_type='host') # ask data from hosts      
+
+if res[0]:
+    data = res[1]
+else:
+    print res[1]
+    sys.exit(0)
+
+print "\n\nAverage CPU across all the hosts in the infrastructure:"
+print data
+
+#
+# Third example: CPU average across all containers
+# datasource_type is set to container since no grouping keys or filters are specified (ovverrides the host default)
+#
+res = sdclient.get_data(cpu_metric, # metrics list
+                        -600,    # start_ts = 600 seconds ago
+                        0,       # end_ts = now
+                        datasource_type='container') # ask data from containers
+
+if res[0]:
+    data = res[1]
+else:
+    print res[1]
+    sys.exit(0)
+
+print "\n\nAverage CPU across all the containers in the infrastructure:"
+print data

examples/list_metrics.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python
 #
-# Print the list of dashboards.
+# Print the list of metrics.
 #
 
 import sys