Errand

Errand provides Ruby bindings for RRD functions (via librrd), and a clear API for interacting with RRDs.

Installing

Install Errand via RubyGems:

gem install errand

Or adding do your Gemfile:

gem 'errand'

Using

To start working with an RRD:

@rrd = Errand.new(:filename => "data.rrd")

This will either read an existing RRD, or stub out the bits to create a new one.

To create an RRD:

options = {
  :sources => [
    {
      :name => "Counter",
      :type => :counter,
      :heartbeat => 1800,
      :min => 0,
      :max => 4294967295
    }
  ],
  :archives => [
    {
      :function => :average,
      :xff => 0.5,
      :steps => 1,
      :rows => 2400
    }
  ]
}

@rrd.create(options)

To update said RRD:

@rrd.update(:sources => [{:name => "Counter", :value => 1}]

To fetch that data:

@rrd.fetch # <= {:start => Time, :end => Time,
                 :data =>  {"Counter" => [nil, nil, nil, 1]}

Check under spec/ for more usage examples.

Developing

Clone the repository:

git clone git@github.com:auxesis/errand.git

Suck down all the dependencies:

cd errand
bundle

Dependencies

Errand requires RRDtool version 1.2 or later. Some RRD functions such as rrddump are only available with the latest RRDtool.

Installation is standard. If you've installed the gem, you should be ready to go.

Otherwise, simply run:

ruby extconf.rb
make
make install

This should build a library named rrd.so in the current directory. If it doesn't, please report bugs at http://github.com/eric/rubyrrdtool/issues!

Testing

Testing is done with RSpec.

To run tests:

rake spec

Building the gem

Build the gem:

rake build

TODO

  • Extend documentation with more examples

License

Errand is distributed under the MIT license.