update code comments

Change-Id: I0e4e43ed8b799452dc759beb0e9ffbbd045a37b3
Signed-off-by: Dibya Prakash Das <dibyadascool@gmail.com>

diff --git a/csit/scripts/generate_dashVis.py b/csit/scripts/generate_dashVis.py
index 03f9c521a8e1ab9eb99c3af6b372596acfa19d3d..b94ebba774491ede24950596228c6444567f118d 100644 (file)
--- a/csit/scripts/generate_dashVis.py
+++ b/csit/scripts/generate_dashVis.py
@@ -12,6 +12,8 @@ import copy
 
 import json
 
+# Pretty Printer
+
 
 def p(x):
     print(json.dumps(x, indent=4, sort_keys=False))

diff --git a/csit/scripts/generate_searchSourceJSON.py b/csit/scripts/generate_searchSourceJSON.py
index eadd6a87256ce98d6d06e08949b7d31d93679c06..c8a78d82a9ceabe2d313e6e9af4c8bb29883c929 100644 (file)
--- a/csit/scripts/generate_searchSourceJSON.py
+++ b/csit/scripts/generate_searchSourceJSON.py
@@ -1,8 +1,10 @@
 from copy import deepcopy as dc
 
+# Template for search source format
 SEARCH_SOURCE_FORMAT = {"index": None, "filter": [],
                         "query": {"language": "lucene", "query": ""}}
 
+# Template for filter format
 FILTER_FORMAT = {
     "query": {
         "match": {
@@ -19,6 +21,14 @@ def generate(dash_config, viz_config, index_pattern):
 
     search_source = dc(SEARCH_SOURCE_FORMAT)
 
+    # Search for 'match-with' and 'field' for each keys in 'filter' either
+    # in viz_config or dash_config
+    #
+    # ex:- filter:
+    #        1:
+    #           field: my_field
+    #           match-with: pattern
+
     try:
         filters = dash_config['filter']
         for _, value in filters.items():

diff --git a/csit/scripts/generate_uiStateJSON.py b/csit/scripts/generate_uiStateJSON.py
index 6db4e5f5b9b7180cb3d161ab6e9cf8970a8cfd23..e99da6924890a3c7f9565ad321a235a3125bdc21 100644 (file)
--- a/csit/scripts/generate_uiStateJSON.py
+++ b/csit/scripts/generate_uiStateJSON.py
@@ -1,3 +1,4 @@
+# Template for UIState (Currently supports only colors)
 UI_STATE_BODY = {
     "vis": {
         "colors": None
@@ -9,6 +10,12 @@ def generate(dash_config, viz_config):
 
     colors = {}
 
+    # Check for 'color' key in 'series' or 'seriesParams' in
+    # either viz_config and dash_config
+
+    # Note:- 'series' simplifies 'seriesParams' and 'aggs'
+    # and avoids duplication
+
     try:
         series = dash_config['y-axis']['series']
         for _, value in series.items():

diff --git a/csit/scripts/generate_visState.py b/csit/scripts/generate_visState.py
index 3e8a24933e3b4237b69a3be67af1540ded899f16..b3327881b5c2f75453969f6b9ea2dfb33c631b85 100644 (file)
--- a/csit/scripts/generate_visState.py
+++ b/csit/scripts/generate_visState.py
@@ -12,12 +12,15 @@ from copy import deepcopy as dc
 
 import json
 
+# Pretty Printer
+
 
 def p(x):
     print(json.dumps(x, indent=4, sort_keys=True))
 
 
 class visState:
+    # viState template
     def __init__(self):
         self.content = {
             'title': None,
@@ -97,6 +100,7 @@ class categoryAxes:
         }
         self.counter = 0
 
+    # Category axes are named as CategoryAxis-i
     def create(self):
         self.counter += 1
         temp = dc(self.content)
@@ -146,6 +150,10 @@ class ValueAxes:
 
         return temp
 
+# 'seriesParams' are the ones that actually show up in the plots.
+# They point to a data source a.k.a 'aggs' (short for aggregation)
+# to get their data.
+
 
 class seriesParams:
     def __init__(self, data_type, mode, label, agg_id, value_axis):
@@ -155,7 +163,7 @@ class seriesParams:
             'mode': mode,
             'data': {
                 'label': label,
-                'id': str(agg_id)
+                'id': str(agg_id)  # the id of the aggregation they point to
             },
             'valueAxis': 'ValueAxis-{}'.format(value_axis),
             'drawLinesBetweenPoints': True,
@@ -165,6 +173,21 @@ class seriesParams:
     def create(self):
         return self.content
 
+# 'aggs' or aggregation refers to collection of values. They are the data
+# source which are used by seriesParams. and as expected they take 'field'
+# as the nested name of the key.
+#
+# Example, if your value is in {
+#  'perfomance': {
+#  'plots': {
+#         'rate': myval,
+#          ...
+#        }
+#   },
+#   then I would have to use, 'performance.plots.rate' as the 'field' for aggs
+# the 'schema' of an agg is 'metric' which are to be
+# plotted in the Y-axis and 'segment' for the ones in X-axis
+
 
 class aggs:
     def __init__(self):
@@ -197,6 +220,9 @@ class aggs:
         return temp
 
 
+# 'series' actually combines and simplifies both 'seriesParams' and 'aggs'
+# Both 'seriesParams' and 'aggs' support 'default' to set default values
+
 # generate takes both the template config and project specific config and
 # parses and organizes as much info available from that and
 # generates an intermediate format first which
@@ -264,6 +290,8 @@ def generate(dash_config, viz_config):
         except Exception:
             pass
 
+    ####################################################################
+    # Extract 'value_axes', 'seriesParams' or 'aggs' if present in viz_config
     value_axes_counter = 1
     for m in viz_config['value_axes']:
         if m != "default":
@@ -308,7 +336,9 @@ def generate(dash_config, viz_config):
                 format['aggs'].update(temp)
     except KeyError:
         pass
+    ####################################################################
 
+    # collect 'series' from both the configs
     configs = []
     try:
         viz_config['series']
@@ -322,6 +352,8 @@ def generate(dash_config, viz_config):
     except KeyError:
         pass
 
+    ########################################################################
+    # Extract 'series' from either of the configs
     for config in configs:
         try:
             value_axes_counter = 1
@@ -374,6 +406,8 @@ def generate(dash_config, viz_config):
         except KeyError as e:
             print("required fields are empty!")
 
+    ##########################################################################
+
     # to remove the default template index
     for i in ['value_axes', 'seriesParams', 'aggs']:
         try:
@@ -386,13 +420,12 @@ def generate(dash_config, viz_config):
     if len(missing):
         raise ValueError('Missing required field values :-', *missing)
 
-    # print(format)
     p(format)
 
     vis = visState()
     generated_visState = vis.create(format)
 
-    # checking incase there are None values \
+    # checking incase there are None values
     # in the format indicating missing fields
 
     missing = config_validator(generated_visState)

diff --git a/csit/scripts/push_dashboard.py b/csit/scripts/push_dashboard.py
index bb86f803232259a1a7c4c0bce07df3ddfcdc57d8..5120ad5447131afe377f7ce97d1a5765c73a71d7 100755 (executable)
--- a/csit/scripts/push_dashboard.py
+++ b/csit/scripts/push_dashboard.py
@@ -127,7 +127,6 @@ except Exception as e:
     # raise e
     print('Unable to push data to ElasticSearch')
 
-# Create and push visualizations
 try:
     viz_config_path = glob.glob('**/dashboard/viz_config.yaml')[0]
 except IndexError:
@@ -147,6 +146,7 @@ with open(viz_config_path, 'r') as f:
     viz_config = yaml.safe_load(f)
 
 
+# Create and push visualizations
 for dashboard_id, dashboard_content in dash_config.items():
 
     for _, i in dash_config[dashboard_id]['viz'].items():
@@ -163,6 +163,7 @@ for dashboard_id, dashboard_content in dash_config.items():
         # p(intermediate_format)
         # p(visState)
 
+        # Template for visualization template
         VIZ_BODY = {
             'type': 'visualization',
             'visualization': {
@@ -186,6 +187,7 @@ for dashboard_id, dashboard_content in dash_config.items():
             searchSourceJSON)
 
         p(VIZ_BODY)
+        # Pushing visualization to Kibana
         index = '.kibana'
         ES_ID = 'visualization:{}'.format(i['id'])
         res = es.index(index=index, doc_type='doc', id=ES_ID, body=VIZ_BODY)
@@ -193,6 +195,7 @@ for dashboard_id, dashboard_content in dash_config.items():
 
     # Create and push dashboards
 
+    # Template for dashboard body in Kibana
     DASH_BODY = {
         'type': 'dashboard',
         'dashboard': {
@@ -217,7 +220,7 @@ for dashboard_id, dashboard_content in dash_config.items():
         dash_gen.generate(dashboard_content['viz']))
 
     p(DASH_BODY)
-
+    # Pushing dashboard to kibana
     index = '.kibana'
     ES_ID = 'dashboard:{}'.format(dashboard_content['id'])
     res = es.index(index=index, doc_type='doc', id=ES_ID, body=DASH_BODY)