wmsupermon/README

   1 wmsupermon
   2 ==========
   3 Author: Sergei Golubchik <sergii@pisem.net>
   4 Download: http://www.dockapps.org/file.php/id/320
   5
   6 Universal Monitoring Dockapp.
   7
   8 Can be used to monitor
   9
  10  1. CPU usage
  11  2. disk i/o
  12  3. memory
  13  4. swap
  14  5. filesystems - space utilization
  15  6. network traffic
  16  7. wireless link quality
  17  8. cpu frequency
  18  9. CPU temperature, fan speed, voltages (no lm_sensors required!)
  19 10. battery status (with actual - not guessed - discharge rate!)
  20 11. traffic from your router
  21 12. anything else :)
  22
  23 The dockapp is configured via ~/.wmsupermon file,
  24 which specifies what to monitor and how to present the results.
  25
  26 The syntax of a config file is:
  27 =========================
  28 [mem]
  29 Source = /proc/meminfo
  30 Regex = {MemTotal: *([0-9]+).*MemFree: *([0-9]+).*Buffers: *([0-9]+) kB.Cached: *([0-9]+)}[(\1 - \2 - \3 - \4)/\1]s
  31
  32 [i/o]
  33 Source = /proc/diskstats
  34 #major minor name rio rmerge rsect ruse wio wmerge wsect wuse running use aveq
  35 # note that "name" part is limited to letters!
  36 # thus we count, e.g. "sda" line, but not "sda1", "sda2", etc.
  37 Regex = /^ +[0-9]+ +[0-9]+ [a-z]+ ([0-9]+) [0-9]+ [0-9]+ [0-9]+ ([0-9]+) /DIFF(SUM(\1+\2))/
  38
  39 [eml]
  40 Source = !/usr/local/bin/check_email
  41 Interval = 60
  42
  43 [cpu]
  44 Source = /proc/stat
  45 Regex = {cpu  ([0-9]+) ([0-9]+) ([0-9]+) ([0-9]+)}{DIFF(\1+\2+\3+0.01)/DIFF(\1+\2+\3+\4+0.01)}
  46
  47 [Tem]
  48 Source = /sys/bus/i2c/drivers/w83627hf/9191-0290/temp2_input
  49 Scale     = 1000
  50 Range     = 37 .. 50
  51
  52 [[wmsupermon]]
  53 eml=number -label
  54 i/o=bar -label
  55 mem=graph -small
  56
  57 cpu=percent -label
  58 tem=bar
  59 cpu=graph -medium
  60 =========================
  61
  62 Empty lines are allowed, if the line starts with #, it is ignored.
  63
  64 First there are sources of readings. Every source starts with a label
  65 (e.g. [mem]) which can be one to three characters long.
  66
  67   After the label, the following keywords are allowed:
  68
  69   Source = specifies where to take the data from. It's either a
  70   filename or an executable/script (if the value starts from the
  71   exclamation sign).
  72
  73   Regex = defines how to parse the source (the file or the output of
  74   an executable).  It consists of two parts delimited by any non-blank
  75   character (e.g. regex=  !...!...!   or /..../..../) or two pairs of
  76   matching brackets (e.g. [ ...]{...} or (...)<....>).
  77   The first part is an extended regex, the second - an expression to
  78   evaluate.  This expression can use numeric constants (floating
  79   point), \1 .. \9 to refer to parts of regex, operators + - * / > < ?:,
  80   parentheses, and two functions SUM() and DIFF().
  81
  82   The DIFF function (which means differentiate) returns the difference
  83   between the value of its argument and the value of its argument from
  84   the previous evaluation. See [cpu] source above to for an example -
  85   DIFF is used to convert the constantly growing number of raw "cpu
  86   ticks" into "cpu usage".
  87
  88   The SUM() function is explained below.
  89
  90   After the expression one can put flags. Supported are
  91   i - case insensitive match
  92   s - single line (see below)
  93   d - debug (the result of the expression is printed to stdout).
  94
  95   Normally the source is read line by line, until the regex matches
  96   for the first time.  The result of the expression is the reading of
  97   a source.
  98
  99   If SUM() function is present anywhere in the expression, all lines
 100   of the source are read, and all matches are accumulated. The result
 101   of the SUM() is the sum of values of its argument for all matches.
 102   See [i/o] source above for an example - SUM is used to calculate i/o
 103   for all block devices.
 104
 105   If 's' (single line) flag is specified, regex is used to match
 106   file's content as a whole, not linewise. See [mem] source above for
 107   an example.
 108
 109   If no regex is specified, the source is expected to contain just one
 110   number (many files on sysfs do).
 111
 112   Other recognized keywords are:
 113
 114   Interval = N, the reading of a source is taken every N seconds. 0
 115   means "as fast as possible" (currently - four times a second).
 116
 117   Scale = N, the reading calculated from Source+Regex is divided by N.
 118   That's most useful when there's no regex, see [Tem] example above.
 119
 120   Range = N1 .. N2, used by bar and graph widgets.  Without explicit
 121   range, bar expect readings to be in 0..1 range, and graph
 122   autoscales. As with scale, this is most useful when no regex is
 123   specified, as in [Tem] example above.
 124
 125   Action = shell command to be executed on left mouse click on the
 126   widget.
 127
 128 Besides sources, config file defines windows and panes.
 129
 130   Every window definiftion starts from [[name]], where "name" is the
 131   window title. Wmsupermon may open many windows, with different
 132   layouts and values to monitor.
 133
 134   Window definition consists of widgets, which are placed on panes.  A
 135   pane has four rows, and a widget can take up to all the four,
 136   depending on the type and options, see below. A pane is thus defined
 137   by one to four lines, specifying widgets for this pane.  Empty
 138   lines are used to separate panes. One widget line looks like
 139
 140   name=widget [options]
 141
 142   where <name> is the name of a source, defined above, and <widget> is
 143   the widget type. Supported widget types are "number", "percent",
 144   "bar", and "graph". After the type, one can optionally put
 145   <options>, from the following list:
 146
 147     -label              - print a source name on the widget.
 148                           can be used with any widget
 149     -smooth             - smooth the output by averaging last 8 readings.
 150                           can be used with any widget
 151     -float              - print a number with the decimal dot, not an integer.
 152                           can be used only with "number" widget
 153     -log                - use logarithmic scale. only valid for "graph" widgets
 154     -big                - 4-rows graph, only valid for "graph" widgets
 155     -medium             - 2-rows graph, only valid for "graph" widgets
 156     -small              - 1-row graph, only valid for "graph" widgets.
 157                           by default a graph takes 3 rows.
 158     -scaledown          - if the graph autoscales, allow the scale to decrease,
 159                           by default it can only increase.
 160
 161 See example-wmsupermonrc
 162