This is a substantially revamped version of the program which was made
available in ISODE-7.0.  The main changes allow the program to be run
frequently, keeping running totals, and printing the results on demand.
This obviates holding very large log files, merely to produce usage
statistics.

dsastats is a script which processes the log file produced by a quipu DSA 
of normal operation.  This file is by default called quipu.log, which
is by default written to the /usr/tmp directory.  The script produces
a summary of usage of a DSA.

To use the script successfully, you must have set the logging levels as
described in the note "Tailoring Quipu's logging" by Paul Barker.
Briefly, you must have the "stats" variable in the quiputailor set thus:

stats           level=TRACE level=NOTICE

OR

you can omit this line entirely: the defaults give the appropriate level
of logging.

Helpful comments on the script will be gratefully received.  Please email
quipu-support@uk.ac.ucl.cs.


If you would like to port these logging scripts, you first need to 
configure a few things in the Makefile.

# this is where the script will by default find the log file.
LOGFILE= /usr/etc/quipu.log

# this is the quiputailor file.  This is accessed to get the name of the
# DSA's logs to be processed, ready for inclusion in the report.
TAILORFILE=/usr/ucl/etc/isode/quiputailor

# The DN of your local organisation.  This allows DSA activity to be 
# categorised as either "local" or "remote"
LOCALORGDN=c=GB@o=University College London

# The "etc" directory, where a couple of configuration files (quipulocaladds
# and quiputechusers) will be installed
ETCDIR=/usr/etc

# where you want the script installed
LOCALPATH=/usr/local/bin

You now have to configure a couple of files.

The file quipulocaladds contains leading substrings from local DUA and DSA
addresses.  The surest method to get these to examine the file quipu.log 
and see what the DSA is writing out.
You can extract all the addresses from the quipu.log file by

grep "context association" quipu.log | awk '{print $NF}'

Note that the quipulocaladds file must be terminated with a 
line beginning with a #.  An example quipulocaladdsfile is given in
quipulocaladds.example

The file quiputechusers is mainly for the benefit of sites where one or
more users make heavy use of the directory by testing it or verifying that
it is working correctly.  This file allows use of the Directory by such users 
to be filtered out and classed as "system" usage.  The file 
consists of a number of distinguished names.  Again, the file must 
be terminated with a line beginning with a #.  An example quiputechusers file
is given in quiputechusers.example

Then type:

make dsastats

to configure the script ready for use.

make install

installs the dsastats script in the $(LOCALPATH) directory.


To run it:

dsastats [-s] [-n] [-t] [-a] [-g <dsaname>] [<logfilename>]

-n           Don't produce a report

-t           Save totals

-a           Archive totals

-s           Summary report

-g dsaname   Grand totals for chosen dsa - printed from archive
-g all       Grand totals for all dsas



Something essential
===================

You will need a directory called dsastats.arch in the same directory as your
stats file(s).  The script will try and create the directory if it doesn't
exist, but you may get a permissions failure.

Some useful things to know!
===========================

If no filename is supplied, the script uses the file which is configured by
the makefile macro, LOGFILE.

If the filename contains the string ".usage", it is assumed that the file
is called something like "vicuna.usage" or "giant.usage" (at UCL, we have
to rename our quipu.log files as we often have more than one DSA on a 
machine).  Otherwise, the file configured by the makefile macro, TAILORFILE,
is consulted to discover the name of the local DSA.

The report is written to standard output.


Examples of usage
=================
It may be possible to upset the program by specifying peculiar combinations
of flags.  But the following should all work.

dsastats                 Print a report based on the quipu.log file + any
                         running total

dsastats -n              As above, except don't do the printing bit!!  An
                         option only for people with surplus CPU cycles.

dsastats -t              Print report, and preserve running total.  The script
                         does not delete or archive the quipu.log

dsastats -t -n           Keep running total, don't print

dsastats -a              Print the totals, and archive them.  Delete
                         the running total.

dsastats -g quipu        Produce grand totals for all the quipu.log data
                         in the archive.  Don't touch any other data.

dsastats -g all          Produce grand totals for all the DSAs data
                         in the archive.  Don't touch any other data.