root/README

ApacheTop Readme

ApacheTop watches a logfile generated by Apache (in standard common or
combined logformat, and generates human-parsable output in realtime.

See the INSTALL file for ./configure options (there's a few newly added
since v0.11)

Several commandline options dictate some of its' behaviour:
-f logfile
        Select which file to watch.
        Specify this option multiple times to watch multiple files

-H hits | -T time
        These options are mutually exclusive. Specify only one, if any at
        all. They work as follows. ApacheTop maintains a table of
        information internally containing all the relevant information about
        the hits it's seen. This table can only be a finite size, so you
        need to decide how big it's going to be. You have two options.
        You can either:
                Use -H to say "remember <this many> hits"
        or      Use -T to say "remember all hits in <this many> seconds"
        
        The default (at the moment) is to remember hits for 30 seconds.
        Setting this too large (whichever option you choose) will cause
        ApacheTop to use more memory and more CPU time. My experimentation
        finds that remembering no more than around 5000 requests works well.

-q
        Instructs ApacheTop to keep the querystrings, not remove them

-l
        Instructs ApacheTop to lowercase all URLs, thus /FOO and /foo are
        treated as the same and accumulate the same statistics.

-r
        Enable resolving of hosts/ips (you need adns!)

-s segments
        Instructs ApacheTop to only keep the first <segments> parts of the
        path. Trailing slashes are kept if present. Statistics are then
        merged for each truncated url.
        This is easiest to demonstrate with examples:
        -s 2 would produce the following:
        /media/x.jpg               ->  /media/x.jpg
        /media/images/x.jpg        ->  /media/images/
        /media/images/small/x.jpg  ->  /media/images/
        /media/images/big/x.jpg    ->  /media/images/
        Stats for the last three URLs would be merged in this case.

-p
        Instructs ApacheTop to keep the protocol (http:// usually) at the
        front of its' referrer strings. Normal behaviour is to remove them
        to give more room to more useful information.


-d secs
        Set default refresh delay, in seconds.


Once it's running, you'll see a display like this:

last hit: 09:17:07        atop runtime:  0 days, 00:58:20              09:17:08
All:       638924 reqs ( 182.65/sec)      3433539K ( 981.6K/sec)  (   5.4K/req)
2xx:  455415 (71.3%) 3xx:  175745 (27.5%) 4xx:  7746 ( 1.2%) 5xx:    10 ( 0.0%)
R ( 30s):    5195 reqs ( 173.17/sec)        25405K ( 846.8K/sec)  (   4.9K/req)
2xx:    3447 (66.4%) 3xx:    1715 (33.0%) 4xx:    33 ( 0.6%) 5xx:     0 ( 0.0%)
                                                                               
 REQS REQ/S    KB  KB/S URL                                                    
  103   3.4  2983  99.4 /                                 
   56   1.9   239   8.0 /tickerdata/story2.dat
   47   1.6   104   3.6 /home/today/patina.js
   44   1.5    82   2.8 /home/styles/home_d0e2ee.css
<snip>


The top line displays the time the last hit was seen, how long it's been
running, and the current time.

The next two lines display information about every single hit ApacheTop has
processed in this incarnation.
Firstly you see how many hits the data is representing. After that, the
average number of hits/second since starting. Following that, the total number
of KB witnessed; then the average KB/sec. Finally you see the average KB per
request.
The next line shows a breakdown of return codes; in this particular example you
can see that 71.3% of the hits returned a 2xx code. 27.5% were 3xx, and so on.
You also have the actual number of hits in each group.

The two lines below this are where the commandline options -h and -t come in.
The data in these lines reads the same as the two above them, but this data is
only for the hits remembered in ApacheTop's internal table (remember that?).
You can see how many seconds of data this represents in the R ( 30s) at the
beginning of the line. This is for 30 seconds. These two lines of information
are good for a "what is my server doing *right now*?" scenario, while the two
above them are good for a picture over the course of a few minutes or hours.

Underneath this header, you'll see a list of URLs along with their relevant
number of requests, requests per second, kb, and kb per second.
This list is generated from the internal table ApacheTop maintains. Thus, in
this example, the list is being generated from the last 30 seconds of data. You
can see the root page has been requested 103 times in the last 30 seconds,
resulting in about 3.4 hits per second. Additionally, those 103 requests have
resulted in 2983K of traffic, at an average of 99.4K/second.

You can see the individual number of return codes a given item has generated
by pressing 'n'. This alternates the numbers columns between hits/bytes
and return codes for each item.


You may sort this list by any of the first four columns; first press 's' to
enter the 'sort submenu', and then one of the following:
        r       Sort by REQUESTS
        R       Sort by REQUESTS/SECOND
        b       Sort by BYTES
        B       Sort by BYTES/SECOND

If you are viewing return code breakdown, then you'll see the following:
        2       2xx
        3       3xx
        4       4xx
        5       5xx

Thus you can see where all your Page Not Founds are coming from and so on.
Each sort order is individually maintained, so you can sort by 3xx, and
Bytes, for example, then freely switch between number modes (using 'n')
without losing either setting.

Additionally, you can press d during runtime to switch the list of displayed
items between URLs, IPs, and REFERRERs. URLs is the default, and simply
groups together hits on your site and provides collated stats for each one.
IPs, similarly, groups hits from each IP and shows you stats for it. So you
can see how much bandwidth is being used by any given IP. REFERRERs is handy
if you want to see where your traffic is coming from. The stats here reflect
how many pages/kbytes have been served as a result of a particular referrer.

To hold the current screen at any time, press p - statistics will still be
generated in the background, but whatever is displayed at the current time
is kept onscreen until you press p again.

The asterisk beside the URL/IP/Referrer entry in the table can be used to
restrict the display to any entry you're interested in. Use Up/Down arrow
keys to move the asterisk to an entry you're interested in (you can use 'p'
to freeze the display to give you more time to do so) and then press Right
arrow to enter the display specific for that item.
        
        If the item you expanded is a URL, then IPs and Referrers specific
        to that URL will be shown; ie, IPs (or hosts) which are visiting
        that URL, and Referrers which are referring people to that URL.

        If the item is an IP/Host, then URLs that IP/Host is visiting will
        be displayed, along with the referrers that IP is coming from.

        If the item is a Referrer, then URLs and IPs will be shown which
        have that Referrer.

You may turn off any of these subcolumns; press 't' to enter the toggle
submenu, then:
        u       Toggles URL subdisplay
        r       Toggles REFERRER subdisplay
        h       Toggles HOSTS subdisplay

Thus you can only display HOSTS that are visiting a given URL, etc.
Use Left arrow to return to the previous display.




Bug reports and patches are very welcome. Please send any comments on.
(if anyone fancies rewriting this README so its a bit more readable..)
Chris Elsworth <chris@shagged.org>