prrd 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 4c074fd1d609522279be5d2493075487a4b43403
+  data.tar.gz: 96b588b278c0f30d663ba3d8766b6e843d87936d
+SHA512:
+  metadata.gz: 3d1c7eb14b07162eb2c35b49ebc32de72cadded2d54b9783921440aa317f772350252d0ce27ec54b621ff3ffcb1358b4c4074a2736917ac9670e9c28ac090c9f
+  data.tar.gz: f6e18d680ae236f3b0cf09a6d43a970bfef9b8ca82040ea4e8b368c65a1aa835c171b04743e688f04f9b6025a860cbc829b0f409d2166eb87e2161901684d16a

data/Gemfile

@@ -0,0 +1,13 @@
+#!/usr/bin/env ruby
+
+# File: Gemfile
+# Time-stamp: <2014-09-22 22:39:57 pierre>
+# Copyright (C) 2014 Pierre Lecocq
+# Description: Gemfile for PRRD library
+
+source 'https://rubygems.org'
+
+# Utils
+gem 'rake'
+gem 'rspec'
+gem 'yard'

data/README.md

@@ -0,0 +1,223 @@
+# PRRD
+
+A (simple) rrdtool ruby interface
+
+## Disclaimer
+
+Hold on please, work in progress ...
+
+## Install
+
+During the development process, there is no gem available. It will be packaged when the first stable release is reached.
+
+To install PRRD, install dependencies and clone this repository:
+
+```
+sudo gem install bundler
+git clone https://github.com/pierre-lecocq/prrd
+cd prrd
+bundle install
+```
+
+## Usage
+
+### Require the library
+
+`require '/path/to/prrd/lib/prdd.rb'`
+
+### Define a database
+
+```
+database = PRRD::Database.new
+database.path = '/path/to/your/directory/sample.rrd'
+
+unless database.exists?
+
+  database.start = Time.now.to_i
+  database.step = 300
+
+  # Add datasources
+
+  ds = PRRD::Database::Datasource.new
+  ds.name = 'ds1'
+  ds.type = 'GAUGE'
+  ds.heartbeat = 600
+  ds.min = 0
+  ds.max = 'U'
+  database.add_datasource ds
+
+  ds = PRRD::Database::Datasource.new
+  ds.name = 'ds2'
+  ds.type = 'GAUGE'
+  ds.heartbeat = 600
+  ds.min = 0
+  ds.max = 'U'
+  database.add_datasource ds
+
+  # Add archives
+
+  ar = PRRD::Database::Archive.new
+  ar.cf = 'AVERAGE'
+  ar.xff = 0.5
+  ar.steps = 1
+  ar.rows = 576
+  database.add_archive ar
+
+  ar = PRRD::Database::Archive.new
+  ar.cf = 'AVERAGE'
+  ar.xff = 0.5
+  ar.steps = 6
+  ar.rows = 672
+  database.add_archive ar
+
+  ar = PRRD::Database::Archive.new
+  ar.cf = 'AVERAGE'
+  ar.xff = 0.5
+  ar.steps = 24
+  ar.rows = 732
+  database.add_archive ar
+
+  ar = PRRD::Database::Archive.new
+  ar.cf = 'AVERAGE'
+  ar.xff = 0.5
+  ar.steps = 144
+  ar.rows = 1460
+  database.add_archive ar
+
+  # Create
+
+  database.create
+
+end
+```
+
+### Update the database
+
+```
+value_ds1 = 125
+value_ds2 = 38
+
+database.update Time.now.to_i, value_ds1, value_ds2
+
+```
+
+### Generate the graph
+
+```
+graph = PRRD::Graph.new
+graph.path = '/path/to/your/directory/sample.png'
+graph.database = database
+graph.width = 600
+graph.height = 300
+graph.title = 'My graph'
+graph.vertical_align = 'My vertical label'
+
+# Optionally set colors
+
+graph.add_color PRRD::Graph::Color.new colortag: 'BACK', color: '#151515'
+graph.add_color PRRD::Graph::Color.new colortag: 'FONT', color: '#e5e5e5'
+graph.add_color PRRD::Graph::Color.new colortag: 'CANVAS', color: '#252525'
+graph.add_color PRRD::Graph::Color.new colortag: 'ARROW', color: '#ff0000'
+
+# Set definitions
+
+graph.add_definition PRRD::Graph::Definition.new vname: 'ds1', rrdfile: database.path, ds_name: 'ds1', cf: 'AVERAGE'
+graph.add_definition PRRD::Graph::Definition.new vname: 'ds2', rrdfile: database.path, ds_name: 'ds2', cf: 'AVERAGE'
+
+# Set lines
+
+graph.add_line PRRD::Graph::Line.new value: 'ds1', width: 3, color: PRRD.color(:blue), legend: 'Ds1'
+graph.add_line PRRD::Graph::Line.new value: 'ds2', color: PRRD.color(:blue), legend: 'Ds2'
+
+# Create graph
+
+graph.generate
+
+```
+
+## Syntaxes
+
+For each element of a database or a graph, there are alternative syntaxes to create them.
+
+Let's take an exemple with Datasources, but it is the same for Archives, Colors, Lines, Areas, ... and so on.
+
+(Note: each example in the `scripts` folder use a different syntax as a showcase of all different ways to write PRRD scripts)
+
+### Object properties
+
+```
+ds = PRRD::Database::Datasource.new
+ds.name = 'ds1'
+ds.type = 'GAUGE'
+ds.heartbeat = 600
+ds.min = 0
+ds.max = 'U'
+database.add_datasource ds
+
+ds = PRRD::Database::Datasource.new
+ds.name = 'ds2'
+ds.type = 'GAUGE'
+ds.heartbeat = 600
+ds.min = 0
+ds.max = 'U'
+database.add_datasource ds
+```
+
+### Hashes
+
+```
+ds = PRRD::Database::Datasource.new name: = 'ds1', type: 'GAUGE', heartbeat: 600, min: 0, max: 'U'
+database.add_datasource ds
+
+ds = PRRD::Database::Datasource.new name: = 'ds2', type: 'GAUGE', heartbeat: 600, min: 0, max: 'U'
+database.add_datasource ds
+```
+
+### Array of hashes
+
+```
+dss = [
+  PRRD::Database::Datasource.new({name: = 'ds1', type: 'GAUGE', heartbeat: 600, min: 0, max: 'U'}),
+  PRRD::Database::Datasource.new({name: = 'ds2', type: 'GAUGE', heartbeat: 600, min: 0, max: 'U'}),
+]
+
+database.add_datasources dss
+```
+
+### Add objects
+
+This syntax auto-detect the type and add it properly to the database or graph object
+
+```
+database << PRRD::Database::Datasource.new({name: = 'ds1', type: 'GAUGE', heartbeat: 600, min: 0, max: 'U'})
+graph << PRRD::Graph::Line.new({width: 2, value: = 'ds1', color: PRRD.color(:blue), legend: 'DS1'})
+```
+
+## Sample scripts
+
+PRRD provides some real-world sample scripts located in the `scripts` directory.
+
+- A `memory` script that graphs the consumption of memory and swap on your system
+- A `cpu` script that graphs the usage of your CPU
+- A `process` script that graphs the user and system processes
+- A `network` script that graphs the send and recv packaged on your network interface (eth0)
+
+To run them, simply type:
+
+```
+ruby scripts/memory.rb
+ruby scripts/cpu.rb
+ruby scripts/process.rb
+ruby scripts/network.rb
+```
+
+Before that, you may be ask to copy `scripts/config.rb-example` to `scripts/config.rb` and edit it to fit to your needs
+
+If you want to run them permanently, add these lines to your crontab (adpat *paths* and *username*):
+
+```
+*/5 *   * * *   username ruby /home/username/prrd/scripts/memory.rb > /dev/null
+*/5 *   * * *   username ruby /home/username/prrd/scripts/cpu.rb > /dev/null
+*/5 *   * * *   username ruby /home/username/prrd/scripts/process.rb > /dev/null
+*/5 *   * * *   username ruby /home/username/prrd/scripts/network.rb > /dev/null
+```

data/Rakefile

@@ -0,0 +1,35 @@
+#!/usr/bin/env ruby
+
+# File: Rakefile
+# Time-stamp: <2014-09-22 22:45:18 pierre>
+# Copyright (C) 2014 Pierre Lecocq
+# Description: Rakefile for PRRD library
+
+task :default => :help
+# rake help
+task :help do
+  puts 'PRRD - rrdtool ruby interface'
+  puts "\n" + 'Available rake tasks:'
+  puts ' * test: run rspec tests'
+  puts ' * code: run rubocop to verify code quality'
+  puts ' * doc: run yard to generate documentation'
+end
+
+# rake test
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:test)
+
+# rake code
+require 'rubocop/rake_task'
+desc 'Run RuboCop on the lib directory'
+RuboCop::RakeTask.new(:code) do |task|
+  task.patterns = ['lib/**/*.rb']
+  task.fail_on_error = false
+end
+
+# rake doc
+require 'yard'
+YARD::Rake::YardocTask.new do |t|
+  t.files = ['lib/**/*.rb']
+end
+task :doc => :yard

data/lib/prrd.rb

@@ -0,0 +1,189 @@
+#!/usr/bin/env ruby
+
+# File: prrd.rb
+# Time-stamp: <2014-10-01 21:59:18 pierre>
+# Copyright (C) 2014 Pierre Lecocq
+# Description: RRD ruby module
+
+$LOAD_PATH.unshift File.join(File.dirname(__FILE__))
+
+# Main PRRD module
+module PRRD
+  # Version
+  VERSION = [0, 2, 0].join('.')
+
+  # Class variables
+  @@debug_mode = false
+  @@colors = nil
+  @@bin = nil
+
+  # Activate debug mode
+  def self.activate_debug_mode
+    @@debug_mode = true
+  end
+
+  # Activate debug mode
+  def self.debug_mode
+    @@debug_mode
+  end
+
+  # Get rrdtool binary
+  # @return [String]
+  def self.bin
+    if @@bin.nil?
+      @@bin = `which rrdtool`.chomp
+      fail 'Install rrdtool. See http://oss.oetiker.ch/rrdtool/' if @@bin.nil?
+    end
+
+    @@bin
+  end
+
+  # Execute a command
+  # @param cmd [String]
+  # @param message [String, Nil]
+  # @return [String, Nil]
+  def self.execute(cmd, message = nil)
+    puts cmd if PRRD.debug_mode
+    `#{cmd}`
+
+    message if $CHILD_STATUS.nil? && !message.nil?
+  end
+
+  # Color class
+  class Color
+    # Accessors
+    attr_accessor :collection, :hexcode
+
+    # Constructor
+    # @param name [Symbol]
+    # @param tint [Symbol, nil]
+    # @param alpha [Symbol, nil]
+    def initialize(name, tint = nil, alpha = nil)
+      if name.is_a?(String) && name.include?('#')
+        @hexcode = name
+      else
+        @hexcode = to_hex(name, tint, alpha)
+      end
+    end
+
+    # Translate into hexcode
+    # @param name [Symbol]
+    # @param tint [Symbol, nil]
+    # @param alpha [Symbol, nil]
+    # @param [String]
+    def to_hex(name, tint = nil, alpha = nil)
+      if @collection.nil?
+        @collection = {
+          red: {light: '#EA644A', dark: '#CC3118'},
+          orange: {light: '#EC9D48', dark: '#CC7016'},
+          yellow: {light: '#ECD748', dark: '#C9B215'},
+          green: {light: '#54EC48', dark: '#24BC14'},
+          blue: {light: '#48C4EC', dark: '#1598C3'},
+          pink: {light: '#DE48EC', dark: '#B415C7'},
+          purple: {light: '#7648EC', dark: '#4D18E4'}
+        }
+      end
+
+      name = name.to_sym
+      tint = tint.nil? ? :light : tint.to_sym
+
+      fail "Unknown color #{name}" unless @collection.key? name
+      fail "Unknown tint #{tint}" unless @collection[name].key? tint
+
+      alpha.nil? ? @collection[name][tint] : @collection[name][tint] + alpha
+    end
+
+    # Darken the color
+    # @param percentage [Integer]
+    # @return [String]
+    def darken(percentage)
+      fail 'Can not operate on a non-hexadecimal color' if @hexcode.nil?
+
+      hexcode = @hexcode.gsub('#', '')
+      percentage = percentage.to_f / 100
+      rgb = hexcode.scan(/../).map { |c| c.hex }
+      rgb.map! { |c| (c.to_i * percentage).round }
+
+      "#%02x%02x%02x" % rgb
+    end
+
+    # Lighten the color
+    # @param percentage [Integer]
+    def lighten(percentage)
+      fail 'Can not operate on a non-hexadecimal color' if @hexcode.nil?
+
+      hexcode = @hexcode.gsub('#', '')
+      percentage = percentage.to_f / 100
+      rgb = hexcode.scan(/../).map { |c| c.hex }
+      rgb.map! { |c| [(c.to_i + 255 * percentage).round, 255].min }
+
+      "#%02x%02x%02x" % rgb
+    end
+
+    # String representation
+    def to_s
+      @hexcode
+    end
+  end
+
+  # Entity base class
+  class Entity
+    # Accessors
+    attr_accessor :data, :keys
+
+    # Constructor
+    def initialize(values = nil)
+      @data = {}
+
+      unless values.nil?
+        values.each do |k, v|
+          next unless @keys.include? k
+          send "#{k}=".to_sym, v
+        end
+      end
+    end
+
+    # Validate presence of keys in data collection
+    # @param keys [Array]
+    def validate_presence(*keys)
+      keys.each do |k|
+        fail 'Define a "%s" option' % k if !@data.key?(k) || @data[k].nil?
+      end
+    end
+
+    # Method missing
+    # @param m [Symbol]
+    # @param args [Array]
+    # @param block [Proc]
+    # @return [Boolean]
+    def method_missing(m, *args, &block)
+      ms = m.to_s
+      if ms.include? '='
+        ms = ms[0..-2]
+        if @keys.include? ms.to_sym
+          @data[ms.to_sym] = args[0]
+          return true
+        end
+      end
+
+      super
+    end
+  end
+end
+
+# Requires
+require 'prrd/database'
+require 'prrd/database/datasource'
+require 'prrd/database/archive'
+
+require 'prrd/graph'
+require 'prrd/graph/definition'
+require 'prrd/graph/colors'
+require 'prrd/graph/area'
+require 'prrd/graph/line'
+require 'prrd/graph/print'
+require 'prrd/graph/comment'
+require 'prrd/graph/hrule'
+require 'prrd/graph/vrule'
+require 'prrd/graph/shift'
+require 'prrd/graph/textalign'