RRDtool graph --x-grid tutorial and examples

If the default grid is not what you want, use the --x-grid parameter ("rrdtool graph --x-grid"...) to make it look how you like it.

The documentation says: --x-grid GTM:GST:MTM:MST:LTM:LST:LPR:LFM (and some more). I'll show pair by pair what these codes are and do

GTM:GST

These define the base grid. The first is a unit, like HOUR or DAY, the second one is how many of those should occur. Two example graphs show what happens with HOUR:8 and HOUR:24, all other parameters are equal:

MTM:MST

These define the major grid. They work the same as GTM:GST, but they define the somewhat more visible grid lines. Same example, now with DAY:7 added.

But there's more. 7 days equals a week, right? Wrong! Look at these examples. One uses DAY:7, the other uses WEEK:1. Again, all other parameters are exactly the same.

Notice those red lines are in a different place? That difference is when a period starts. You should know that RRDtool works with intervals of a fixed amount of time, such as 86400 seconds (a day).

You should also know that each period starts and ends at a well defined moment in time, in such a way that the timestamp is a whole multiple of the interval size. For a 7-day period DAY:7, that's 604800 seconds.

Each start and end of such a period is then n*604800, which may be any day (this depends on the year).

Not so when using WEEK:1. This does not work in n*604800 units, but in monday to sunday.

This becomes more apparant when I add day of the month as a label, in the next examples. You are looking at the end of July 1998.

The first example graph has red lines at n*604800. Example: July 16, 1998 started at timestamp 900547200 which is exactly 1489 times 604800. July 23 of the same year started at timestamp 901152000 which is exactly 1490 times 604800. This is also the end of the previous 7-day interval.

The other example has red lines between sunday and monday, no matter if their timestamps are divisible by 604800 without a remainder or not. And indeed, July 13, 20 and 27 are all mondays.

LTM:LST

This pair defines how often labels are placed. Again, these work the same as the previous two pairs. You have already seen an example, I used DAY:1 to display the day of the month for each day. I could have used DAY:2 to display every other day, and so on.

LPR:LFM

This pair is the most confusing. I will start with showing LFM. It's the format of the label, what it looks like. In the last two examples I used %d which means day of the month. There are many such codes, and you can mix them with normal text. For instance, using %V for week of the year, combined with regular text "week":

Adding a year would be nice, but a label can get too long. Just display it on even weeks only by setting LFT:LST to WEEK:2:

These last 3 LFM examples contain spaces. RRDtool needs to see these spaces, and this is where many people experience difficulties. Spaces are often (if not always?) used to separate arguments for programs. If you just enter Week %V of year %Y, then "Week" will be seen as the LFM code, "%V" will be a separate parameter, as is "of", "year" and "%Y". The result is that RRDtool complains about "%V", as it thinks it is a new command. Quite often this can be avoided by placing the parameter between quotation marks, like so: "Week %V of year %Y" or like so: 'Week %V of year %Y'. Perhaps your OS, your interpreter, or whatever it is you are using to build your RRDtool command, interprets "%". In that case you need to escape (as that's what it is usually called) "%", may be like so: "\%" or like so: "%%".

This has nothing to do with RRDtool itself. RRDtool needs to see the string, including spaces, as one parameter. You need to find out how your program can do that. To give you some inspiration: here's what I used (where these lines read <space>, just type a space):

LPR

So, what does LPR do? Currently the labels are placed below the line separating the weeks. It would be better if they appear at the center of each period, not at the border. But when displaying hours, minutes and so on, it is more appropriate (in most cases) to display those under the line. That's the role of LPR. Set it to 0 (zero) or set it to the duration of an interval. Four examples this time. The first set shows a couple of times (hours and minutes), the second set shows a couple of weeks. One of each set has LPR set to 0, the other has LPR set to 3600 (an hour) or 604800 (a week).

Not only does LPR influence the position of the label, it also influences the content. This is visible for HH:MM, not for week numbers. If you still want to show times as whole hours, you can use "%H:00".

It is also possible to shift the label partially, i.e. not at the center. Specify 1800 in stead of 3600, or specify 259200 (3*86400) in stead of 604800, and look at the resulting graphs:

In both cases the labels are centered halfway the first n seconds (1800 or 259200). Intrestingly, this does not work as nice in some cases. Look what happens when I use DAY:7:

The label is shifted, but not by half of 259200. I didn't look at the source why this happens. I guess it has something to do with the length of an interval (DAY in stead of WEEK) but I'm not sure and frankly I can't be bothered to look this up.

LFM

You've seen a couple of codes already, but I guess you would like to know more. RRDtool uses an OS library function called "strftime" to convert these codes into useful data. Not every implementation has exactly the same possibilities, so it is quite possible that yours is not capable of converting all codes. If you can, use the manual of your own OS (unix: man strftime). Else look at the manual page for rrdgraph_graph (in the RRDtool source, on Tobi's website) or use your favorite search engine.

Some of the codes I use very frequently are:

Wrapup

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 .