Fixing my rrd knowledge

April 28, 2016

I am using rrd databases for a quite a while now. Now and then I need to create a new database and I am constantly failing with this task. There are quite a number of reasons why - mostly I lost my references, my cheat sheets or I am too lazy to do the math. So here is -for me- a way how to create a rrd database without hurting yourself too much.

This is not a replacement for the official manpages, it’s just my quick reference!

At least that’s the way I am doing it, it might be wrong - but it works for me. Point out errors or problems. Thanks :)

The basic call is always the same, everything starts with:

    rrdtool create <filename.rrd> --step <steps> \
      DS:<name_of_datasource>:<ds type>:<heartbeat>:<min_value>:<max_value> \
      RRA:<combine_function>:<xff>:<steps combined>:<rows>

Let’s clarify a few things first. I’ve added some custom naming themes because some of the rrdtool names confuse me. Let’s run a grind down:


Specifies the interval in seconds that been used to update the rrd database. The default is 300, therefore if you are feeding your data every 5 minutes into the database you can ommit it.

name_of_datasource (DS)

Have a wonderful name for your datasource - aka the data you want to store in here. Remember it can be up to 19 chars with the character class [:alphanum:]

ds_type (DST)

Here you specify the different types for a data source, the most used one is GAUGE.

ds type usage
GAUGE Everything that you just measure. It doesn’t add up or something. Examples: Temperatures, Free memory, contract nunbers
COUNTER Something constantly increasing. Example: Network packages on an interface, your power meter at home
DCOUNTER Same as counter but with double precision floats
DERIVE Is for variations of a fixed number, people that come in or leave a room and track the total
DDERIVE Double precision floats - same as DERIVE
ABSOLUTE Take a value, then the counter is reset, puuh, I need an example here
COMPUTE Do some calculations with a formular with them. I need a good sample here


The heartbeat value tells you something about the time period that a value can be inserted until it’s considered an empty value. If you defined steps to 5 minutes (300 seconds = –step 300) and the heartbeat is set to 600 you can still insert the value at 9 minutes and 59 seconds. This helps with some variations when the server is under heavy load.


Set the min value for the data source here. Sometimes rrdtool seems to be pretty clever here. Just for safety set something here, usually I’ll set this to 0.


Set the max value for the data source here. If you have set the min_value to something it’s safe to set this to “U” - for unlimited.

combine_function (CF)

The combine functions determines which algorithm is used to combined the values. Typically you are looking for AVERAGE, however you can also go for MIN, MAX, LAST.


I never got into this so far - go with 0.5 seems to be safe. Bascically it’s a xfiles factor that determines the ratio between known and unknown values. It ranges from 0 - 1.


This is the number of samples that will be converted using the CF function to one value - also called the resolution. If you take a measurement every 5 minutes (–step 300) and use 12 samples to build a new value in the RRA the resolution of the RRA will be 1 hour. Due to the way that rrdtool works internally the result will be in seconds.


For how long will your store your data - so define the number of slots here. If data gets older, aka is from a later point than slots are available it will get overwriten.

Formula to calculate the rows

     rows = <time period> / ( <steps_combined> * <step interval> )

The time period specified how long you would like to store in this RRA (round robin archive). Typically you are looking for certain intervals. This value has to be specified in seconds.

Time unit seconds
1 day 86400
1 week 604800
1 month 2592000
3 month 7776000
6 month 15552000
1 year 31536000
3 years 94608000
5 years 157680000


    # Example
    resolution = step * samples
      resolution = 12 * 300 = 3600 (s)

In this case the resolution of the RRA is 3600 seconds, so 1 hour. Please note - the 12 single values will be combined with the CF function. In most case you will aim for the AVERAGE of the values.


comments powered by Disqus