Document expected behavior on Daylight Saving Time (DST) clock changes

[dkerr64]

Clocks moved forward one hour for Daylight Savings Time (DST) in the United States today at 2am local time. Observing behavior of vnstat and what is logged in the database I see that there is no data for 02:00 to 02:59. Put another way... for hourly reports there will be 23 entries for today, 2021-03-14. This is what I was expecting.

But this is not documented (as far as I can see) and I am wondering what to expect for when the clocks move back at 2am local time on November 7th (to 1am local time). Will the database record two entries for the period 01:00 to 01:59 that day. Or put another way, 25 hourly entries one of which will have duplicate timestamp of 01:00 hrs. Or will vnstat combine the traffic for a 2-hour period into a single database record? And if vnstat is recording to the database every 10 or 20 minutes, what will that record for the overlap period? And what about 5-minute entries?

I am reading JSON from the db and It would be really helpful to have this documented... so I can anticipate what will happen when DST ends.

Thank you.

[vergoh]

The database tracks local time without information about the timezone. As a result, if the used timezone follows DST then vnStat still doesn't need to really be aware of it. If local time skips forward one hour then that hour will not be recorded as it didn't exist from the daemon point of view. If the local time jumps backward one hour then that will result in the ongoing hour getting repeated and vnStat will add any new traffic on top of the time period that hour had previously seen. This same applies to the 5 minute resolution data. The daemon keeps track of those 5 minute entries regardless of what the database write interval is (and that's one reason why the vnstat -u option was removed). To be more precise, the daemon only keeps track of the traffic using 5 minute slots which are cached until the next database write occurs. The database write will the flush this cache and handle incrementing/creating all the correct entries in the database structure.

This same principle obviously also applies if you'd, for example, have a laptop you travel with and change the timezone of the system to match the local timezone. The change doesn't need to be DST induced.

[dkerr64]

Okay, so the database will not have duplicate entries. But it will add new traffic to existing traffic. So if there was a constant 100MB of traffic every hour overnight, the database will record

00:00 - 100MB
01:00 - 200MB
02:00 - 100MB
03:00 - 100MB

and if someone happens to pull data sometime between 1am and 2am after the clock moved back, it would report some value between 100MB and 200MB as data is accumulating.

Thanks

[vergoh]

The sqlite database used in the vnStat 2.x versions can't have duplicate entries due to the database schema and how the data is being written in. The numbers in your example are correct.

[dkerr64]

Thank you, that makes life easy as apps that pull JSON or XML will not have to worry about duplicate timestamps, and no data is being lost from the count.

I think it would be good to document this in the man page.... or just let this issue suffice as the documentation, your call.

Thanks

[vergoh]

I haven't yet decided which location should be best for documenting this, most likely either the vnstat or vnstatd man page as most of the other documentation apart from man pages doesn't end up being that easily accessible in the binary packages most distributions provide. However, you may be still able to help a little:

When searching for documentation about how vnStat handles timezones, which documentation sources did you read and in what order? Was there any particular keyword you were looking for?

[dkerr64]

I would search for DST or Daylight Savings Time and I would probably look in the section of man page that describes output from JSON or XML as that is where someone that needs to know this info would likely be looking. But it could just as easily go at the end of the man page (maybe between examples and restrictions) as a database notes section for example.

David

[dkerr64]

Humm... sorry to day but your documentation wouldn't really have helped me. The problem is not really timezone changes, the problem is DST, I suggest explicitly addressing behavior when DST or Daylight Savings Time changes occur, those are the relevant keywords, not timezone and neither appear in the updated documentation.