#The following commits are pre-requisite for this feature.
1. https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=78acb1f9b898e85fa2c1e28e700b54b66b288e8d
2. https://lwn.net/Articles/611994/
#The former commit is implemented in kernel v3.16 and the later in v3.19. So this tool will work only from v3.19.

#Install the shared library libmnl-dev on your build environment.

=== To Build tipc-link-watcher ===

#To build the daemon (SuSE environment):

#First install libmnl on your build host: (libmnl-1.0.4)

"zypper install libmnl-devel"

#and run:

"gcc -o tipc-link-watcher  $(pkg-config --libs --cflags libmnl) *.c"

=== 2Do ===
- Possible bug in current code or TIPC regarding values of rx_packets and tx_packets.
  When a link is reset, rx_packets and tx_packets contain rubbish values until the link is reestablished.

=== Couple of notes ===

-Option "-x" and "-a" should not be used at the same time.

-One shot (-x):
You will get one single "layer 1" sample when you run with option "-x".
Setting "-a" option will not change this behaviour.

-Run forever:
When all layer 0 samples (s) are taken every p second, the window
layer 0 start to slide. Afterwards, every p seconds "mean of samples of layer 0"
 are calculated.  The calculated mean value will be the sample that is inserted into layer 1 window.
The procedure above will continue to fill the layer 1 window until the layer 1 window begin to slide.
When layer 1 window begin to slide the oldest value will be deleted from that window.
The size of layer 1 window is set by option "-a"

=== So what is "layer 0 and layer 1"? ===
Note:
    -layer 0 samples are statistic values obtained from TIPC.
    -layer 1 samples are "mean of samples of full layer 0 window".

When Layer 0 is complete, it starts to "slide" and the first sample (mean of layer 0 samples) of layer 1 is
calculated and inserted in layer 1 samples.

-P 4 : Sample period (how often) in secounds (Default:60 secounds)
-s 5 : Number of samples in the window(layer 0) which must be gt 1
       Default:60 samples
-a 4 : Number of samples in the window layer 1 which must be gt 1
      These samples are mean of layer zero samples over full window
      size defined by -s option
      Default value is 3600 samples.
      __________ _______________
      | 3  | 2  |2   |1   |2   |
      |____|____|____|____|____|
      <-p->
      <----------- s ---------->

3+2+2+1+2=10
The mean value = 10 / 5(-s) = 2
"2" is mean of layer 0 samples, which is sample number one in layer 1.

     layer 1
     _____________________
     | 2  |    |    |    |
     |____|____|____|____|
      <-p->
     <------------ a ---->

Layer 0 received a new sample (8) and the second
sample (mean of layer 0 samples) of layer 1 is calculated and inserted in layer 1 samples.!

      layer 0
      __________ _______________
      | 8  | 3  |2   |2   |1   |
      |____|____|____|____|____|
      <-p->
      <----------- s ---------->

8+3+2+2+1=15
The mean value = 15 / 5(-s) = 3
"3" is mean of layer 0 samples, which is sample number two in layer 1.

     layer 1
     _____________________
     | 2  | 3  |    |    |
     |____|____|____|____|
      <-p->
      <----------- a ---->

Layer 1 windown mean samples are generated at the same rate as the -p value.
=== Examples how to run the Deamon ===

#3.1: Run forever(absence of -x option); do not run as Daemon(-d);
      every second(-p); 60 samples (-s: window size layer 0) and
      3600 mean samples (-a:Default, window size layer 1).

"tipc-link-watcher -d -p 1 -s 60"

To make the process generate samples into a file run:
"kill -HUP $(pidof tipc-link-watcher)"

#3.2: Run forever as a daemon, every second(-p),
      60 samples (-s) and 3600 mean samples (-a:Default).

"tipc-link-watcher -p 1 -s 60"

To request samples run:
"kill -HUP $(pidof tipc-link-watcher)"

#3.3: One shot(-x), do not run as daemon(-d), every 1 second (-p), 60 samples (-s) and dump the samples in "/my/print/path" when the daemon exits.

"tipc-link-watcher -dx -p 1 -s 60 -f /my/print/path"

To request additional samples before the daemon exist:
"kill -HUP $(pidof tipc-link-watcher)"

#3.4: Run forever (last 24 hour) and do not run as daemon(-d),
     every 60 seconds (-p:Default), 60 samples (-s:Default). 3600 mean samples (-a:Default).

     "-tipc-link-watcher -d"

     To request samples run:
     "kill -HUP $(pidof tipc-link-watcher)"

Be aware that after 24 hours window layer 1 begins to slide and oldest mean value are removed from the window.

#3.5:Run forever (latest 24 hour) as a daemon,
     every 60 seconds (-p:Default), 60 samples (-s:Default). 3600 mean samples (-a:Default).

     "-tipc-link-watcher"

     To request samples run:
     "kill -HUP $(pidof tipc-link-watcher)"

Be aware that after 24 hours window layer 1 begins to slide and oldest mean value are removed from the window.


#3.5:Run for one hour (-x), as daemon, every 60 seconds (-p:Default), 60 samples (-s:Default)
     dump the samples in "tmp" directory at exit.
     "-tipc-link-watcher -x"

     To request samples run:
     "kill -HUP $(pidof tipc-link-watcher)"

#3.6: Run forever; do not run as Daemon(-d), every second(-p), 2 samlpes (-s) and set thresholds (-o).

"tipc-link-watcher -d -p 1 -s 2 -o t1_rx_loss_rate=10 -o rx_packets=666"

The thresholds warnings will be written in syslog.

#3.7: Run forever, do not run as daemon(-d), every second(-p) and 60 samples (-s), 3600 mean samples (-a:Default), with selected links to watch (-l)

"tipc-link-watcher -d -p 1 -s 60 -l 1.1.1:bond0-1.1.3:bond0 -l 1.1.1:bond0-1.1.4:bond0"

The program will print the quality levels of selected links: (looks like this for a link   )
"1.1.1:bond0-1.1.2:bond0: link reset:0   rx_packets:11  tx_packets:71  rx_loss:0  tx_loss:0  Working :)"
Possible quality levels are: Working, Degraded, Faulty and Down

Watching(-l) links quality is only possible in "non" daemon mode.

The sample files are NOT effected by "-l" option. That means that you will still get statistic for all published links.

Note: "rx_packets and tx_packets" are mean values of window layer 0!
      "rx_loss and tx_loss" are presented in precent.
      "link reset" is number of reset of the link!


Attention: There is some bug in TIPC or this code regarding values of
 rx_packets and tx_packets.
 When any link is reset, rx_packets and tx_packets are rabish values until
 the link is restablished.
=== Tipc link quality ===

t1: Threshold one! 10%
t2: Threshold two! 30%

This is how the link quality is calculated:
Down      == (Tipc link is not up)

Working   == (Tipc link is up) &&
       (Tipc link not reset during a size of window layer 0, which is -s) &&
       ((rx loss rate < t1)  && (tx loss rate < t1))

Degraded  == (Tipc link is up) &&
    ((link rested: up->Down->up) ||
      !((rx loss rate < 10 %)  && (tx loss rate < 10 %))) &&
      ((rx loss rate < t2)  && (tx loss rate < t2))

Faulty    == (Tipc link is up) &&
  ((link rested: up->Down->up) ||
    !((rx loss rate < 10 %)  && (tx loss rate < 10 %))) &&
      !((rx loss rate < t2)  && (tx loss rate < t2))


=== Couple of notes ===

-Option "-x" and "-a" should not be used at the same time.

-One shot (-x):
  1-One full set of samples which are represented by values in layer 0 window of samples. The first sample in
    the file represents the accumulated staticstic since last time the link statistics were reset by TIPC.
  2-And One single "layer 1" sample which is mean of samples in layer 0 window.
    Setting "-a" option will not change this behaviour.

-Run forever(absence of -x):
 When all layer 0 samples (s) are taken every p second, the window
 layer 0 start to slide. Afterwards, every p seconds "mean of samples of
 layer 0" are calculated.  The calculated mean value will be the sample
 that is inserted into layer 1 window. The procedure above will continue
 to fill the layer 1 window until the layer 1 window begin to slide.
 When layer 1 window begin to slide the oldest value will be deleted
 from that window.
 The size of layer 1 window is set by option "-a"

-The dumped sample files name look like this: (in csv format)
 2017-05-30.14.26.28_tipc (layer 0 samples)
 2017-05-30.14.26.28_tipc_l1 (layer 1 samples; which are mean values of
 layer 0 samples for every "-p" over every "-s" samples)

-The link "up" and "active" statistics in *_tipc_l1 are the sum
 of (not mean of) the link "up" and "active" statistics in window layer 0.

-"Mean of" some of properties; such as, "dest" and "mtu" in "*_tipc_l1" file; it does
 not make sence.
 The advantage of mean calculation for these properties is, to reveal any changes of
 these values during sampling time.
 For example: if "mtu" is configured to the value "1500" the mean value of "mtu"
 in window layer 0 should of course be equal to "1500".

=== That's all folks ===
