[grafana] Document the dashboard refresh interval taming mechanism

Author: amotl

kotori/daq/graphing/grafana.py

@@ -196,7 +196,41 @@ def demo(self):
     def get_dashboards(self):
         return self.grafana_client.search(type='dash-db')
 
-    def tame_refresh_interval(self, interval):
+    def tame_refresh_interval(self, preset='standard'):
+        """
+        Tame refresh interval for all dashboards.
+
+        :param mode: Which taming preset to use. Currently, only "standard" is
+                     implemented, which is also the default preset.
+
+        Introduction
+        ------------
+        The default dashboard refresh interval of 5 seconds is important
+        for instant-on workbench operations. However, the update interval
+        is usually just about 5 minutes after the sensor node is in the field.
+
+        Problem
+        -------
+        Having high refresh rates on many dashboards can increase the overall
+        system usage significantly, depending on how many users are displaying
+        them in their browsers and the complexity of the database queries
+        issued when rendering the dashboard.
+
+        Solution
+        --------
+        In order to reduce the overall load on the data acquisition system,
+        the refresh interval of dashboards not updated since a configurable
+        threshold time is decreased according to rules of built-in presets.
+
+        The default "standard" preset currently implements the following rules:
+
+        - Leave all dashboards completely untouched which have been updated during the last 14 days
+        - Apply a refresh interval of 5 minutes for all dashboards having the "live" tag
+        - Completely disable refreshing for all dashboards having the "historical" tag
+        - Apply a refresh interval of 30 minutes for all other dashboards
+
+        """
+        log.info('Taming dashboard refresh interval with preset="{preset}"', preset=preset)
         for dashboard_meta in self.get_dashboards():
 
             # Get dashboard by uid
@@ -209,7 +243,7 @@ def tame_refresh_interval(self, interval):
             # TODO: Look at list of tags and apply interval=5m if it contains "live".
 
             # Update refresh interval
-            dashboard['dashboard']['refresh'] = interval
+            dashboard['dashboard']['refresh'] = '5m'
             response = self.grafana_client.dashboards.db.create(**dashboard)
 
 
@@ -737,4 +771,4 @@ def collect_fields(data, prefixes=None, sorted=True):
     ])
     grafana.create_dashboard(dashboard)
 
-    grafana.tame_refresh_interval('5m')
+    grafana.tame_refresh_interval()