Documentation for WB6YMH/NK6K Stats package.
Version 1.11, February 1996.

Amended by Jonathan Naylor G4KLX

This set of programs is intended to be the start of a family of 
programs to gather performance statistics and other information 
about the amateur radio packet system.  A complete background on 
the project was provided in a paper presented at the 6th ARRL 
Computer Networking Conference.  A copy of the paper is included 
in this release.

The following programs are currently included:

STATS - monitors output from a KISS TNC, displays activity on
the screen and puts stats in LOG.

REPORT - reformats data from LOG file.

TOTALS - reformats data from LOG file.

PTOTALS - prints output from TOTALS program.

AVERAGE - averages data from REPORT program.


The programs are written C and compiled with the GNU C compiler
2.7.0.  They will be as easily transportable to other versions of
C as any other C program.

The code in the STATS program can operate either with the kernel
AX.25 code within Linux, or via a standard serial port to a KISS
TNC. By removing the -DLINUX line in the Makefile, the code is
portable to other versions of UNIX with the TNC operating via a
serial port.

Specifics on each program are discussed below.


STATS
----

This program reads AX.25 frames in the KISS TNC format.  
Information about the frame is summed in various counters.  These 
counters are output into a log file once every reporting 
interval.  The reporting interval is currently set at five 
minutes.   The format of the records in the log file are in 
MONFILE.H

At the end of each interval, STATS opens "log" in the current 
directory (or any other file specified by the OUTPUT command below),
appends the new records, and then closes the file.  If the log file
can not be opened (disk full), STATS aborts.

STATS also writes all incoming frames on stdout.

Commands to STATS can be entered on the startup line, or after it 
is running.  Once running, the command parser is entered by 
hitting Control-C.  The parser will then accept one command line, 
then return to collecting data.  Multiple commands are separated 
by ';'.  The commands are:


BAUD speed

    Selects baud rate of the serial line to the KISS TNC, e.g. 
    BAUD 4800.


END

    Terminates execution.  Control-X may also be used to exit 
    instead of Control-C END.


HELP

    Displays the list of available commands.


OUTPUT file

    Selects a file to use in place of the default "log".


PORT device

    Selects the port for monitoring.  If the port name includes the
    string "/dev" then it is assumed that the port is a serial port with
    a KISS TNC attached.  Any other PORT name will be assumed to be a
    kernel AX.25 port and the Linux kernel code will be used.


QUIT

    Synonym for END.


TIME

    Adds timestamp to each frame displayed by STATS.  Timestamp 
    records are always included in the log file.




REPORT
------

Report further summarizes and combines the information in the log 
file built by STATS.  Data is emitted as one record per interval.  
These records can then be passed through AVERAGE to produce data
averaged over larger intervals.  The data can then passed to a 
plotting program for display.  Lotus 123 was used to produce the 
graphs in the conference proceedings.  The various items output 
by REPORT have no great cosmic meaning, they serve as examples of 
the kind of information we feel can tell us something about how 
the network is running.  The intent is for others to add more 
sophisticated reports as we get an idea of what it is we need to 
know.


The commands are summarized below.  An item enclosed in [] is 
optional.

CIRCUIT

    Most of the data graphed in the conference proceedings was 
    generated by this command.  It has no options.  The command 
    generates one record per interval; the records contain the 
    following fields:
          time_stamp          Time stamp of the start of the 
                              interval.
          all circuits        Count of unique to/from pairs.
          user circuits       Circuits excluding those sending 
                              only occasional UI frames.  These
                              are assumed to be beacons or NETROM
                              node commands.
          packets             All packets on channel
          retried packets     Total data packets - unique data 
                              packets
          poll                All packets with poll bit set
          final               All packets with final bit set
          rnr                 RNR packets
          rej                 REJ packets
          bytes               total bytes (all bytes in all 
                              packets)
          udbytes             unique data bytes (data bytes in I 
                              frames of unique packets)

END

    Exits REPORT.


HELP

    Generates a list of valid commands.


INPUT file

    Selects a file to use in place of the default "log".


OUTPUT file

    Selects a file to use for the generated report instead of 
    stdout.

HELP

    Displays the list of available commands.


QUIT

    Exits REPORT.


RAW  [T]
          
    This command displays all fields of all records selected by 
    the RECORD command.  Hit the space key to abort the display.  
    The number printed under the TO call for circuit records is 
    the record number.  RAW also totals all the data in F records 
    and prints this total at the end of the display, providing a 
    quick indication of the amount of data collect.  This command 
    has one option, T.  If T is specified, only the F record 
    total line is displayed.


RECORD [c][d][f][i][t]

    This command selects record types for processing.  The record 
    types are defined in the MONFILE.H file.  To select a record 
    type, enter the type code(s) after the command name, e.g.
          RECORD FT
    selects timestamp and frequency records.  Record with no 
    options will display the current setting.  The default is all 
    types.


RR

    RR has no options.  The command generates one record per 
    interval; the records contain the following fields:
          time_stamp          Time stamp of the start of the 
                              interval.
          packets             Total packets
          i packets           total non-digipeated I frames
          rr packets          total non-digipeater RR frames


SELECT [call]

    This command selects a callsign.  Only circuit records 
    containing this call as one of the endpoints are used in 
    other processing.  The default is no call specified, i.e., 
    all calls are used.  Only one call may be specified at a 
    time, use select with no call to de-select.




AVERAGE
-------

This program takes the output from the one-interval-per-record 
output of REPORT and averages them together.  Average takes two 
commands on the startup line, -n and -t.  -n is followed by the 
number of records that should be averaged.  For instance, the 
basic reporting interval is five minutes.  If the data is to be 
plotted in half hour points, use -n6.  This will average six 
five-minute intervals together.

If -t is specified, the first data item in each record is assumed 
to be a timestamp, which is then not averaged.




TOTALS
------

This program reads a log file through STDIN and generals a totals 
file through STDOUT.  It produces four record types, detailed 
below.  This program generates one record per station on the air, 
one record per digipeater, and one record giving totals of all 
packets and bytes heard on the frequency.  PTOTALS is used to 
display the information output by TOTALS.

TOTALS takes one option on the command line, a call sign.  If 
specified, only circuit records containing the specified call as 
one of the end points are used.  Record types are:

     D - Totals for each digipeater.
          call
          total bytes
          total packets


     F - Totals for the frequency
          total packets
          total bytes
          unique packets
          unique bytes
          l32 packets <= 32 bytes long
          l64 packets <= 64 bytes long
          l128 packets <= 128 bytes long
          l256 packets <= 256 bytes long
          g256 packets > 256 bytes long
          dcd on ticks
          dcd off ticks


     S - totals for a station
          station call
	  total rx bytes
          total rx unique data bytes
          total rx non-digipeated data bytes
          total rx data bytes
	  total tx bytes
          total tx unique data bytes
          total tx non-digipeated data bytes
          total tx data bytes

If a callsign was specified, a Z record is emitted as the first 
record in the output file.  This record is the same as an S 
record, and contains the data for the selected call.



PTOTALS
-------

This program formats the output from the TOTALS program.
There are no options.


