FileSpy is copyrighted ã1996 by Felix Rauch.

FileSpy
A logfile observing utility
by Felix Rauch
felix@nice.ch

0. Introduction

FileSpy has many advantages:
-	It's free, so you don't have to pay anything for it.
-	It comes with full source code, so you may improve or debug it, if you wish to do so.
- It seems to work. I like it and use it whenever I'm working on my NeXT. So do some of my collegues, which means it does a good job for us.

However, it has also some disadvantages:
- It's free, so you won't get support for it.
- It comes with full source code, but the source is ugly. I started this programm two years ago, when I knew much less about how to make a good programm, without having a clear project or even design. Over the years, I inserted code wherever I felt it would be a good idea to do so. This resulted in ugly code and not so well designed objects. Please do not look at this programm as an example of how to do things.
- It seems to work. As I explained above, FileSpy is a really useful and working application for me and some other people. For you it may be a buggy and completely useless collection of bits.

1. Copying, warranty and legal stuff

For most people, this program underlies the GNU GENERAL PUBLIC LICENSE. However, there are special restrictions for people having to do with nuclear weapons. See the file CONDITIONS for details.

THE PROGRAM IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.

For more details about terms and conditions about copying, distribution and modification see the file COPYING.

This product includes software developed by Rich Salz, i.e. the wildmat-routine.

2. Features

This is a short list what FileSpy does. For more detailed help, see chapter 4. Using FileSpy.

FileSpy helps you monitor your log- and lock-files such as /usr/adm/messages, /tmp/console.log, /usr/spool/uucp/Log, /usr/spool/uucp/LCK/LCK..cufa and similar ones. It lets you do the following things:
-	Select as many log- or lockfiles as you want and pop up a window as soon as something happens to these files. This means when: Something is appended to them; they're removed or created; they're no longer accessible; they reduce their size (in this case, FileSpy of course can't show you any new text, so it just prints a message on the console that the file reduced its size).
-	Have one window for each observed file or log everything in one central Multilog-window. Files may have different colors to be quickly identified in the multilog or their names may be printed each time they log something or just when a different file starts to print its output to the multilog. You may also print timestamps when something is logged.
-	Use a filter to strip out non-interesting messages. The filter allows the use of wildcards, as well as for the logged texts as for the filenames to which the filter should be applied.
-	List lockfiles in a Existencelog-window to find out quickly which lockfiles currently exist and which don't. You may also print the time how long a lockfile existed.

3. Installing FileSpy

Installing FileSpy is very easy: Just drag the FileSpy.app-bundle to the ~/Apps or /LocalApps directory. If you want to use the 'Spy in FileSpy'-service you may have to log out and back in to let the Workspace know about the new service.

4. Using FileSpy

4.1 Starting FileSpy

After starting FileSpy for the first time, the empty main window appears on the screen.

4.2 The main window

The main window shows you all the files you are currently spying.

If the main window is open, you may add files in one of the following ways:
-	Enter the filename of the file in the textfield and press return or click on the 'Add' button.
-	Click on the 'Open...' button and choose the file in the OpenPanel.
-	Drag a file from the File Viewer in the main window.
- Use Christian Limpach's improved open from a shell (e.g. open -a FileSpy /tmp/console.log). You can get open from ftp://nice.ethz.ch/users/chris/.

When you don't want to spy a specific file any longer, select the file (or files) and click on the 'Delete' button.

4.3 The Inspector Panel

Select a file in the main window and then press cmd-i or click on 'Tools->Inspector...'. This opens the Inspector Panel where you can change the settings for the currently selected file.
The first line in the Inspector Panel shows you the name of the file you're changing the settings for. If the filename is gray, you're changing the settings for more than one file (i.e. for all the selected files in the main window).

4.3.1 Changing the settings for a file

The radio buttons and switches in the Inspector Panel have the following meaning:

- Show entire file / only new text: This changes the behaviour of FileSpy on startup. 'Show entire file' means that the whole file is loaded and displayed when FileSpy loads it for the first time. 'Only new text', on the other hand, tells FileSpy to load only text that is appended to the file after FileSpy checked it for the first time (this settings may be useful for the file /tmp/console.log which contains only some text about the version of your operating system right after login to the Workspace).
- Auto popup: If this switch is on, FileSpy will automatically pop up the window where new text for this file appeared. Note: If you also set 'Windows become key on popup' in the Preferences Panel, the window containing the new text will also become the key window.
- Beep when file changed: This switch is quite self-explaining. If some file changes (e.g. text gets appended to it or it changes its size), FileSpy beeps. You may choose your own beep in the Preferences Panel.
- Log to multilog: Do not only put the text from this file to its own window, but append it also to the multilog. If 'Log to multilog' and 'Auto popup' is active and some text is append to the file, only the multilog pops up. The multilog may be quite usefull, because you don't have your screen filled up with FileSpy-windows. If you would like to have the changes of some special file in its own window, uncheck this switch.
- Use filter: If this switch is on, FileSpy first applies the filter to text which it would otherwise directly append to the file's window or to the multilog.
- Don't copy to multilog on startup: If you would like to have the window of a file contain all of its contents and not only new text (See 'Show entire file / only new text' above), but don't want to have the multilog filled up with the whole file on startup, then you should check this switch. The multilog will then only receive new text which gets appended to the file after FileSpy checks it for the first time.
- Print time: This option prints a timestamp in front of each line that FileSpy appends to a file's window or to the multilog. This is usefull if you are not in front of your computer all the time but still want to know when exactly something happened.
- Filename in multilog: There are many different ways in which FileSpy's multilog can tell you from which logfile its text comes:
	- Once: Each time the file logs to the multilog (and the last file that did so is not the same), its name is printed underlined before the new text.
	- On each line: In front of each line that this file logs to the multilog its name is printed.
	- None: The name of this file is never printed in the multilog. In this case, you have to know which file currently logs by yourself, or you may use colors to distinguish different files in the multilog.
- Spy what: You may not only spy the contents of logfiles but also the existence of lockfiles. If you set this option to Contents, FileSpy only notifies you if the contents of the file change (more specifically: If it's size changes). On the other hand, if the option is set to Existence, FileSpy adds the file to the existencelog, where it is marked with a '+' or a '-' sign depending on its current state (existing or not existing). The option Both lets FileSpy examine the contents as well as the existence of the specified file.
- Text attributes: In this box you may select different fonts and colors for your files. This is especially usefull if you let many different files log to the multilog, but don't want to have all their names printed each time they log something. The little boxes in the main window display the selected color for the files.

4.4 The Preferences Panel

In the Preferences Panel you may change some of the behaviors of FileSpy. There are four different sections:

4.4.1 General

The settings in this section affect FileSpy in general.
- Save filelist: If this switch is on, Save Preferences saves everything in the Preferences Panel plus the list of files in the main window. If it's off, the (saved) file list is unchanged and only the settings in the Preferences Panel are saved.
- Windows become key on popup: If a window is poped up by FileSpy and this box is set, it also becomes the key window.
- Save preferences on exit: With this switch on, FileSpy automatically saves its preferences on exit or logout.
- Update intervall: This intervall specifies the time in seconds that FileSpy waits between two checks for changes in the files. It may be set between one and sixty seconds.
- Buffer length for each window: If you set a limit in this box, then FileSpy will automatically truncate the contents of its windows to the specified number of lines. This may speed up FileSpy if you have files which contain a lot of text and are updated frequently.
- Beep: Here you may set your own beep for FileSpy. If you don't set an extra beep, FileSpy uses the system beep. It may be an advantage to use a different beep so that you can better distinguish it from other beeping applications.

4.4.2 New Files

This section contains the same settings as the Inspector Panel. If you specify an new file in the main window for FileSpy to spy (see 4.2), this settings are used.

4.4.3 Multilog / Existencelog

Here you can set some settings for the Multilog- and the Existencelog window. Some of them are comparable to the settings in the Inspector Panel. The difference is, that they only enable a feature, they do not automatically turn it on. The next paragraphs will hopefully make this clear.
- Enable auto popup: If this switch is unchecked, the Multilog will never automatically pop up. If it's checked, then the Multilog will pop up if some new text is append to a file, that file logs to the superlog and its Auto popup feature is on.
- Enable beep on change: This switch's functionality is similar to the above.
- Enable filter: As the name implies, this switch enables the filter for the Multilog. If it's checked, all the files that have the Use filter switch checked send the filtered text to the multilog. Thouse files that don't use the filter still send the unfiltered text to the Multilog! If Enable filter is unchecked all the files send their unfiltered text.
- No duplicated lines: If this option is set, FileSpy tries not to copy the same lines from multiple files to the Multilog. However, if a line appears multiple times in the same file, all occurences are copied to the Multilog. This feature is useful if you spy e.g. /usr/adm/messages and /tmp/console.log but don't want to see the warning message "May  4 18:00:03 harka su: BAD SU hacker on /dev/ttyp2" two times in the Multilog.
- Show lifetime: This button affects only the Existencelog. If it's set, every file in the Existencelog shows the time it does already exist (if it exists of course). If the file does no longer exist, the timer stops, but the time the file did exist is still displayed. When the file is created again, the timer starts from zero. This feature is useful for lock-files of modem-lines and gives you an idea about how long the line is already up. The frequency in which the existence of the files is checked is equal to the one in which normal log files are checked and is set in the Preferences Panel under Update intervall.

4.4.4 Swapfile

This preference lets you keep track of your swapfile. Enter the path of your swapfile and a maximum size. FileSpy will then warn you when your swapfile exceeds the specified limit.

4.4.5 Saving the preferences

When you click on Save preferences in the Preferences Panel, all the settings you set up in FileSpy are saved. 'All' means: The files in your list and their settings in the Inspector panel (if the Save filelist switch is checked), all the settings in the Preferences Panel and the positions and states of the windows. So, make FileSpy exactly look as you would like it to have on the next startup (e.g. close the windows you don't want to have on the screen when you start FileSpy) and the click on Save preferences. The Preferences Panel itself is of course an exception to this rule as it must be on the screen to be able to save the preferences, neverthless it is never shown on startup.

4.5 The Tools menu

From the Tools menu you can access all the important windows and panels. It has five submenus:

4.5.1 File list

This menu button displays the main window where you can add new files to the list of files to be spyed, remove files from the list or change settings for the files. For more information, see section 4.2 The main window.

4.5.2 Inspector

With the inspector panel you can change the settings for a file. See section 4.3 The Inspector Panel for an explanation of what the settings do.

4.5.3 Multilog

Clicking on this menu button shows the multilog window. It contains all the text that was appended to files which have the 'Log to multilog' checkbox checked. See sections 4.3.1 Changing the settings for a file and 4.4.3 Multilog / Existencelog for a detailed description of what the multilog can do.

4.5.4 Existencelog

This menu button is similiar to the above and displays the existencelog window. See sections 4.3.1 Changing the settings for a file and 4.4.3 Multilog / Existencelog for a detailed description of  how to use the existencelog.

4.5.5 Filter

Here you can set the filter strings for your files. Enter lines in the following format:
[<filename pattern> '|' ] <filter pattern>
This lines have the following meaning: In every file with a name that matches <filename pattern>, filter all lines matching <filter pattern>. If you want a filter pattern to be applied to all files, leave the filename pattern out. After changing the filter, click on 'Apply' to let FileSpy use the new filter. If you want to use the same filter the next time you start FileSpy, click on 'Save Filter'.

The pattern matching uses wildmat by Rich $alz. It performs shell-style pattern matching for ?, \, [ ], and * characters. Please note that you have to escape the '[' and ']' character if you want to match them, as in "\[Mail: Loading *.bundle\]*". The same applies of course to the other special characters '?', '\' and '*'.

In the lower part of the filter window are two radio buttons to select the kind of filtering you wish to perform. The upper button Don't copy filtered strings in logwindow cuts the matched lines out of the incoming text. You therefore won't find these lines anywhere in FileSpy if they get appended to file which uses the filter. If you don't want to loose the matched text, but don't want to be alarmed everytime something unimportant is logged in one of the files you spy, then check the second button Don't beep or popup on filtered strings. In this case, FileSpy keeps quiet when a matching line is appended somewhere in your spyed files, but the text is appended to the appropriete windows nevertheless.

4.5 Messages by FileSpy

Under some special circumstances FileSpy doesn't pop up a window, but prints a message on the console (so you should probably add the file /tmp/console.log to your filelist). This happens when a file
-	reduces its size
- is deleted or created
- has permissions so that it can't be opened
- is no langer accessible through its path

5. Comments

What other people think about FileSpy:

... habe ich jetzt mein Stuart-Consolefenster geschlossen und arbeite mit FileSpy; das will doch was heissen :-)
[... I have closed my Stuart-Consolewindow and I'm working with FileSpy; that means something ;-) ]
								- Marcel Waldvogel, formerly Uptime Object Factory Inc.

Musste letzhin Zeugs installieren. Da hab ich filespy wunderbar verwenden kðnnen, is ne richtig geile app :) Wollt ich nur mal sagen *grins*
[Had to install stuff lately. I used filespy wonderfully, 's a truly cool app :) Just wanted to say that once *grin* ]
									- Philippe Steindl, Swissbank

PS: Und es ist eben doch ne Megacoole App ;-))
[PS: And it really is a megacool app ;-)) ]
									- Amir Guindehi, Datacore

6. Acknowledgements

I would like to thank the following people:

Amir Guindehi for the initial idea which let me start with FileSpy.
Michael Hauber for the initial tips which let me know how to start with FileSpy.
Both of them as well as Christian Limpach, Marcel Waldvogel, Urs Gubser, Daniel Kluge and Philippe Steindl for bug-reports and ideas.
Timothy Reed for the cat's eye in FileSpy's icon.