The -h histfile flag tells watcher what file to use as a history file for comparisons between runs. The default is `watcher.history'.
The -p option has watcher pretty print the control file. This is useful to make sure that watcher is parsing the file the way expected, and to provide a prettier version of the control file to use (i.e. it is of limited use except when debugging the parser).
The -v option tells watcher to be verbose as it is running. It will print out various information about where it is looking for the files that it uses, the commands that it is executing, and the output from these commands. This option is mainly of use when debugging control files or debugging watcher itself.
Watcherfile contains a sequence of entries that specify the commands to be executed, the output format of those commands, and what changes should be reported. The format of the control file is one or more of the following:
( <pipeline> ) { <alias> }
<output format> :
<change format>.
A <pipeline> is a series of commands joined together with pipes ('|').
This command is executed and the output parsed according to the output
format specified. It is then checked against the change format for
potential problems. An <alias> is optional; it is used when identifying
the command in the report of problems encountered. If there is no
alias, the entire pipeline is used. The reason for using an alias is
to keep the report clean; the pipelines tend to be long and messy.
An <output format> is either a column format or a relative format. A column format is one or more of the following:
<start> - <end> <name> % <type>
Where <start> is the first column containing the information to be compared and
<end> is the last one. <name> is the name of the field. This name is
matched with the names in the change format to identify where in the
output the appropriate information is. <type> is either "d", "f", "s", or
"k" specifying integer, floating point, or string data, or a keyword
which is used in matching output from the various programs between runs.
Relative formats are one or more of the following:
<field> <name> % <type>Where <field> is the field on the line (a field is defined as a sequence of non-whitespace surrounded by whitespace). <name> and <type> are the same as for above.
A change format consists of various names and what changes are allowable. Change format entries are separated by semicolons (';'). The list of change formats is terminated by a period ('.'). A semicolon does not follow the last change format. Watcher knows about five types of changes. It can compare the output (numeric) to the previous value and calculate the percentage change. If the change is greater that a set amount, a message is generated. The syntax of this format is:
<name> <value> %
where <name> is a name matching a name in the output format and <value
is the maximum percentage change which is allowed before a report is
issued.
Very similar to the percentage change is the absolute change. The only difference is that a percentage is not calculated. The difference is calculated and compared to the value given. Values greater that what is provided are reported. The syntax is:
<name> <value>
A maximum and minimum may be specified for numeric data also. This is useful for only numeric data. The format for this is:
<name> <max> <min>
Watcher can also watch for string values changing from a given value to any other value. This syntax is:
<name> "<value>"
or
<name> "<value>" , "<value2>"
where the second case checks the string value against all of the values
provided and only if it matches none is a message produced.
The last change watcher can watch for is any change at all. The syntax is:
<name>
A sample control file is provided below:
(df -i | /usr/ucb/tail +2) { df }
1-9 filesystem%k 41-42 spaceused%d 64-65 inodesused%d 1-9 device%k:
spaceused 15%;
spaceused 0 89;
inodesused 15%;
inodesused 0 49.
(/usr/ucb/ruptime | fgrep -f UnmHosts) { ruptime }
2 status%s 1 machine%k 7 loadav%d:
loadav 0 10;
status "up".
(ps -aux | fgrep -v -f Daemons | /usr/ucb/tail +2) { 'ps with no daemons' }
9-14 pid%k 16-19 percentcpu%d 42-45 cputime%d:
cputime 0 10.
Note that there is no order for the output format specifiers; the second
field may be specified before the first.
All names are of arbitrary length, start with [a-zA-Z] and contain no white space unless enclosed in tics ("'").
The pipeline is executed by popen(3), which uses sh(1) to expand the command; therefore shell metacharacters may be used.
The control file may have comments in it. Comments are delimited by a # on the left and a newline on the right.
Watcherfile or watcherfile default control file. watcher.history default file containing results of previous run.
Kenneth Ingham Computing and Information Resources and Technology University of New Mexico 2701 Campus NE Albuquerque, NM, 87131 ingham@ariel.unm.edu
There are various syntax errors when parsing the controlfile. These also cause an exit.
Watcher complains when output does not parse according to the format provided. It will continue to look at the rest of the output.