add missing comments
authorStefan Koegl <stefan@skoegl.net>
Sun, 20 Jun 2010 19:35:39 +0000 (20 21:35 +0200)
committerStefan Koegl <stefan@skoegl.net>
Sun, 20 Jun 2010 19:35:39 +0000 (20 21:35 +0200)
bwmon/aggregator.py
bwmon/model.py
bwmon/monitor.py
bwmon/util.py

index 7997bcf..04a933e 100644 (file)
@@ -51,22 +51,25 @@ class Aggregator(object):
 
 
     def add_notification(self, regex, in_threshold, out_threshold, interval, command):
-        """FIXME
+        """Add a notification setting
 
-        @param regex: TODO
-        @param in_threshold: TODO
-        @param out_threshold: TODO
-        @param interval: TODO
-        @param command: TODO
+        A notification entry consists of a regex that specifies for which
+        processes/applications it is valid and in/out thresholds
+
+        @param regex: regular expression that is matched against processes/applications
+        @param in_threshold: incoming bandwidth threshold in kB/s
+        @param out_threshold: outgoing bandwidth threshold in kB/s
+        @param interval: interval in seconds for which the average bandwidth is calculated
+        @param command: optional command that shall be executed when a notification is issued
         """
         self.notification_configs.append( (re.compile(regex), in_threshold, out_threshold, interval, command) )
 
 
     def set_app_config(self, app, regex_list):
-        """FIXME
+        """Add a config entry on how to group processes to Applications
 
-        @param app: TODO
-        @param regex_list: TODO
+        @param app: name of the formed application
+        @param regex_list: a list of regular expressions that are matched against the processes full commandline
         """
         self.app_configs[app] = regex_list
 
@@ -182,11 +185,11 @@ class NotificationHandler(object):
     def __init__(self, cmd, in_threshold, out_threshold, interval, notify_command):
         """Creates a new NotificationHandler object
 
-        @param cmd: TODO
-        @param in_threshold: TODO
-        @param out_threshold: TODO
-        @param interval: TODO
-        @param notify_command: TODO
+        @param cmd: commandline of the monitored process
+        @param in_threshold: incoming bandwidth threshold that is configured for the process
+        @param out_threshold: outgoing bandwidth threshold that is configured for the process
+        @param interval: interval that is configured for the process
+        @param notify_command: command that should be called when a notification is issued
         """
         self.cmd = cmd
         self.in_threshold = in_threshold
@@ -196,17 +199,20 @@ class NotificationHandler(object):
         self.notify_command = notify_command
 
     def report_data(self, in_value, out_value):
-        """TODO
+        """Report current usage data to the handler
 
-        @param in_value: TODO
-        @param out_value: TODO
+        @param in_value: currently utilized incoming bandwidth
+        @param out_value: currently utilized outgoing bandiwdht
         """
         self.in_data.append(in_value)
         self.out_data.append(out_value)
 
 
     def check_notify(self):
-        """TODO
+        """Check if a notification should be issued and issue it if necessary
+
+        The average in-/out-bandwidth for the configured interval is
+        calculated and checked against the thresholds
         """
         in_avg = avg(self.in_data.get())
         if self.in_threshold and in_avg > self.in_threshold:
@@ -217,11 +223,13 @@ class NotificationHandler(object):
             self.notify('out', self.out_threshold, out_avg)
 
     def notify(self, direction, threshold, value):
-        """TODO
+        """Issue a notification
+
+        This is called by check_notify if a threshold has been exceeded
 
-        @param direction: TODO
-        @param threshold: TODO
-        @param value: TODO
+        @param direction: direction (in or out) for which the threshold was exceeded
+        @param threshold: configured threshold for the given direction
+        @param value: actual average bandwidth that has exceeded the threshold
         """
         import sys
         if len(self.cmd) > 50:
index 4e2e7a3..646999c 100644 (file)
@@ -162,9 +162,9 @@ class MonitorEntryCollection(object):
         return x
 
     def get_datapoints(self):
-        """TODO
+        """Returns values for the visualization through the built-in HTTP  server
 
-        @return: TODO
+        @return: list of x (time) and y (bandwidth usage) values;
         """
         items = [self.get_history(cmdline) for bin, bout, cmdline in self.get_usage()]
         if not items:
index 280ea56..7a4491f 100644 (file)
@@ -32,8 +32,8 @@ class Monitor(object):
         lookback value is False, this call already takes
         the first measurement from ip_conntrack.
 
-        @param lookback: TODO
-        @param ignorelocal: TODO
+        @param lookback: indicates if data already existing in ip_conntrack should be considered (True) or ignored (False)
+        @param ignorelocal: indicates if the Monitor should ignore loopback traffic (True) or include it in the calculations (False)
         """
         self.fd_map = {}
         self.sample_time = time.time()
index bd47790..aff6349 100644 (file)
@@ -14,10 +14,10 @@ def clear():
     sys.stdout.flush()
 
 def read_monitor_config(configfile):
-    """TODO
+    """Reads the monitor configuration file for the Aggregator
 
-    @param configfile: TODO
-    @return: TODO
+    @param configfile: path of the config file
+    @return: a list of Monitor or PipeMonitor objects
     """
     config = ConfigParser.ConfigParser()
     config.read(configfile)
@@ -65,10 +65,10 @@ def parse_bool(val):
 
 
 def read_notification_config(configfile):
-    """TODO
+    """Reads the notification config file for the Aggregator
 
-    @param configfile: TODO
-    @return: TODO
+    @param configfile: path to the config file
+    @return: a list of tuples representing the notification settings (process_regex, in_threshold, out_threshold, interval, command)
     """
     config = ConfigParser.ConfigParser()
     config.read(configfile)
@@ -78,13 +78,13 @@ def read_notification_config(configfile):
 
 
 class RingBuffer:
-    """TODO
+    """A ringbuffer
     """
 
     def __init__(self,size_max):
-        """TODO
+        """Initiates a new ringbuffer with the given size
 
-        @param size_max: TODO
+        @param size_max: maximum number of entries
         """
         self.max = size_max
         self.data = []
@@ -108,7 +108,7 @@ class RingBuffer:
 
 
 class RingBufferFull:
-    """TODO
+    """A full ringbuffer - not initialized directly
     """
 
     def __init__(self, n):