wots(1)

NAME
wots - jolly nice log watcher program

SYNOPSIS
wots [--config=FILE] [--pidfile=FILE] [--debug[=on|off]] [--count=N] [--help] [--version]

VERSION
This is wots version 1.22.

DESCRIPTION
wots is a configurable logfile watching program. It monitors a set of logfiles looking for message lines to match against patterns and actions to perform when a match occurs. wots is best described via its options and examples. The default values are listed in the defaults section.

OPTIONS

wots uses the GNU extended POSIX option format:

-config FILE, --config=FILE
    The definitions of logfiles, patterns to be matched, and the associated actions are in FILE. See configuration section below.

-pidfile FILE, --pidfile=FILE
    wots records its process id in file FILE. This makes it easy to send signals to wots. See signals section below.

-debug, --debug[=on|off]
    See DIRECTIVES.

-count N, --count=N
    See DIRECTIVES.

-help, --help
    Give a usage summary and exit.

-version, --version
    Display the current version, and die.

CONFIGURATION
The configuration file for wots lists the logfiles to be watched, patterns to look for in those logfiles and what to do if a pattern is found.

DIRECTIVES
Note: the "config" directives "poll" and "nice" are not present on the command line; this is because subsequent reads of the configuration override the initial command line settings. So it seemed more sensible to locate them solely in the configuration file.

config poll N
    Check the logfiles listed in the configuration file every N seconds.

config count N
    Check the logfiles N times. A count of 1 makes wots scan all the logfiles once all the way through and exit, otherwise wots behaves like "tail -f".

config nice PRIO
    Renice this process to priority PRIO.

config debug on|off
    Show (lots of) internal information about what wots is doing. With no argument, assume "on". For debugging, or for the hopelessly inquisitive.

from LOGFILE
    starts a pattern/action section for the named LOGFILE. This logfile is current until the next "from" or end-of-file.

from ! PROCESS

from pipe PROCESS

from once PROCESS
    starts a pattern/action section for the named PROCESS. Output from the process (stdout) is the input space for pattern matches. ``!'' and ``pipe'' are synonyms, ``once'' will run PROCESS on each pass, but any actions will be executed at most once, until wots does a re-read of its configuration or is restarted.

echoformat STRING

mailformat STRING
    STRING is a template which defines how "echo" and "mail" will format their output when called as actions.

    The default echo format is ~L:~M which is the logfile name, a colon and the matched pattern.

    The default mail format is ~M.

    The STRING is pre-processed by strftime() so the relevant % escapes will be handled too.

    Outside of a "from" context, these commands are global, inside a "from", they apply only to the current logfile.

    NB: these directives are likely to change to a more extensible format.

PATTERNS AND ACTIONS
An action/pattern line has the format

    /pattern/ <space> action[,action...]

All of the patterns in wots are dealt with by perl, so basically you can use anything that perl would cope with as a regular expressions. wots checks all the regular expressions in the configuration file at start-up so you don't get bitten by perl croaking over a bad pattern when something matches it at a later time. A pattern is, as usual, delimited by "/".

There is a selection of actions

echo[=style[;style...]]
    if the pattern matched, then echo the match to standard output, optionally with the named style, e.g. bold, underline, reverse, on_blue. These are taken directly from Term::ANSIColor, q.v.

mail[=address]
    if the pattern matched, then send mail to the supplied address if given, or to the user who started this wots if not given.

exec=command
    if the pattern matched, then spawn the given command. The command may contain $1, $2, etc. which are replaced with bracketed matches from the pattern.

    The command will be run in the foreground by default, but putting "&" at the end of the command will run it in the background (handy for things like xmessage and friends).

bell
    if the pattern matched, ring the bell. Sanctuary, Esmerelda...

ignore
    if the pattern matched, don't do anything (handy for catch-all situations).

SIGNALS
wots responds to various signals to let you control already running instances.

SIGHUP
    makes wots re-read its configuration file and start scanning all the logfiles again.

SIGINT
    makes wots exit.

SIGTERM
    same as SIGINT.

DEFAULTS

~/.wotsrc
    location of configuration file.

./wots.pid
    location of process-id file.

poll 5
    how often to check logfiles.

no nice
    don't change the priority.

no debug
    debug tracing is turned off.

no count
    loop forever looking at the files.

EXAMPLES
A simple configuration file

    config poll 30
    from /var/log/printers
    /out of paper/ mail,echo
    /jam/ bell,echo
    from /var/adm/messages
    echoformat "~L\n ~M"
    /panic/ exec=xmessage EEEEK&

WHY WOTS?
wots was written to feel as much like swatch as possible. I was using swatch to monitor things but thought it was lacking a few features and wots is the result.

Although wots owes a lot to the ideas behind swatch, all of the code is new.

As for the name wots, I was listening to the Genesis album "Foxtrot" while writing the code. One of the songs on this album is called "Watcher Of The Skies" and contains the lyrics "watcher of the skies, watcher of all". So now you know.

SEE ALSO
swatch(1), perl(1), strftime(3), signal(2), tail(1).

TODO AND BUGS
Extended signal handling, more robust configuration parsing, time constraints on actions (e.g. echo "panic" messages during business hours, otherwise mail them when I'm not there).

I don't like the ``once'' thing, it needs to be rethought.

AUTHOR
Tony Curtis <Tony.Curtis@vcpc.univie.ac.at>

Thanks to

Martin Paul
William Annis
Michael Fischer
Lionel Cons

for lots of testing, bug reports, and helpful suggestions.