Python RRDTool Tutorial

pythonRRDtool is the OpenSource industry standard, high performance data logging and graphing system for time series data.

For this tutorial I’m going to assume you understand how to get RRDTool installed and working from the command line. If not you should take a look at this tutorial (if you are in a hurry look at the “A Real World Example” section) or any of the tutorials on this page.

Setup and introduction

Py-rrdtool wrapper implementation has been written from the scratch (without SWIG). So we will require python dev file for compiling the py-rrdtool module.

$ sudo apt-get install python-dev

Download the Python RRDTool from here.

$ tar xfz py-rrdtool-1.0b1.tar.gz
$ cd py-rrdtool-1.0b1
$ sudo python install

Creating a RRD

We first need to create a database for our data. For these examples we will be creating a database that could be used for generating network graphs. This database is created for updates every 5 minutes (300 seconds), has input and output counters that store data for the average and max counts and stores enough samples for hourly, daily, monthly and yearly graphs of both average and max.

import sys
import rrdtool
ret = rrdtool.create("net.rrd", "--step", "300", "--start", '0',
if ret:
 print rrdtool.error()

After running you will have a file called net.rrd in the current directory. This is your RRD and will contain all the samples for your graphs.

For more information on the options to rrd_create see: rrdcreate

Updating a RRD

The next step is to update your RRD on the frequency you set when you created it. In the case above the frequency was set to 5 minutes (300 seconds). The following script generates random input and output values as input to the update function, sleeps for 300 seconds and then loops.

import sys
import time
import random
import rrdtool
total_input_traffic = 0
total_output_traffic = 0
while 1:
 total_input_traffic += random.randrange(1000, 1500)
 total_output_traffic += random.randrange(1000, 3000)
 ret = rrdtool.update('speed.rrd','N:' + `total_input_traffic` + ':' + `total_output_traffic`);
 if ret:
 print rrdtool.error()

Displaying RRD data as a graph

Now that you have data in your RRD you will want to graph it. The following code will graph the average input and output for 1 day as well as the max for that day.

import sys
import rrdtool
ret = rrdtool.graph( "net.png", "--start", "-1d", "--vertical-label=Bytes/s",
 "AREA:inoctets#00FF00:In traffic",
 "LINE1:outoctets#0000FF:Out traffic\\r",
 "GPRINT:inbits:AVERAGE:Avg In traffic\: %6.2lf %Sbps",
 "COMMENT:  ",
 "GPRINT:inbits:MAX:Max In traffic\: %6.2lf %Sbps\\r",
 "GPRINT:outbits:AVERAGE:Avg Out traffic\: %6.2lf %Sbps",
 "GPRINT:outbits:MAX:Max Out traffic\: %6.2lf %Sbps\\r")

You should end up with a file named net.png in your working directory that looks something like:


You can also do weekly and monthly graphs by changing the start parameter to -1w or -1m:



For more information on the options to rrd_graph see: rrdgraph