Introduction

Many of the postings about using rrdtool reference this example setup.  This example is representative of the type of data frequently gathered as part of routine system monitoring.  It has been designed to facilitate the illustration of the techniques and problems referenced in the other postings and is not necessarily representative of actual system monitoring conditions.  While a more typical usage would probably separate out groups of the statistics into several files, this example collects them all in a single file for the sake of simplicity.

The rrdtool must be installed prior to any attempt to create or load data.  It is readily available as a package for installation for a number of Unix distributions or may be downloaded directly from the developer’s website and built locally.

Creating the RRD

The example RRD creates a file named sysinfo.rrd, a start date of Jan 1, 2009 00:00:00 PST (Unix epoch time 1230796800) and a Primary Data Point (PDP) step value of 300 seconds.  There are a number of different measurements that it retains: the system load, temperature, CPU fan speed, amount of used disk space, rate of change in the use of disk space, and the number of bytes written or read from the disk.  For these measurements, it maintains five Round Robin Archives (RRA):  three RRAs with a resolution of 5 minutes spanning 31 days using the AVERAGE, MIN, and MAX consolidation functions, a RRA with a resolution of 15 minutes for 90 days, and a RRA with a resolution of 1 hour for 365 days.

rrdtool create sysinfo.rrd –start 1230796800 –step 300 \
DS:load:GAUGE:600:0:U \
DS:temperature:GAUGE:600:0:500 \
DS:cpu_fan:GAUGE:600:0:U \
DS:disk_used:GAUGE:600:0:U \
DS:disk_change:DERIVE:600:U:U \
DS:disk2_used:GAUGE:600:0:U \
DS:disk2_change:DERIVE:600:0:U \
DS:bytes_written:COUNTER:600:0:U \
DS:bytes_read:COUNTER:600:0:U \
RRA:AVERAGE:0.5:1:8928 \
RRA:MIN:0.5:1:8928 \
RRA:MAX:0.5:1:8928 \
RRA:AVERAGE:0.5:3:8640 \
RRA:AVERAGE:0.5:12:8760

Adding Data

The general format for adding data to the RRD is through the update command.  The general format for adding a set of datapoints for the same time value is as follows:

rrdtool update filename timestamp:DS1[:DS2][:DS3]…

filename is the name of the RRD to be updated.  An update command can update only a single RRD file at a time.

timestamp is the time of the event.  This is typically specified in the standard Unix epoch format (number of seconds elapsed since Jan 1, 1970 UTC), however it may also be represented as “N” (for Now) which will insert the data using the current time value.  An alternate format may also be specified using the formats as accepted by the at command.  (See the manual page for the at command for more details on the time format rrdtool supports.)  If the at format is used, the “@” symbol should be used to separate the timestamp from the data values instead of the “:” character.

DS is the value of the data point(s) that are to be inserted into the RRD for the time specified.  The data points are processed in the same order as the Data Sources were specified when the RRD was created.  If there is no data for a particular DS, then a “U” (for Unknown) should be used instead.  If there is more than one DS to be updated in the RRD, the values should be separated by a “:” character.

An alternate update format is also available which may assign a unique time value for each data point:

rrdtool update filename timestamp:DS1 [timestamp:DS2] [timestamp:DS3]…

Data Generation

The perl script sysinfo-sample.pl is available which will create the RRD as well as populate it with a full year’s worth of data.  The data is randomly generated but should bear enough semblance to real data to help illustrate the concepts.  Also, because it is randomly generated it will result in different results each time it is run.

Please note that this script will automatically overwrite any previous instance of the sysinfo.rrd file in the working directory.

1. Create a directory that will hold the example data and associated files.

   mkdir rrd_example

2. Download the sysinfo-sample.pl file into the newly created directory.
3. Verify the permissions on the perl script are set as executable.

   chmod 0755 sysinfo-sample.pl

4. Execute the perl script and wait for the command prompt to reappear.  (This may take 5-15 minutes depending on the speed of your system.)

   ./sysinfo-sample.pl

Upon completion, a file named sysinfo.rrd should be created in the working directory.  It will be filled with one year’s worth of data starting on Jan 1, 2009.