Valid HTML 4.01 Strict!
Valid CSS!

UTC, Time Zones and how to cope with it from RRDtool perspective

Index

Intro
UTC time vs. Local Time aka Wall Clock time
Specifying that offset
Example
Wrapup

Intro

Time depends (mostly) on the position of the sun in the sky. People on opposite sides of the globe will disagree on being day time or night. It may be 12:00 for both, but then it's going to be 12:00am for one and 12:00pm for the other. They live in different time zones. Please look this up elsewhere if you want to know details; wikipedia will do a good job, amongst others that I didn't verify. But most of you will find the information presented here more than enough.

UTC time vs. Local Time aka Wall Clock time

As of 1970 (or so) UTC was invented. The English didn't like "TUC", the French didn't like "CUT", I don't know why "UTC" was chosen over "UCT", "CTU" or "TCU". Anyway, now the world had one time to work with, everywhere on the world it was the same time.

Most places on earth apply some offset to get "local time" (explained next) and apply another offset during the summer. This is called "summer time" or "daylight saving". RRDtool will convert local time into time, or back, when necessary.

Locations west of Greenwich (England, not USA) have a local time that is behind UTC. Locations east of Greenwich have a local time that is ahead of UTC. It's easy to remember: the sun rises in the east, day starts in the east before it does in the west.

There are several converters to be found on the internet that can convert your local time into UTC. Try one or some, to roughly know your offset.

Most, not all, places use an offset that is a whole amount of hours. During summer time, another hour is added (again: not everywhere). An example works best: in the Netherlands we have a time offset of one hour, plus an extra hour during the summer. We are east of Greenwich so we are ahead of UTC time by either one or two hours. If it is 13:00 UTC, it is 14:00 or 15:00 local time.

Changing from normal local time to summer time means that a whole day is 23 hours (In our time zone, at 01:00 UTC the clock is set forward an hour). Changing back to normal time means a day of 25 hours. Not so in UTC! It is the offset that is altered, not time itself!

This also means that on those days local time is not what you expect. There is no time 02:00 to 02:59 in the first case. Time 02:00 to 02:59 occurs twice in the second case. When is 02:30 ?

The previous paragraph is very important. Make sure you understand it. Local time just isn't reliable. That's one of the reasons RRDtool uses UTC time.

Internally, RRDtool uses "seconds since the epoch" to keep track of time. This is the number of seconds since January first, 1970, midnight, UTC. When you are specifying a time in this format, it is UTC time automatically.

Specifying that offset

Because everything is computed in UTC time, you can move a database to another time zone and continue working there as if nothing happened. There will be no gap or overlap, that's because in both time zones UTC time is still the same. However, the computer definately shows a different time. How?

Any decent operating system knows about time zones. That's not strange, as it was invented 35 years ago. Most of them work in UTC time as well, they apply an offset when you ask for the current date and/or time. This offset is what is different, not time itself. In other words, the computers in those different time zones have the same time but apply another offset.

Remember my remarks about the French and English? Well, of course the people living in the central part of the northern half of the continent called America (they refer to themselves as "Americans") couldn't stay behind. So, in stead of specifying the offset in a logical manner, things are usually (see further) specified the other way around. Zones usually don't say "subtract six hours" (that would read "-6"), they say "six hours west of Greenwich" (which reads "6"). This is unfortunate but it has become a standard. But wait, why that "usually"? Well, a certain software vendor which is known to "embrace and extend" standards and slightly modify them in the process, decided to do it the other way around. Would they have been the first to do it, I would actually have been happy about this but now they only add to the confusion.

As you can read above, you will have to find out what your OS requires and do it right. If you don't do it right, your wall clock time may be correct but "the" time is not! If you get this wrong, all of your RRDtool data will be collected with an unintended time offset. At some point you discover the error, correct it and then you end up with a database containing a gap, or you get errors about the minimum update time being one second (RRDtool refuses to overwrite data).

According to this webserver, its current local time is 2017-10-18 12:52:00 which is 2017-10-18 10:52:00 UTC.

Some of the usual methods of specifying the time offset are:

Great. What a mess. Even experienced people get it wrong at some moment of not paying enough attention. Do yourself a favor, check your settings. I added an example that works for both SunOS and Linux, and I added one that works in perl. If these don't work for you, please find a command that does and let me know.

Compare the time difference (if any) against what it should be according to one of the many available services on the web.

Command: TZ="UTC" date; date

This should display UTC time first, then your local time.

Command: perl -e 'print gmtime(time)."\n".localtime(time)."\n"'

This should do the same, except that it doesn't print the time zone designator (UTC, or your zone).

The first command also shows something important which you may have missed: it is possible to specify another time zone and let the command you start use that timezone. RRDtool is no exception. The hard part is to find out how to specify that time zone.

Example

Create a (small) database, fill it with numbers, display it using two different time zones. The following perl program should do just that. You probably need to tweak some settings, look in the example directory of your rrdtool setup for the exact values (program minmax.pl for instance) on how to find perl (first line) and how to find its libraries (second line).

This script works for unix/linux. With a bit of modification, it can also work for windows. I figured this out with the help of William Owen and Eric Brander. Both helped me to test various commands and settings, thanks guys! If you (the reader in general) have other suggestions, please let me know! This page could use some suggestions for other kinds of OSes as well.

I did the copy and paste, followed by running the program, myself. If you also try it: this program will create timezones.rrd, timezone0.png and timezone1.png; make sure you don't overwrite any existing files you like to keep. I suggest naming the script "timezones.pl".

The perl program, first two lines may need adjustment as discussed

#! /usr/bin/perl
use lib qw( /usr/local/rrdtool-1.2.11/lib/perl );

use RRDs;
my $start=time;
my $rrd="timezones.rrd";

$start-=$start%300;

RRDs::create ($rrd, "--start",$start, "--step",300,
	      "DS:a:GAUGE:600:U:U",
	      "RRA:AVERAGE:0.5:1:100",
);
my $ERROR = RRDs::error;
die "$0: unable to create `$rrd': $ERROR\n" if $ERROR;

$start+=300;
# Store some rates in this RRD
my $t;
for ($t=$start; $t<$start+100*300; $t+=300){
  RRDs::update $rrd, "$t:".($t-$start);
  if ($ERROR = RRDs::error) {
    die "$0: unable to update `$rrd': $ERROR\n";
  }
}

$ENV{TZ}="UTC";

RRDs::graph "timezone0.png",
  "--title", "Timezone 0 Demo", 
  "--start", "$start",
  "--end", "start+3600sec",
  "--imgformat","PNG",
  "--width=400",
  "DEF:a=$rrd:a:AVERAGE",
  "AREA:a#0000ff",
;
$ERROR = RRDs::error;
die "$0: unable to create first graph: $ERROR\n" if $ERROR;

$ENV{TZ}="CET-1CEST";

RRDs::graph "timezone1.png",
  "--title", "Timezone 1 Demo", 
  "--start", "$start",
  "--end", "start+3600sec",
  "--imgformat","PNG",
  "--width=400",
  "DEF:a=$rrd:a:AVERAGE",
  "AREA:a#0000ff",
;
$ERROR = RRDs::error;
die "$0: unable to create second graph: $ERROR\n" if $ERROR;

Modifications to make it work on windows:

It boils down to: have the environment correct, then start perl which in turn starts RRDtool.

An interesting modification to my script:

[...]
RRDs::graph "timezone".$ENV{TZ}.".png",
  "--title", "Timezone ".$ENV{TZ}." Demo",
[...]

This probably won't work with "europe/amsterdam" kind of timezones but it does show an easy, nice way of setting a different filename for each run. Of course, "--title", "$ENV{PNGNAME}" will also work.

You could use this small html file for easy viewing your results:

<html>
<head>
<title>RRDtool and timezones</title>
</head>
<body>
<img src=timezone0.png><br>
<img src=timezone1.png><br>
</body>
</html>

P.S. If your browser tried to display images, that is not my fault. I use &lt;img , not <img , so your browser is wrong if it tries to download timezone0.png&gt;&lt;br&gt;. You are probably running InfoPath or Maxthon.

I copied the perl script from my own site (as displayed to you) onto my own site (as a program) and ran it. The output follows below. The script is available for download: timezones.pl.txt. All of a sudden the hoster tried to execute this file instead of just serving it as code. That's why I had to rename it, sorry for the inconvenience.



As you can see, the images are similar except for the time difference on the X-axis.

Wrapup

This completes the page on timezones and such. I hope you find it useful.

Do you like this information? Tell others! Don't you? Tell me!

This page was created by Alex van den Bogaerdt, an independent IT consultant. If you want to provide feedback or if you want to hire me please see contact alex.
Back to the top of this page. You can also go to the index