10.6.1 Running Swatch

Swatch has two modes of operation. It can be run in batch, scanning a log file according to a preset configuration. Alternatively, Swatch can monitor your log files in real time, looking at lines as they are added.

Swatch is run from the command line:

% swatch options input-source

The following are the ones that you will most likely use when running Swatch:

-c config_file

Specifies a configuration file to use. By default, Swatch uses the file ~/.swatchrc, which probably isn't what you want to use. (You will probably want to use different configuration files for different log files.)

-r restart_time

Allows you to tell Swatch to restart itself after a certain amount of time. Time may be in the form hh:mm[am|pm] to specify an absolute time, or in the form +hh:mm, meaning a time hh hours and mm minutes in the future.

The Swatch options given below allow you to change the separator that the program uses when interpreting its files. They are probably of limited use in most applications:

-P pattern_separator

Specifies the separator that Swatch uses when parsing the patterns in configuration file. By default, Swatch uses the comma (,) as the separator.

-A action_separator

Specifies the separator that Swatch will use when parsing the actions in the configuration file. By default, Swatch uses the comma (,) as the separator.

-I input_separator

Specifies the separator that Swatch will use to separate each input record of the input file. By default, Swatch uses the newline.

The input source is specified by one of the following arguments:

-f filename

Specifies a file for Swatch to examine. Swatch will do a single pass through the file.

-p program

Specifies a program for Swatch to run and examine the results.

-t filename

Specifies a file for Swatch to examine on a continual basis. Swatch will examine each line of text as it is added.

10.6.2 The Swatch Configuration File

Swatch's operation is controlled by a configuration file. Each line of the file consists of four tab-delimited fields, and has the form:

/pattern/[,/pattern/,...] action[,action,...] [[[HH:]MM:]SS] 
[start:length]

The first field specifies a pattern which is scanned for on each line of the log file. The pattern is in the form of a Perl regular expression, which is similar to regular expressions used by egrep. If more than one pattern is specified, then a match on either pattern will signify a match.

The second field specifies an action to be taken each time the pattern in the first field is matched. Swatch supports the following actions:

echo[=mode]

Prints the matched line. You can specify an optional mode, which may be either normal, bold, underscore, blink, or inverse.

bell[=N]

Prints the matched line and rings the bell. You can specify a number N to cause the bell to ring N times.

exec=command

Executes the specified command. If you specify $0 or $* in the configuration file, the symbol will be replaced by the entire line from the log file. If you specify $1, $2 or $N, the symbol will be replaced by the Nth field from the log file line.

system=command

Similar to the exec= action, except that Swatch will not process additional lines from the log file until the command has finished executing.

ignore

Ignores the matched line.

mail[=address:address:...]

Sends electronic mail to the specified address containing the matched line. If no address is specified, the mail will be sent to the user who is running the program.

pipe=command

Pipes the matched lines into the specified command.

write[=user:user:...]

Writes the matched lines on the user's terminal with the write command.

The third and fourth fields are optional. They give you a technique for controlling identical lines which are sent to the log file. If you specify a time, then Swatch will not alert you for identical lines which are sent to the log file within the specified period of time. Instead, Swatch will merely notify you when the first line is triggered, and then after the specified period of time has passed. The fourth field specifies the location within the log file where the timestamp takes place.

For example, on one system, you may have a process which generates the following message repeatedly in the log file:

Apr  3 01:01:00 next routed[9055]: bind: Bad file number
Apr  3 02:01:00 next routed[9135]: bind: Bad file number
Apr  3 03:01:00 next routed[9198]: bind: Bad file number
Apr  3 04:01:00 next routed[9273]: bind: Bad file number

You can catch the log file message with the following Swatch configuration line:

/routed.*bind/  echo        24:00:00        0:16

This line should cause Swatch to report the routedmessage only once a day, with the following message:

*** The following was seen 20 times in the last 24 hours(s):

==> next routed[9273]: bind: Bad file number

Be sure that you use the tab character to separate the fields in your configuration file. If you use spaces, you may get an error message like this:

parse error in file /tmp/..swatch..2097 at line 24, next 2 tokens
 "/routed.*bind
/ echo"
parse error in file /tmp/..swatch..2097 at line 27, next token "}"
Execution of /tmp/..swatch..2097 aborted due to compilation errors.