wiplc - Generate tables in HTML, XML or text format based on statistics maintained by wipld

wiplc [ options ] columlist

The wiplc program from the 991008 release of wipl is renamed to wiplcSimple.

This program will connect to the wipld daemon and display tables calculated from statistics maintained by the daemon. The program will display a row for each entry in the table maintained by wipld and a column for each element given in the columlist arguments. Each element in the columlist argument should be one of the following:

mac Display a column with MAC addresses.

ipn Display a column with IP addresses with n components where n can be 1, 2, 3 or 4.

(title,digits1,digits2,units,expr) Display a column with the title title with each row containing the value the expression expr evaluates to. Refer to the section EXPRESSIONS below for a description of the format of this expression.

The integer values digits1 and digits2 specifies how many digits should be printed before and after the period. The string units is printed after each value.

Note that the columns are numbered starting by 0.

Also note that to avoid unexpected interpretations from the shell you probably want to but enclose each element in the columlist arguments by "".

The following options are recognized:

-d daemonfile --daemon daemonfile

Connect to the wipld daemon through the file daemonfile

-o file --outfile file

Write tables to file instead of to stdout.

-c --clearscr

Clear the Linux console before each table is displayed

-s col --sort col

Sort the table by the column col.

-r --sortrev

Reverse the sort order

-p n --periodlen n

Set the period length to n in effect writing a new table every n'th second. Default is to write only a single table.

-q n --quittime n

If this is set it indicates the date/time where the program should quit. This is given in number of seconds since 1970-01-01 00:00:00 UTC. Such a number can be obtained from the date(1) command. For example the command echo $(date --date 'next monday 00:00' +%s) will print the number corresponding to next monday at 00:00.

-t title --title title

Set a title for the tables

-f format --format format

Create tables in the format format. This string can be either txt, xml, or html.

-a t --starttime t

Normally each generated table has a line displaying the time where the table was generated. If this argument is given each table in a addition has a start-time line. If t is -2 the start-time will be the time where the daemon was started. If it is -1 it will be the time where this client was started. If it is greater than or equal to 0 it will be the time as it was n periods ago.

-z --zero

Do not print rows which have no non-zero values.

This section describes the format of the expressions which can be given in the column arguments to the program. The expressions are just simple arithmetic expressions which can be build using literal constants and standard binary operators such as +, -, *, /, << and >>. The expressions are always evaluated using floating point arithmetic. The expressions can use the following functions which must be given constant non-negative integer arguments:

d(col,n) The value of counter col maintained by the daemon as it was n periods ago.

b(col) The value of counter col maintained by the daemon as it was when this client was started.

c(col,n) The value of the column col in the table displayed by this client as it was n periods ago.

t(n) The time (in seconds since 1970) of the table calculated n periods ago.

When the n value is set to 0 it indicates the values as they are in the current period. Because of this it is possible to specify cyclic refering computations by using the c function. An error message will be printed if this happens.

You might want to compare these examples with the examples on the wiplcSimple man page.

To display the values of counter 0 and 1 in the daemon together with the MAC and IP addresses they are associated with use:

wiplc \
  "mac"                     \
  "ip4"                     \
  "(Counter0,10,0,,d(0,0))" \
  "(Counter1,10,0,,d(1,0))" 

To write a HTML file every 10th second displaying in KB/s the speed data was transfered with during the last minute for counter 0 and 1 in the daemon use:

wiplc \       
   --periodlen 10 --starttime 6                            \
   --format html --outfile speed.html                      \
   "mac"                                                   \
   "ip4"                                                   \
   "(Counter0,5,1,KB/s,(d(0,0)-d(0,6))/(t(0)-t(6)) >> 10)" \
   "(Counter1,5,1,KB/s,(d(1,0)-d(1,6))/(t(0)-t(6)) >> 10)"

Note that the expression x >> 10 is equivalent to x/1024.

Also note that you should not just divide by 60 instead of by t(6)-t(0) since it will give less accurate results.

To write a table to the Linux console every two seconds displaying 1) a column with the difference of counter0 and counter1 of the daemon in bytes relative to the values they had when this client was started and 2) a column with the speed this differences changes with calculated over a period of 10 seconds use:

wiplc \       
   --periodlen 2 --starttime -1                            \
   --clearscr                                              \
   "mac"                                                   \
   "ip4"                                                   \
   "(Diff,10,0,B,(d(0,0)-b(0))-(d(1,0)-b(1)))"             \
   "(DiffSpeed,10,1,B/s,(c(2,0)-c(2,5)) / (t(0)-t(5)))"

Note that the columns with the MAC and IP addresses are also given numbers and this is why the first argument to the c function should be 2 and not 0.

Creating expressions refering to values from many periods back will increase the memory usage of the program because it has to save many old values. The extra memory usage will be proportional to the maxentries argument given to wipld(8).

If you want to create tables with a different layout you have two options: 1) You can extended the wiplc program itself with a new output format (which is rather easy) or you can 2) pipe the output of this program to another program which can then write its own tables. In the later situation you probably want to use the XML output of this program.

In either case please email me your extensions. And please let me know if another format of the XML output than the current will be more appropriate.

Referring to time and counter values as they were n periods ago will not give correct results until the client has run for n periods.

/etc/wipld.conf Default daemonfile.

wipl(1), wiplc(1), date(1)