#    Copyright (c) 1999 University of Southern California.
#    All rights reserved.                                            
#                                                                   
#    Redistribution and use in source and binary forms are permitted
#    provided that the above copyright notice and this paragraph are
#    duplicated in all such forms and that any documentation, advertising
#    materials, and other materials related to such distribution and use
#    acknowledge that the software was developed by the University of
#    Southern California, Information Sciences Institute.  The name of the
#    University may not be used to endorse or promote products derived from
#    this software without specific prior written permission.
#    
#    THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
#    WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
#    MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.

LSAM RESOURCE USAGE LOGGING
===========================
LSAM Authors: Lars Eggert, Amy S. Hughes
$Revision: 1.11 $ ($Date: 1999/05/07 00:19:48 $)


Introduction
------------
NOTE THAT THIS IS NOT PART OF THE LSAM SERVER BUT SIMPLY A TOOL USED FOR
SERVER PERFORMANCE ANALYSIS. THUS, YOU CAN SAFELY IGNORE THIS README.

The LSAM server provides a mechanism to monitor server resource usage.
Resources monitored are the CPU, memory, page faults and disk I/O. Resource
usage is being checked during apache server maintenance, which is performed
roughly once a second. After each check a line summarizing the results is
being appended to the error log, unless _LSAM_LOG_ON_SIGNAL is defined (see
below.)

The format of the line is as follows:
TIMESTAMP IDLE USER NICE SYS INTR IDLE TOTAL FREE FLT IN OUT XMIT IF_STATS

  TIMESTAMP
	Time of the measurement in seconds relative to the start of the server.
	
  IDLE
	Percentage of time the CPU was idle since the last measurement.

  USER NICE SYS INTR IDLE
	Number of ticks spent in each of the five processor states (user,
	nice, system, interrupt, idle) since the last measurement. 

  TOTAL
	Total number of processor ticks since the last measurement.

  FREE
	Kilobytes of free physical memory at the time of the measurement.

  FLT
	Number of major page faults since the last measurement. (Major page
	faults incur physical I/O.)

  IN OUT
	Number of physical disk input and output operations. (Physical disk
	I/Os are not served from the buffer cache.)

  XMIT
	Number of TCP retransmissions done (on all network interfaces.)

  IF_STATS
	For each network interface that is not a point-to-point link or a
	loopback device, IF_STATS is of the form NAME IPKTS OPKTS COLLS,
	where:

		NAME
			Name of the interface (e.g. fxp0).

		IPKTS
			Number of packets received on the interface.

		OPKTS
			Number of packets sent on the interface.

		COLLS
			Number of collisions observed on the interface.


Note that some of the fields in the listing could be calculated from the 
others; they were included anyway to make the log file easier to read without
the need for preprocessing it.

The current version of the resource usage monitor has the following 
limitations:

Child process resource usage:
	Resource usage by child processes will only appear in the log after
	the child process has terminated. This is due to a limitation in the
	getrusage() system call and cannot be worked around easily. That means
	that if a child processes runs for a long time and then exits, its
	all resource usage over its running time will appear in the next log
	line, even if the actual time of usage was earlier and should have
	been recorded earlier. To lessen the effect of this, keep 
	MaxRequestsPerChild low in the apache configuration file - that will
	force apache to terminate and restart servers more frequently. Keep in
	mind that this may lower server performance because of processes
	startup times.

Free RAM measurement:
	The free RAM values are not terribly meaningful for two reasons: First,
	FreeBSD will try to keep the amount of free RAM small by dynamically
	allocating free RAM to the disk buffer cache. Thus, even when there
	may me ample free RAM this value may still be low. Second, this value
	represents a snapshot of the system at the time of measurement, not an
	average since the last measurement.

Must be run as root:
	Because the resource monitor reads kernel memory, apache must be run 
	as root if it is enabled. Alternatively, /dev/drum and /dev/mem can be 
	made readable and apache an be executed in user mode.


Compilation
-----------
1. Modify src/Configuration such that EXTRA_CFLAGS defines _LSAM_LOG_RUSAGE.
   One way of doing this is to add this line:
   EXTRA_CFLAGS+=-D_LSAM_LOG_RUSAGE

   Modify src/Configuration such that EXTRA_LIBS includes -lkvm.
   One way of doing this is to add this line:
   EXTRA_LIBS+=-lkvm

2. Run the apache configuration utility.

3. Recompile.

4. OPTIONAL 
   Modify conf/httpd.conf to decrease MaxRequestsPerChild.
   For example, the next line will force apache to use a new server process 
   after each 100 requests:
   MaxRequestsPerChild 100

5. Test the server. Start the server as root. Let it run for a few seconds,
   then look at the error log.


Configuration
-------------
If _LSAM_LOG_ON_SIGNAL is defined in addition to _LSAM_LOG_RUSAGE, the server
will not continuously log resource usage. Instead, it will only write a log 
entry when signal SIGUSR2 is sent to the master process. (Note tha


Execution
---------
Run the server normally.


Upcoming Features
---------------
None planned at this time.