Title: rrdtool howto
Subject: syntax to work with rrdtool
#########################################
 # Create a database in rrdtool:
 #   DB starts from noon, 7th of march, 1999
 #   holds one data source (DS) named ``speed'' that gets built from a counter, on 5 minute intervles.
 #   holds one round robin archives (RRAs) one averages the data every time it is read and keeps 24 samples (24 times 5 minutes is 2 hours).
 #   holds one round robin archives (RRAs) one averages the other averages 6 values (half hour) and contains 10 of such averages (eg 5 hours)
# 
# 7th of march, 1999
# data source name=speed, build from couter in 5 minute intervals.
# Averages data each time it is read, and keeps 24 samples, and cycles data every 2 hours (5min x 24 samples = 2 hours).
# Counts 6 samples, 1sample/5 minutes, then takes an average.  Holds 10 averages. (6samples * 5 minutes x 10 averages = 5 hours )
##RRA:<Operation>:<?>:<sampling intervle>:<# of samples for Opeation calculation>:<# of  Opeation calculation to store>
#-------------------------------------------------------------
rrdtool create test.rrd \
 --start 920804400 \
 DS:speed:COUNTER:600:U:U \
 RRA:AVERAGE:0.5:1:24 \
 RRA:AVERAGE:0.5:6:10 
#-------------------------------------------------------------
#We now have to fill our database with some numbers. We'll pretend to
#have read the following numbers:
# 12:05  12345 KM
# 12:10  12357 KM
# 12:15  12363 KM
# 12:20  12363 KM
# 12:25  12363 KM
# 12:30  12373 KM
# 12:35  12383 KM
# 12:40  12393 KM
# 12:45  12399 KM
# 12:50  12405 KM
# 12:55  12411 KM
# 13:00  12415 KM
# 13:05  12420 KM
# 13:10  12422 KM
# 13:15  12423 KM
#We fill the database as follows:

rrdtool update test.rrd 920804700:12345 920805000:12357 920805300:12363 \
920805600:12363 920805900:12363 920806200:12373 920806500:12383 \
920806800:12393 920807100:12399 920807400:12405 920807700:12411 \
920808000:12415 920808300:12420 920808600:12422 920808900:12423

#-------------------------------------------------------------
#We can now retrieve the data from our database using ``rrdtool fetch'':
 rrdtool fetch test.rrd AVERAGE --start 920804400 --end 920809200

#-------------------------------------------------------------
#Create some graphics
# create speed.gif
# starts =	12:00 
# ends   = 	13:00
# line =	2 pixels high
# color =	red

 rrdtool graph speed.gif \
 --start 920804400 --end 920808000 \
 DEF:myspeed=test.rrd:speed:AVERAGE \
 LINE2:myspeed#FF0000
 color is red
#-------------------------------------------------------------
# Colors.
#   red     #FF0000
#   green   #00FF00
#   blue    #0000FF
#   magenta #FF00FF     (mixed red with blue)
#   gray    #555555     (one third of all components)
#-------------------------------------------------------------
#Graphics with some math  
# create speed2.gif
# starts =	12:00 
# ends   = 	13:00
# line =	2 pixels high
# color =	red
# CDEF part and are in Reverse Polish Notation
#Take the data source "myspeed" and the number 1000; multiply those

rrdtool graph speed2.gif \
 --start 920804400 --end 920808000 \
 --vertical-label m/s \
 DEF:myspeed=test.rrd:speed:AVERAGE \
 CDEF:realspeed=myspeed,1000,*  \
 LINE2:realspeed#FF0000
 
#-------------------------------------------------------------
#   display kilometers per hour
# To change a value that is measured in meters per second:
# -*- Calculate meters per hour: value * 3600
# -*- Calculate kilometers per hour: value / 1000
# -*- Together this makes: value * (3600/1000) == value * 3.6
rrdtool graph speed3.gif                           \
      --start 920804400 --end 920808000               \
      --vertical-label km/h                           \
      DEF:myspeed=test.rrd:speed:AVERAGE              \
      "CDEF:kmh=myspeed,3600,*"                       \
      CDEF:fast=kmh,100,GT,kmh,0,IF                   \
      CDEF:good=kmh,100,GT,0,kmh,IF                   \
      HRULE:100#0000FF:"Maximum allowed"              \
      AREA:good#00FF00:"Good speed"                   \
      AREA:fast#FF0000:"Too fast"
      
      
#  Check if kmh is greater than 100    ( kmh,100 ) GT
#  If so, return 0, else kmh           ((( kmh,100 ) GT ), 0, kmh) IF

# For the other speed switch arount the end of the line:

#  Check if kmh is greater than 100    ( kmh,100 ) GT
#  If so, return kmh, else return 0    ((( kmh,100) GT ), kmh, 0) IF

rrdtool graph speed4.gif                           \
      --start 920804400 --end 920808000               \
      --vertical-label km/h                           \
      DEF:myspeed=test.rrd:speed:AVERAGE              \
      "CDEF:kmh=myspeed,3600,*"                       \
      CDEF:fast=kmh,100,GT,100,0,IF                   \
      CDEF:over=kmh,100,GT,kmh,100,-,0,IF             \
      CDEF:good=kmh,100,GT,0,kmh,IF                   \
      HRULE:100#0000FF:"Maximum allowed"              \
      AREA:good#00FF00:"Good speed"                   \
      AREA:fast#550000:"Too fast"                     \
      STACK:over#FF0000:"Over speed"
#-------------------------------------------------------------
# curent time can be calculated with 
# perl -e 'print time, "\n" '
# date
#or by specifying an 'N' in the rrdtool
   
#Get the value, put it in variable "$speed"
rrdtool update speed.rrd N:$speed