Updated documentation for mentat-statistician.py module.

(Redmine issue: #3379,#3361)

doc/sphinx/_doclib/bin_mentat-statistician.rst

@@ -6,4 +6,4 @@ mentat-statistician.py
 .. automodule:: mentat.module.statistician
 
 
-.. include:: _inc_bin.help.script.rst
+.. include:: _inc_bin.help.fetcher.rst

lib/mentat/module/statistician.py

@@ -259,8 +259,6 @@ class MentatStatisticianScript(mentat.script.fetcher.FetcherScript):
         """
         result = {}
 
-        #self.logger.warning("Running in simulation mode, no data will be actually removed")
-
         (time_low, time_high) = self.calculate_interval_thresholds(
             time_high = self.c(self.CONFIG_TIME_HIGH),
             interval  = self.c(self.CONFIG_INTERVAL),
@@ -294,15 +292,21 @@ class MentatStatisticianScript(mentat.script.fetcher.FetcherScript):
     #---------------------------------------------------------------------------
 
 
-    def _update_rrds(self, result, tstamp):
+    def _update_rrds(self, stats, tstamp):
         """
+        Update add RRD database files with given statistics and timestamp.
 
+        :param dict stats: Calculated message statistics.
+        :param datetime.datetime tstamp: Update timestamp.
         """
-        stats = result[mentat.stats.idea.ST_OVERALL]
+        # We are interested only in overall statistics.
+        stats_oa = stats[mentat.stats.idea.ST_OVERALL]
 
         utstamp = int(tstamp.timestamp())
 
-        if not stats['cnt_alerts'] > 0:
+        # In case there are no messages at all update all existing databases with
+        # value '0'
+        if not stats_oa['cnt_alerts'] > 0:
             self._rrd_update_all(tstamp)
             return
 
@@ -314,7 +318,7 @@ class MentatStatisticianScript(mentat.script.fetcher.FetcherScript):
             total   = 0
             updated = {}
 
-            for (stat_key, stat_value) in stats[itm[1]].items():
+            for (stat_key, stat_value) in stats_oa[itm[1]].items():
 
                 try:
                     db_name = self.stats_rrd.clean(stat_key)
@@ -347,7 +351,9 @@ class MentatStatisticianScript(mentat.script.fetcher.FetcherScript):
 
     def _generate_charts(self, tstamp):
         """
+        Generate charts and export files.
 
+        :param datetime.datetime tstamp: Update timestamp.
         """
         utstamp = int(tstamp.timestamp())
 
@@ -355,9 +361,35 @@ class MentatStatisticianScript(mentat.script.fetcher.FetcherScript):
 
         self.runlog['generated_files'] = result
 
+    def _update_db(self, stats):
+        """
+        Store given message statistics into database.
+
+        :param dict stats: Message statistics to store.
+        """
+        stats['ts'] = int(time.time())
+
+        try:
+            db_id = self.collection_stats.insert(stats)
+            self.logger.info("Stored statistics log to database document '%s'", db_id)
+            stats['flag_stored'] = True
+            stats['db_id']       = db_id
+
+        except Exception as exc:
+            self.logger.error(str(exc))
+
+        return stats
+
+    #---------------------------------------------------------------------------
+
+
     def _rrd_update_all(self, tstamp, value = 0):
         """
+        Update all RRD database files with given timestamp and the same value, ``0``
+        by default. This method is usefull in case there were no messages in given
+        time interval and the statistics are empty.
 
+        :param datetime.datetime tstamp: Update timestamp.
         """
         utstamp = int(tstamp.timestamp())
         self.logger.info("Updating all existing RRD DBs with default value '%d' and timestamp '%s':'%d'", value, str(tstamp), utstamp)
@@ -365,27 +397,15 @@ class MentatStatisticianScript(mentat.script.fetcher.FetcherScript):
 
     def _rrd_update_database(self, db_type, db_name, tstamp, value):
         """
+        Update given RRD database with given timestamp and value.
 
+        :param str db_type: Type part of the database identifier.
+        :param str db_name: Name part of the database identifier.
+        :param datetime.datetime tstamp: Update timestamp.
+        :param int value: Update value.
         """
         db_id = '{}.{}'.format(db_type, self.stats_rrd.clean(db_name))
         utstamp = int(tstamp.timestamp())
         self.logger.info("Updating RRD DB '%s' with value '%d' and timestamp '%s':'%d'", db_id, value, str(tstamp), utstamp)
         (rrddb, flag_new) = self.stats_rrd.update(db_id, value, tst=utstamp)
         return (rrddb, flag_new)
-
-    def _update_db(self, stats):
-        """
-
-        """
-        stats['ts'] = int(time.time())
-
-        try:
-            db_id = self.collection_stats.insert(stats)
-            self.logger.info("Stored statistics log to database document '%s'", db_id)
-            stats['flag_stored'] = True
-            stats['db_id']       = db_id
-
-        except Exception as exc:
-            self.logger.error(str(exc))
-
-        return stats