WHAT IS THIS?

fcgi_watch is a supplement to (or replacement for) <rails_app>/script/process/reaper.

The standard reaper script searches for all processes started with a given pathname
using the output from a ps command, and performs an action on them. There are
problems with this approach, at least on some shared servers:

	- The pathname seen from a script is not necessarily the same as the pathname
		seen from a shell command. You can determine whether you have this problem
		by typing a pwd command, then ruby -e 'puts `pwd`'. If the results are
		different, the problem exists.
		
	- At least on some servers, if you have two or more Rails applications running,
		all of the FCGI dispatchers will look the same to the ps command. This means
		that any action performed by reaper will affect all your Rails applications.
		
HOW DOES fcgi_watch SOLVE THESE PROBLEMS?

fcgi_watch finds and parses the fastcgi.crash.log in the <rails_app>/log
directory. It makes a list of processes that should be running, then cross-checks
it against the output of ps to find all the FCGI processes that are actually
running for a specified application. Only then does it perform the specified
action.

BUT THAT'S NOT ALL!

Managing FastCGI processes on a shared server is sometimes problematical. You
have little control over the web server used, over its configuration, or over
the activities of other users. Your dispatchers might get swapped out and 
become "unresponsive", causing the server to start new ones. After a day or so,
"ps aux" might show eight or ten copies of dispatch.fcgi -- more, if you have
multiple applications -- and you have no way of knowing which ones of them can
be safely killed.

fcgi_watch provides an "expire" action, in addition to the actions provided by
reaper. fcgi_watch keeps track of the ages of instances of dispatch.fcgi, and
can "expire" processes older than a given number of hours. You can also set a
maximum number of FCGI dispatchers that you want to allow for a given 
application. "fcgi_watch expire" will terminate the extras -- gracefully, if
possible.

HOW TO USE fcgi_watch

Quick Start: 
-----------

put fcgi_watch in <rails_app>/script, and use it like any of the
other scripts. "script/fcgi_watch" will show you a list of this application's
FCGI processes. "script/fcgi_watch restart" will restart your application. 

All the Details:
---------------

First, take a look at the constants declared at the top of the fcgi_watch file.
fcgi_watch uses the first batch, RailsDirCharacteristics, to determine whether
it has successfully located a Rails application directory. You should not have to
edit these, unless you have renamed one or more of the files and directories it
refers to.

The second group of constants, SmartReapConsts, determines how fcgi_watch behaves
in relation to the dispatch.fcgi processes it finds -- how many to keep, how
long to keep them, how many seconds to allow for them to expire gracefully. It
also sets the default action. You may want to edit these constants to meet the
needs of your own situation.

To use fcgi_watch as a supplement to reaper, just put it in the <rails_app>/script
directory, and call it like any of the other scripts: script/fcgi_watch. Unless
you have changed the default action in "SmartReapConsts", it should show you a 
list of all FCGI dispatcher processes for the associated Rails application, noting
which are outdated and/or superfluous. To get rid of these processes, just type
script/fcgi_watch expire. To restart the associated application, as reaper does
by default, type script/fcgi_watch restart.

And More:
--------

fcgi_watch can process several Rails applications each time you run it. Just
type "fcgi_watch <action> <pathname 1> <pathname 2> <etc.>". This is probably
easier if you put fcgi_watch in the directory ABOVE your Rails applications.

fcgi_watch was written in June, 2006 by Al Evans <anejr@alevans.com>
The action-processing code is largely borrowed from the standard reaper.
Released under the MIT license.
Use freely and enjoy!

