= All you ever wanted to know about counter-rollovers in Dstat

== What you need to know about counter rollovers
Unfortunately, Dstat is susceptible for counter rollovers, which may give
you bogus performance output. Linux currently implements counters as 32bit
values (not sure on 64bit platforms). This means a counter can go up to
2^32 (= 4294967296 = 4G) values.

Especially for network devices (which are calculated in bytes) this is too
much as it means every 4GB, the counter is reset to 0. On a 1Gbps interface
that is fully used, this happens every 32 seconds. On 2 bonded 10Gbps
interfaces, this happens after 1.6 seconds.

Since /proc is updated every second, this becomes almost impossible to catch.


== How does this impact Dstat ?
Currently Dstat has a problem if you specify delays that are too big. I.e.
using 60 or 120 seconds delay in Dstat will make Dstat check these counters
only once per minute or every two minutes.

In case a counter rolls over, it may be lower than the previous value, or
worse, the value may actually be higher. In the first case we compensate
because we now a rollover (at least one) happened, but if in the interval more
than one rollover happened, you're screwed. If however the rollover causes
a higher value than the previous in that interval, you're screwed too :-)

In both situations that you're screwed, we cannot help you either because we
don't know. So we cannot compensate or even notify the user of the problem.
This is very problematic, and it's important you are aware of this.


== What are the solutions ?
The only fix for Dstat is to check more often than the specified delay.
Unfortunately, this requires a re-design (or an ugly hack). But if rollovers
happen more than once (or values are larger than the max value) we cannot fix
this.

There are plans to use 64bit counters on Linux and/or changing the output from
using bytes to kbytes. None of this is sure. (add pointers to threads)


== What can I do ?
Since this is Open Source, you are free to fix this and send me the fix. Or
help with a redesign of Dstat to overcome this problem. Also look at the
TODO file to see what other changes are expected in a redesign of Dstat.

Since I have a lot of other responsibilities and am currently not using Dstat
for something where this problem matters much, I will have no time to look at
it closely (unless the fix or the redesign is made fairly simple). It all
depends on how quick I think I can fix/redesign it and how much time I have.

Your help could be to reduce the time it takes for me to fix it :)


NOTE: Please send me improvements to this document.
