wmshutdown: Destroy dialog window before shutting down. This is especially useful...
[dockapps.git] / wmsupermon / README
blobfd2e57acbb6bf9c75944eb33bf37dffe97d01991
1 wmsupermon
2 ==========
3 Author: Sergei Golubchik <sergii@pisem.net>
4 Download: http://www.dockapps.org/file.php/id/320
6 Universal Monitoring Dockapp.
8 Can be used to monitor
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 :)
23 The dockapp is configured via ~/.wmsupermon file,
24 which specifies what to monitor and how to present the results.
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
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))/
39 [eml]
40 Source = !/usr/local/bin/check_email
41 Interval = 60
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)}
47 [Tem]
48 Source = /sys/bus/i2c/drivers/w83627hf/9191-0290/temp2_input
49 Scale     = 1000
50 Range     = 37 .. 50
52 [[wmsupermon]]
53 eml=number -label
54 i/o=bar -label
55 mem=graph -small
57 cpu=percent -label
58 tem=bar
59 cpu=graph -medium
60 =========================
62 Empty lines are allowed, if the line starts with #, it is ignored.
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.
67   After the label, the following keywords are allowed:
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).
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().
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".
88   The SUM() function is explained below.
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).
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.
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.
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.
109   If no regex is specified, the source is expected to contain just one
110   number (many files on sysfs do).
112   Other recognized keywords are:
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).
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.
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.
125   Action = shell command to be executed on left mouse click on the
126   widget.
128 Besides sources, config file defines windows and panes.
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.
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
140   name=widget [options]
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:
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.
161 See example-wmsupermonrc