Program Logic Manual for ABWE Alert Code

Connie Logg

April 2, 2004

 

 

1. Source code: /afs/slac/package/netmon/bandwidth-tests/v2src/alerts

 

2. Data and report directory: /nfs/slac/g/net/iepm-bw/bandwidth-tests/iepmlite/alerts

 

3. Main results page: http://www.slac.stanford.edu/comp/net/iepmlite/alerts/analysis.html

 

4. Main driver routine is “runperiod”. This calls:

 

• “fetchabw” to fetch the weighted ABWE data
• “combine-trace” to fetch the trace route data
• “triganal” to analyze the ABWE data for changes
• “ckchangeroute” to analyze the traceroute data for changes
• “plotem-each” to plot the ABWE data, alerts, and traceroute changes

 

Program Logic for the Alert Scripts

 

For ease of use, the environment variable BW_CFG should be set to “/afs/slac/package/netmon/bandwidth-tests/v2src/iepmlite.cfg”

 

·        “runperiod” – calling sequence:

“runperiod –d date –i  #days –c configfile(BW_CFG)  -s source_directory(BW_SRC) –n nodelist”

 

If called with no arguments, -d = now,  -i = 1,  -c=BW_CFG,  -s=BW_SRC,

-n= all nodes in the alias file specified in BW_CFG.  That is, it analyzes the data for the last 24 hours from the time it is called.  If you want to run it automatically every hour, set up a cron specification for it. In that case you must specify –s and –c.

 

• “fetchabw” – calling sequence

“fetchabw  -s starttime(mm/dd/yy hh:mm) -e endtime(mm/dd/yy hh:mm)

-n aliasname –o output_directory”

 

The data is fetched from the oracle data base and written to a file with the name form output_directory/aliasname.  The data is in 3 columns: date time abwe

 

• “combine-trace” –  calling sequence:

“combine-trace –n aliasname –d date –i #days”

 

Must be called with –n. If –d and –I are not provided, -d=today and –i=1

The output files are in the data directory and identified as “aliasname.trace” and “aliasname.rtrace”

 

• “triganal” – calling sequence
• “triganal –n aliasname –p datapoint_column (2 for abwe) –s starttime –e endtime”

 

“-n” must be specified. “–s” and “–e” are for output labeling purposes and are not used in the code. “–p”=2 if it is not specified. Triganal works with the files previously fetched and stored in the data and reports directory. It only uses the alerts/aliasname file which contains the ABWE data.

 

“triganal” has two buffers: a history buffer (histbuf) and a trigger buffer (trigbuf). The parameters which are used to tune the code are:

• $histmax = maximum size of the history buffer
• $histmin = minimum size of the history buffer (note that this is only used at startup to load the minimum required data into histbuf)
• $trigdur = the maximum size of the trigger buffer. This is the number of points needed in the trigger buffer to trigger a alert analysis
• $sens = “sensitivity”. This is a factor applied to the std. dev. To see if a value belongs in the trigger buffer. It is also used in the “outlier” calculation. See qtrigger and qoutlier subroutines in the triganal code.
• $majorthresh = the percent change the mean of the values in the trigger buffer have to have in order to be considered a major “alert”.
• $minorthresh = The percent change < $majorthresh, that the mean of the  values in the trigger buffer have to have in order to trigger and minor “alert”.

 

Please see the code for its operation.

 

Output files in the data directory include:

“analysis.html” – the analysis web page

“dat-aliasname” – the file with the major and minor alert points.  The format is:

Date time majoralert (=224) minoralert (=0).  This file is plotted by plotem-each to make the major and minor alert marks on the axes and also by traceaanl to provide a background color for the hourly boxes.  A typical file contents appears as:

04/05/04 00:43:44 224 ?
04/05/04 01:39:35 224 ?
04/05/04 02:08:52 ? 0
04/05/04 02:38:18 ? 0
04/05/04 03:07:34 ? 0 

where the first token is the dae, teh second the time of day (local time) the 3rd token is the majoralert and the fourth the ninoralert.

 

Note: to control what is printed on the analysis.html page, modify the following if statement at the end of the triganal code:

“if ($color eq "magenta" || $color eq "#b8860b" || $color eq "white" || $color eq "yellow")”

 

“magenta” is a major alert, “brown (#b8860b)” is a minor alert, “yellow” are trigger values that do not trigger any alert, and “white” are rises in bandwidth. You probably only want brown and magenta, but I write the others out for debugging and validating the code.

 

• “ckchangeroute” – calling sequence

“ckchangeroute –n aliasname –t tracetype”

 

“-n”= aliasname

“-t” = “trace” or “rtrace”

 

“ckchangeroute” creates a data file with the date and times that traceroutes change

 

Output files are: $aliasname-traceck or $alias-rtraceck

The are plotted by plotem-each to indicate when there were traceroute changes.

 

• “plotem-each” – calling sequence

“plotem-each –n aliasname -d date [-c comment]”

 

“plotem-each plots the alert data, the abwe data, and the traceroute data.  Note that major alerts are plotted on the top axis and minor alerts on the bottom axis. Note -n and -d are mandatory, -c is optional.

e.g. plotem-each -n node1.cacr.caltech.edu -d 2004_04_10 -c 'trigdur=30, histmax=600, sens=2, maxthresh=40'

 

The output files are in the data directory under the subdirectory png. Name are “png/aliasname.png”