view release on metacpan or  search on metacpan

Traffic.pm  view on Meta::CPAN

        perl Makefile.PL
        make
        make test
        make install

This will install the module into the Perl library directory. 

Once installed, you will need to modify your web server's configuration
file so it knows to use Apache::Traffic during the logging phase:

	PerlLogHandler Apache::Traffic

Restart your web server.

As of this writing, there is a problem with IPC::Shareable 
which will cause segmentation faults in httpd processes if
Apache::Traffic is run long enough (at least this is the case
under Linux).  This distribution contains a patch named 'share.patch',
which will fix the problem. 
 
If Apache::Traffic does not appear to work correctly (look in your
server's error_log for problems), make sure the semaphore and shared
memory segments are not already allocated for another purpose.
If this is the case, you can change the constants SHMKEY, SEMKEY, and
DBPATH at the top of the Apache::Traffic module, and reinstall.

=head1 HOW IT WORKS

Each time a request is served, the Apache::Traffic log handler
is called which increments the byte and hit totals for the owner
of the resource.

The owner of the resource is determined in the following way:

  o If the Perl variable Owner has been set for the directory, its
    value is used.  For example:

	<Directory /home/root/www/mark>
	  PerlSetVar Owner mark
	</Directory>

    This would declare user mark as the owner of everything under
    the specified directory.  The value can be either the username
    or UID of the user.

    This value can also be a fake user (i.e. a username which is
    not present in the passwd file).  In this case, the username is
    stored (rather than the UID).

  o If the request is to a virtual host, the owner of the document
    root is used.

  o If neither of the above methods work, the owner of the file
    is used.

The hit and byte total information is stored in shared memory to
minimize processing.  On the first request of each day, all
previous data in shared memory is automatically moved to permanent 
storage.  This means that no more than one day's worth of information
is ever stored in shared memory, and prevents performance degradation
as data accumulates.  This separation of data is transparent from
the end-user perspective.

If you would rather not have the data moved into the dbm file, you
can set USE_DBM to 0 at the top of the Traffic.pm module and reinstall.

Shared memory segments are not preserved through reboots.  If you
reboot your machine multiple times a day, Apache::Traffic will be
of questionable value to you.  I run Linux, so of course, I only
reboot when I've upgraded the OS. ;-)  This area may be improved
in the future (at least for orderly shutdowns).

=head1 VIEWING STATISTICS

A script named 'traffic' is included in this distribution, which allows
you to view the totals for a given user.  Note that this script will
not run properly until Apache::Traffic has recorded at least
one page request.

The basic syntax for the script is:

	traffic [options] [username]

If username is not specified, the effective UID of the person running the
script is used.  By default, only data for the current day is displayed.

The following options are supported:

  -start=starting_date

	Specifies the starting date that you wish to see data for.  The
	date specifications can take any format supported by the 
        Date::Parse module.  If -end is not specified, all data between
        -start and the current day is displayed.

  -end=ending_date

	Specifies the ending date that you wish to see data for.  

  -days=num_days

	Specifies the number of days you want to see information for
        relative to the value of -start (or the current day if -start
        is not specified).  The value can be either positive
        or negative.

  -user=username

	Specifies the user you want to see data for.  Multiple
        -user specifications are allowed.  The users can also be
        specified as non-option arguments.  Both UIDs and usernames
        are allowed.

  -all

	Displays all data present within the given time period.
  
  -reverse

	If present, the information is sorted in descending order based
	on date.