3.2 SAM

This section lists the functional requirements for SAM split into Core and Non-Core.

3.2.1 Core SAM Functionality

This section describes the core functional requirements for SAM.

1. Load a file
   SAM will allow the user to specify a log file of format NETLOG to be loaded. If the file is not in format NETLOG, as judged by the file header, SAM will give the user an error message and prompt the user to load a different file.

2. Select Data for Analysis
   Once a log file has been successfully loaded, the user must be able to select a single form of input data to be analysed from the information available from the log file. This input data will include:
   1. Queue size
      The size of the outgoing queue of the Router (in bytes) at individual points in time (analysis available either per stream or as an aggregate by sum).
   2. Window size
      The window size of packets received by the Receiver at the time of each packet's arrival (analysis available either per stream or as an aggregate by sum).
   3. $p(q)$
      A linear function of the queue size of the Router (analysis available either per stream or as an aggregate by sum). Explained further in the Client's paper in section 11.
   4. Throughput
      The number of bytes passing through the Router for a particular stream over a one second period (analysis available either per stream or as an aggregate by sum).
   5. Number of packets transferred
      The number of packets transferred since the last time data was dumped (analysis available either per stream or as an aggregate by sum).
   All these data have time as the independent variable.

3. Select Analysis Type
   Once a log file has been successfully loaded, the user must be able to select a single analysis type to be performed. All the analysis types are applicable to all the above data types. The analysis types are:
   1. Plot data
      Perform no analysis, plot raw data vs. time.
   2. Mean
      Calculate the mean of the data:
      
      
      $$\overline{x} = \frac{1}{n}\sum_{i=1}^n x_i$$
      
      
      where $\overline{x}$ is the mean and the $x_i$ are the $n$ data values (as on page 41 of [6]).
   3. Variance
      Calculate the variance of the data:
      
      
      $$variance = \frac{1}{n-1}\sum_{i=1}^n {(x_i - \overline{x})^2}$$
      
      
      where $\overline{x}$ is the mean and the $x_i$ are the $n$ data values (as on page 51 of [6]).
   4. Spectral analysis
      Perform spectral analysis (a Discrete Fourier Transform - see Glossary, section 10) on the data.
   5. Autocorrelation
      Plot the autocorrelation coefficients for the data against the time lag (where the time lag $k$ has a range of 0 to the last time the data was dumped):
      
      
      $$r_k = \frac{n}{n-k}\frac{\sum_{i=1}^{n-k} \ {(x_i - \overl... ...k}- \ \overline{x})}}{\sum_{i=1}^n {(x_i - \overline{x})^2}}$$
      
      
      where $r_k$ is the lag-$k$ autocorrelation coefficient and the $x_i$ are the $n$ data values (as in [2], with the scaling factor of $\frac{n}{n-k}$ added in).
   6. CDF
      Calculate the cumulative distribution function of the data [3]:
      
      $$cdf(x) = Pr[X \leq x]$$
      
      
      where $cdf(x)$ is the probability that the variable takes a value less than or equal to the data value $x$, displaying it as a histogram, with the values of the data along the X-axis, and the probability along the Y-axis.
   7. PDF
      Calculate the probability distribution function of the data [3]:
      
      $$pdf(x) = Pr[X = x]$$
      
      
      where $pdf(x)$ is the probability that the variate takes the data value $x$, displaying it as a histogram, with the values of the data along the X-axis, and the probability along the Y-axis (as on page 314 of [6]).
   The output of performing an analysis is either a single graph or a single table (see 'Select Output Type' below).

4. Select Analysis Options
   Once the analysis type is known by SAM, if necessary, SAM will ask the user for any options or variables that are needed by the chosen analysis. Each variable will already have a default value that can be changed by the user.

5. Select Stream Combination
   Once a log file has been successfully loaded, SAM will provide the user with a list of possible streams and aggregate streams contained in the log file from which to perform the chosen analysis on. The user must select at least one stream or stream aggregate. All stream combinations are applicable to all analysis types. For applicability of stream combinations to data types, see section 2 above for details.

   All of the following stream combinations will be available for selection:

   1. Aggregate
      Analysis is performed on the sum of data values of all streams at any point in time and a single overlay is produced.
   2. Per stream
      Separate analysis is performed on one or more individual streams and overlaid on the same graph.

6. Select Output Type
   Once a log file has been successfully loaded, SAM will provide the user with a list of possible output types for the analysis. All of the following output types are applicable to all the stream combinations, analysis types and data types chosen. The user must select one of the following:
   1. Graph to screen
      View on screen the single graph produced by the analysis.
   2. Graph to file
      Export the single graph produced by the analysis to Adobe Postscript Version 2.0.
   3. View Table
      Display the table showing the analysed data on screen.
   4. Export to File
      Save the table showing the analysed data to a text file.
   When more than one stream or stream aggregate is chosen and the output is a graph, the graph will have multiple overlays, where each overlay corresponds to performing the chosen analysis on a particular stream or stream aggregate.

   When more than one stream or stream aggregate is chosen and the output is a table, the table will have multiple columns, where each column corresponds to performing the chosen analysis on a particular stream or stream aggregate. The first column in this table shall hold the X-coordinate values.

7. Run
   SAM will give the user the option of running the analysis and output only after a data type, an analysis function, a set of streams and/or stream aggregates and an output type have been chosen.

8. Select Output Options
   Once the output type is known by SAM, if necessary, SAM will ask the user for any further options needed by the chosen output.

9. Create Network Log
   The user must be able to create a log file of format NETLOG, which can be analysed afterwards. A log file will consists of one or more records, where a record consists of one or more of the following fields. If a record is not being produced for every packet, then one record will be produced for each TCP connection.
   1. The user must specify at least one of the following fields to be logged:
      1. Timestamp
      2. Average packet size in Bytes
      3. Average TCP window in Bytes
      4. Destination address and port
      5. Source address and port
      6. Number of packets transferred since last dump
   2. The user must specify a local network interface to extract the data from.
   3. The user must specify a filename to dump the data to.
   4. The user must specify the interval at which data is dumped into the log file, as either:
      1. Number of Packets
         After a certain number of packets have been collected since the last dump, data about the packets may be logged.
      2. Elapsed Time
         After a certain amount of time has passed since the last dump, data about the packets may be logged. Allowed time intervals are 100 ms, and any multiple of 100 ms, up to 1 hour.
   5. The user may specify the how long the log will last. The maximum time for any log is 24 hours.

10. Exit Program
    The user must be able to exit the program at any time.

3.2.2 Non-Core SAM Functionality

This section lists the non-core requirements for SAM, listed from most desirable to least desirable:

1. Round-trip time as data to be analysed
   The round-trip time from a source to a destination at individual points in time must be another type of data available for analysis from the log file, with analysis available per stream only.
2. Output a Gnuplot file
   SAM must be able to output a file containing Gnuplot commands, and any data files necessary to run these commands. The file containing the commmands must be accepted as input by Gnuplot.
3. Output a NETLOG file
   SAM must be able to output new NETLOG and STREAMSLOG files containing the data after processing.
4. Line Styles
   SAM must provide the facility to globally set all line styles to a particular style which will be used as a dafault from then on. SAM must still provide the option to change each line style individually.
5. Estimated error on analyses
   SAM must be able to calculate the estimated error on all the analyses (using the Central Limit Theorem) and output it as error bars (if the output type was a graph) or values (if the output type was a table).
6. Aggregate by median stream combination
   SAM must allow a stream combination of aggregate by median data value, available for the same data types as aggregate by sum, and available for all analysis and output types.
7. Analysis of mean by stream
   SAM must allow the mean of each stream to be plotted against the stream (instead of time).
8. Multiple analysis selection
   SAM must allow more than one type of analysis to be performed simultaneously. SAM must also provide functionality for a separate graph for each analysis type chosen for display.
9. Multiple data selection
   SAM must allow more than one data type to be analysed and graphed simultaneously, and overlaid on the same graph despite the use of different axes and scaling.
10. Real-time data logging
    SAM must be able to perform real-time graphing of raw data or data analysis.