                            Snowlog README
                          (Updated 2004-07-28)

Snowlog is a webserver access log browser/analyzer. It does not generate 
static reports, but let's you browse through the requests in real time. 
Filters that accept regular expressions can be applied.

Requirements
============
ncurses - screen handling library
pcre    - Perl compatible regular expressions library
Access to your web server's access_log files and to the web server's 
configuration.

Installation
============
The default "combined" log format Apache uses contains only little useful 
information and is very difficult and unreliable to parse. Snowlog 
therefore uses its own log format:

LogFormat "%a\t%l\t%u\t%{%s}t\t%r\t%>s\t%X\t%{Content-Type}o\t%b\t%{Referer}i\t%{User-Agent}i\t%V\t%{LogHint}e" parsable

This produces a log that contains many more useful information in tab 
seperated fields that can be processed reliably. You need to add this log 
directive to your http.conf. You also may want to add this new log file to 
your log cycler and always load the log from the last day in snowlog. This 
is what I do. Of course you can also have up to the second information if 
you let snowlog load the current access log.

Explanation of the fields in the log format:
%a                 remote IP
%l                 ident
%u                 authenticated user name
%t{%s}             time in standard unix time format
%r                 first line of request
%>s                HTTP status code
%X                 connection status
%{Content-Type}o   MIME type of the request
%b                 bytes sent
%{Referer}i        referer as sent by the user agent
%{User-Agent}i     user agent
%V                 name of virtual host
%{LogHint}e        (see below)

LogHint
=======
This is a very simple, yet easy method to let Apache "prefilter" requests 
for us. It's mainly useful on a system that hosts different webpages under 
one virtual host. It's best explained with an example.

On our server private pages are hosted on the vhost home.kcore.de. User 
pages are accessable via the usual /~username URLs. To effectively filter
for all of these requests with snowlog you'll have to create two filter 
rules. vhost and request matches "/~username/". This does not catch 
requests if the user also has a dedicated vhost. My page for example is 
accessable via kiza.kcore.de and home.kcore.de/~kiza. Now we already need 
three rules.

To simplify this you can use loghint. It is just a simple environment 
variable Apache puts in the access log. Put the following into a vhost 
section or into ~user/public_html/.htaccess:

SetEnv LogHint user

To filter for all requests to this particular user home page you only need 
to use the following filter in snowlog since all requests are tagged with 
the loghint by Apache:

loghint	user

Filters
=======
Please see snowlog's manpage about how to write and customize regular 
expression filters.

License
=======
Snowlog is released under the conditions of the GNU General Public License 
version 2. See the file COPYING included with this distribution for 
details.
