= Introduction

rrd-ffi is a gem for using rrd actions in your ruby code.

You may use it in the raw format, as many rrd libs in languages like perl or python, or you can use it through the dsl we provide.

rrd-ffi uses ffi to wrap the librrd C bindings, not system calls.

IMPORTANT: You need librrd installed (version 1.3.1 or above, version 1.4.2 RECOMMENDED) in your system for this gem to work

= Basics

Here's what you need to know before starting.

== Installation

=== Notes

To install rrd-ffi, you will need to have librrd in your system.

Then, run sudo gem install rrd-ffi

If you are using Mac Ports you will have problems, so add the following to your .profile|.bashrc|.bash_profile file:

export RRD_LIB=/opt/local/lib/librrd.dylib

or

export LD_LIBRARY_PATH=/opt/local/lib

If you are not using MAC OS and still having problems, export the RRD_PATH variable with the path to your librrd file.

=== Installing librrd

Debian/Ubuntu: apt-get install librrd-dev

Fedora/Red Hat: yum install rrdtool-devel

Mac: port install rrdtool

From source: cd rrdtool-${rrdtool_version} ./configure --disable-ruby --prefix=/usr/local make make install

== Example Usage require "rrd" rrd = RRD::Base.new("myrrd.rrd")

Restoring a rrd file from xml

Notice that all '-' on flags become '_' like --force-overwrite => :force_overwrite

rrd.restore("myrrd.xml", :force_overwrite => true)

Fetching data from rrd

rrd.fetch(:average).each {|line| puts line.inspect}

Collecting information from rrd

puts rrd.info.to_yaml

Updating rrd (this rrd example has 3 datasources)

rrd.update Time.now, 500, nil, 30

Looking for the first and last entered dates

puts rrd.starts_at puts rrd.ends_at

Growing or Shrinking a rrd_file (create a resize.rrd file)

You need to know the RRA number (starting from 0)

rrd.resize(0, :grow => 10.days) rrd.resize(0, :shrink => 10.days)

Error handling

rrd.fetch(:unknown_function) # should return false puts rrd.error

For raising exceptions in methods, use the '!' at its end

rrd.fetch!(:unknown_function) # raises an error

=== DSLs

Creating a new rrd

rrd = RRD::Base.new("myrrd.rrd") rrd.create :start => Time.now - 10.seconds, :step => 5.minutes do datasource "memory", :type => :gauge, :heartbeat => 10.minutes, :min => 0, :max => :unlimited archive :average, :every => 10.minutes, :during => 1.year end

Generating a graph with memory and cpu usage from myrrd.rrd file

RRD.graph "graph.png", :title => "Test", :width => 800, :height => 250, :color => ["FONT#000000", "BACK#FFFFFF"] do area "myrrd.rrd", :cpu0 => :average, :color => "#00FF00", :label => "CPU 0" line "myrrd.rrd", :cpu0 => :average, :color => "#007f3f" line "myrrd.rrd", :memory => :average, :color => "#0000FF", :label => "Memory" end

Generating a graph or raising an exception if something bad happens

RRD.graph! "graph.png", :title => "Test", :width => 800, :height => 250, :color => ["FONT#000000", "BACK#FFFFFF"] do area "myrrd.rrd", :cpu0 => :average, :color => "#00FF00", :label => "CPU 0" line "myrrd.rrd", :cpu0 => :average, :color => "#007f3f" line "myrrd.rrd", :memory => :average, :color => "#0000FF", :label => "Memory" end

Generating a more complex graph using advanced DSL

RRD.graph IMG_FILE, :title => "Test", :width => 800, :height => 250, :start => Time.now - 1.day, :end => Time.now do for_rrd_data "cpu0", :cpu0 => :average, :from => RRD_FILE for_rrd_data "mem", :memory => :average, :from => RRD_FILE using_calculated_data "half_mem", :calc => "mem,2,/" using_value "mem_avg", :calc => "mem,AVERAGE" draw_line :data => "mem", :color => "#0000FF", :label => "Memory", :width => 1 draw_area :data => "cpu0", :color => "#00FF00", :label => "CPU 0" print_comment "Information - " print_value "mem_avg", :format => "%6.2lf %SB" end

Generating a graph using shift

RRD.graph IMG_FILE, :title => "Test", :width => 800, :height => 250, :start => Time.now - 1.day, :end => Time.now do for_rrd_data "mem", :memory => :average, :from => RRD_FILE for_rrd_data "mem_yesterday", :memory => :average, :from => RRD_FILE, :start => Time.now - 2.day draw_line :data => "mem", :color => "#0000FF", :label => "Memory", :width => 1 shift :mem_yesterday => 1.day draw_line :data => "mem_yesterday", :color => "#0000FF", :label => "Yesterday memory", :width => 1 end

== Raw API Usage

Normal methods return false on error, or the expected result otherwise.

# Creating a rrd file

RRD::Wrapper.create "myrrd.rrd", "--step", "300", "DS:ifOutOctets:COUNTER:1800:0:4294967295", "RRA:AVERAGE:0.5:1:2016"

# Fetching average data

RRD::Wrapper.fetch "myrrd.rrd", "AVERAGE"

# Looking for the first entered dates

RRD::Wrapper.first "myrrd.rrd"

# Creating a graph

RRD::Wrapper.graph("graph.png", "DEF:data=myrrd.rrd:ifOutOctets:AVERAGE", "LINE1:data#0000FF:Output bytes")

# Getting info on a rrd file

RRD::Wrapper.info("myrrd.rrd")

Looking for the last entered dates

RRD::Wrapper.last "myrrd.rrd"

# Getting last data inserted on a rrd
RRD::Wrapper.last_update "myrrd.rrd"

# Resizing a rrd file RRA

RRD::Wrapper.resize "myrrd.rrd", "0", "GROW", "10"

Restoring a rrd file from xml

RRD::Wrapper.restore "myrrd.xml", "myrrd.rrd"

# Tuning a rrd file

RRD::Wrapper.tune "myrrd.rrd", "--minimum", "memory:5"

Updating rrd with a new value

RRD::Wrapper.update "myrrd.rrd", "N:500000000"

Getting the error happened

puts RRD::Wrapper.error

Bang methods raise exception on error.

Throwing the error if happens

RRD::Wrapper.fetch! "myrrd.rrd", "WRONG FUNCTION"