munin-ruby 0.2.1

data/.gitignore

@@ -0,0 +1,42 @@
+!.gitignore
+*.gem
+*.rbc
+*.sw[a-p]
+*.tmproj
+*.tmproject
+*.un~
+*~
+.DS_Store
+.Spotlight-V100
+.Trashes
+._*
+.bundle
+.config
+.directory
+.elc
+.redcar
+.yardoc
+/.emacs.desktop
+/.emacs.desktop.lock
+Desktop.ini
+Gemfile.lock
+Icon?
+InstalledFiles
+Session.vim
+Thumbs.db
+\#*\#
+_yardoc
+auto-save-list
+coverage
+doc/
+lib/bundler/man
+pkg
+pkg/*
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+tmtags
+tramp
+lib/test.rb

data/.rspec

@@ -0,0 +1,3 @@
+--color
+--backtrace
+--format=nested

data/README.md

@@ -0,0 +1,165 @@
+# Munin-Ruby
+
+Munin-ruby is a sockets-based ruby client library to communicate and fetch information from munin-node servers.
+
+## Installation
+
+Simple install using rubygems:
+
+```
+gem install munin-ruby
+```
+
+## Usage
+
+Just require the gem and you're good to go.
+
+```ruby
+require 'munin-ruby'
+
+node = Munin::Node.new
+node.version # => 1.4.4
+```
+
+### Connections
+
+```ruby
+# Connects to 127.0.0.1:4949
+node = Munin::Node.new
+node = Munin::Node.new('YOUR_HOST', YOUR_PORT)
+```
+
+If munin-node has any restrictions on IP addresses, client will trigger ```Munin::AccessDenied``` exception.
+
+By default client will reconnect if connection was lost. To disable that specify ```false``` after port option.
+
+```ruby
+node = Munin::Node.new('YOUR_HOST', 4949, false)
+```
+
+Ways to disconnect:
+
+```
+# Disconnect from server
+node.disconnect
+node.connection.close
+```
+
+In case if automatic reconnection was enabled, service will establish connection even after you call 'disconnect' method.
+
+To force client not to open connection: ```node.disconnect(false)```. 
+
+This will trigger ```Munin::ConnectionError``` on any client calls.
+
+### Services and metrics
+
+See what's available on server:
+
+```ruby
+services = node.list 
+
+# => ["cpu","df", "df_inode", "entropy", "forks", ...]
+```
+
+#### Get service configuration
+
+```ruby
+config = node.config('cpu')
+```
+
+This will produce the following result:
+
+```
+{"graph"=>
+  {"title"=>"CPU usage",
+   "order"=>"system user nice idle iowait irq softirq",
+   "args"=>
+    {"raw"=>"--base 1000 -r --lower-limit 0 --upper-limit 400",
+     "parsed"=>{"base"=>"1000", "lower-limit"=>"0", "upper-limit"=>"400"}},
+   "vlabel"=>"%",
+   "scale"=>"no",
+   "info"=>"This graph shows how CPU time is spent.",
+   "category"=>"system",
+   "period"=>"second"},
+ "metrics"=>
+  {"system"=>
+    {"label"=>"system",
+     "draw"=>"AREA",
+     "min"=>"0",
+     "type"=>"DERIVE",
+     "info"=>"CPU time spent by the kernel in system activities"},
+   "user"=>
+    {"label"=>"user",
+     "draw"=>"STACK",
+     "min"=>"0",
+     "type"=>"DERIVE",
+     "info"=>"CPU time spent by normal programs and daemons"},
+   "nice"=>
+    {"label"=>"nice",
+     "draw"=>"STACK",
+     "min"=>"0",
+     "type"=>"DERIVE",
+     "info"=>"CPU time spent by nice(1)d programs"},
+   "idle"=>
+    {"label"=>"idle",
+     "draw"=>"STACK",
+     "min"=>"0",
+     "type"=>"DERIVE",
+     "info"=>"Idle CPU time"},
+   "iowait"=>
+    {"label"=>"iowait",
+     "draw"=>"STACK",
+     "min"=>"0",
+     "type"=>"DERIVE",
+     "info"=>
+      "CPU time spent waiting for I/O operations to finish when there is nothing else to do."},
+   "irq"=>
+    {"label"=>"irq",
+     "draw"=>"STACK",
+     "min"=>"0",
+     "type"=>"DERIVE",
+     "info"=>"CPU time spent handling interrupts"},
+   "softirq"=>
+    {"label"=>"softirq",
+     "draw"=>"STACK",
+     "min"=>"0",
+     "type"=>"DERIVE",
+     "info"=>"CPU time spent handling \"batched\" interrupts"},
+   "steal"=>
+    {"label"=>"steal",
+     "draw"=>"STACK",
+     "min"=>"0",
+     "type"=>"DERIVE",
+     "info"=>
+      "The time that a virtual CPU had runnable tasks, but the virtual CPU itself was not running"}}}
+```
+
+#### Fetch a single service
+
+```ruby
+service = node.fetch('cpu')
+```
+
+Output:
+
+```
+{"user"=>"140349907",
+ "nice"=>"0",
+ "system"=>"19694121",
+ "idle"=>"536427034",
+ "iowait"=>"6455996",
+ "irq"=>"445",
+ "softirq"=>"482942",
+ "steal"=>"635801"}
+```
+
+  
+## License
+
+Copyright © 2011 Dan Sosedoff.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,11 @@
+#!/usr/bin/env rake
+
+require "bundler"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.pattern = 'spec/*_spec.rb'
+end
+
+task :default => :spec
+task :test => :spec

data/lib/munin-ruby.rb

@@ -0,0 +1,6 @@
+require 'munin-ruby/version'
+require 'munin-ruby/errors'
+require 'munin-ruby/parser'
+require 'munin-ruby/cache'
+require 'munin-ruby/connection'
+require 'munin-ruby/node'

data/lib/munin-ruby/cache.rb

@@ -0,0 +1,34 @@
+module Munin
+  module Cache
+    def cache(key)
+      raise RuntimeError, "Block required." unless block_given?
+      data = cache_get(key)
+      if data.nil?
+        data = yield
+        cache_set(key, data)
+      end
+      data
+    end
+    
+    def flush_cache
+      instance_variables.select { |l| l =~ /^@cache_/ }.each do |var|
+        remove_instance_variable(var)
+      end
+      true
+    end
+    
+    protected
+    
+    def cache_key(key)
+      "@cache_#{key.gsub(/[\.-]/,'__')}".to_sym
+    end
+      
+    def cache_get(key)
+      instance_variable_get(cache_key(key))
+    end
+    
+    def cache_set(key, value)
+      instance_variable_set(cache_key(key), value)
+    end
+  end
+end

data/lib/munin-ruby/connection.rb

@@ -0,0 +1,98 @@
+require 'socket'
+
+module Munin
+  class Connection
+    include Munin::Parser
+    
+    attr_reader :host, :port
+    
+    # Initialize a new connection to munin-node server
+    #
+    # host - Server host (default: 127.0.0.1)
+    # port - Server port (default: 4949)
+    #
+    def initialize(host='127.0.0.1', port=4949, reconnect=true)
+      @host      = host
+      @port      = port
+      @socket    = nil
+      @connected = false
+      @reconnect = reconnect
+    end
+    
+    # Returns true if socket is connected
+    #
+    def connected?
+      @connected == true
+    end
+    
+    # Establish connection to the server
+    #
+    def open
+      begin
+        @socket = TCPSocket.new(@host, @port)
+        @socket.sync = true
+        welcome = @socket.gets
+        unless welcome =~ /^# munin node at/
+          raise Munin::AccessDenied
+        end
+        @connected = true
+      rescue Errno::ETIMEDOUT, Errno::ECONNREFUSED, Errno::ECONNRESET => ex
+        raise Munin::ConnectionError, ex.message
+      rescue EOFError
+        raise Munin::AccessDenied
+      rescue Exception => ex
+        raise Munin::ConnectionError, ex.message
+      end
+    end
+    
+    # Close connection
+    #
+    def close(reconnect=true)
+      if connected?
+        @socket.flush
+        @socket.shutdown
+        @connected = false
+        @reconnect = reconnect
+      end
+    end
+    
+    # Send a string of data followed by a newline symbol
+    #
+    def send_data(str)
+      if !connected?
+        if !@socket.nil? && @reconnect == false
+          raise Munin::ConnectionError, "Not connected."
+        else
+          open
+        end
+      end
+      @socket.puts("#{str.strip}\n")
+    end
+    
+    # Reads a single line from socket
+    #
+    def read_line
+      begin
+        @socket.gets.to_s.strip
+      rescue Errno::ETIMEDOUT, Errno::ECONNREFUSED, Errno::ECONNRESET, EOFError => ex
+        raise Munin::ConnectionError, ex.message
+      end
+    end
+    
+    # Reads a packet of data until '.' reached
+    #
+    def read_packet
+      begin
+        lines = []
+        while(str = @socket.readline.to_s) do
+          break if str.strip == '.'
+          lines << str.strip
+        end
+        parse_error(lines)
+        lines
+      rescue Errno::ETIMEDOUT, Errno::ECONNREFUSED, Errno::ECONNRESET, EOFError => ex
+        raise Munin::ConnectionError, ex.message
+      end
+    end
+  end
+end

data/lib/munin-ruby/errors.rb

@@ -0,0 +1,8 @@
+module Munin
+  class MuninError      < StandardError ; end
+  class ConnectionError < MuninError    ; end
+  class AccessDenied    < MuninError    ; end
+  class InvalidResponse < MuninError    ; end
+  class UnknownService  < MuninError    ; end
+  class BadExit         < MuninError    ; end
+end

data/lib/munin-ruby/node.rb

@@ -0,0 +1,124 @@
+require 'digest/md5'
+
+module Munin
+  class Node
+    include Munin::Parser
+    include Munin::Cache
+    
+    attr_reader :connection
+    
+    # Initialize a new Node instance
+    #
+    # host      - Server host
+    # port      - Server port
+    # reconnect - Reconnect if connection was closed (default: true)
+    #
+    
+    def initialize(host='127.0.0.1', port=4949, reconnect=true)
+      @connection = Munin::Connection.new(host, port, reconnect)
+    end
+    
+    # Open service connection
+    #
+    def connect
+      connection.open
+    end
+    
+    # Close server connection
+    #
+    def disconnect(reconnect=true)
+      connection.close(reconnect)
+    end
+    
+    # Get a node version
+    #
+    def version
+      cache 'version' do
+        connection.send_data("version")
+        parse_version(connection.read_line)
+      end
+    end
+
+    # Get a list of all available nodes
+    #
+    def nodes
+      cache 'nodes' do 
+        connection.send_data("nodes")
+        connection.read_line.split
+      end
+    end
+    
+    # Get a list of all available metrics
+    #
+    def list(node = nil)
+      cache "list_#{node || 'default'}" do
+        connection.send_data("list #{node}")
+        if ( line = connection.read_line ) != "."
+          line.split
+        else
+          connection.read_line.split
+        end
+      end
+    end
+
+    # Get a configuration information for service
+    #
+    # services - Name of the service, or list of service names
+    #
+    def config(services, raw=false)
+      unless [String, Array].include?(services.class)
+        raise ArgumentError, "Service(s) argument required"
+      end
+      
+      results       = {}
+      names         = [services].flatten.uniq
+      
+      if names.empty?
+        raise ArgumentError, "Service(s) argument required"
+      end
+      
+      key = 'config_' + Digest::MD5.hexdigest(names.to_s) + "_#{raw}"
+      
+      cache(key) do
+        names.each do |service|
+          begin
+            connection.send_data("config #{service}")
+            lines = connection.read_packet 
+            results[service] = raw ? lines.join("\n") : parse_config(lines)
+          rescue UnknownService, BadExit
+            # TODO
+          end
+        end
+        results
+      end
+    end
+    
+    # Get all service metrics values
+    #
+    # services - Name of the service, or list of service names
+    #
+    def fetch(services)
+      unless [String, Array].include?(services.class)
+        raise ArgumentError, "Service(s) argument required"
+      end
+      
+      results = {}
+      names   = [services].flatten
+      
+      if names.empty?
+        raise ArgumentError, "Service(s) argument required"
+      end
+      
+      names.each do |service|
+        begin
+          connection.send_data("fetch #{service}")
+          lines = connection.read_packet
+          results[service] =  parse_fetch(lines)
+        rescue UnknownService, BadExit
+          # TODO
+        end
+      end
+      results
+    end
+  end
+end

data/lib/munin-ruby/parser.rb

@@ -0,0 +1,75 @@
+module Munin
+  module Parser  
+    # Parse a version request
+    #
+    def parse_version(line)
+      if line =~  /^munins node on/
+        line.split.last
+      else
+        raise Munin::InvalidResponse, "Invalid version response"
+      end
+    end
+    
+    # Process response
+    #
+    def process_data(lines)  
+      data = {}
+      lines.each do |line|
+        line = line.split
+        key = line.first.split('.value').first
+        data[key] = line.last
+      end
+      data
+    end
+    
+    # Parse 'config' request
+    #
+    def parse_config(data)
+      config = {'graph' => {}, 'metrics' => {}}
+      data.each do |l|
+        if l =~ /^graph_/
+          key_name, value = l.scan(/^graph_([\w]+)\s(.*)/).flatten
+          config['graph'][key_name] = value
+        elsif l =~ /^[a-z]+\./
+          matches = l.scan(/^([a-z\d\-\_]+)\.([a-z\d\-\_]+)\s(.*)/).flatten
+          config['metrics'][matches[0]] ||= {}
+          config['metrics'][matches[0]][matches[1]] = matches[2]
+        end
+      end
+      
+      # Now, lets process the args hash
+      if config['graph'].key?('args')
+        config['graph']['args'] = parse_config_args(config['graph']['args'])   
+      end
+      
+      config
+    end
+    
+    # Parse 'fetch' request
+    #
+    def parse_fetch(data)
+      process_data(data)
+    end
+    
+    # Detect error from output
+    #
+    def parse_error(lines)
+      if lines.size == 1
+        case lines.first
+          when '# Unknown service' then raise UnknownService
+          when '# Bad exit'        then raise BadExit
+        end
+      end
+    end
+    
+    # Parse configuration arguments
+    #
+    def parse_config_args(args)
+      result = {}
+      args.scan(/--?([a-z\-\_]+)\s([\d]+)\s?/).each do |arg|
+        result[arg.first] = arg.last
+      end
+      {'raw' => args, 'parsed' => result}
+    end
+  end
+end

data/lib/munin-ruby/version.rb

@@ -0,0 +1,5 @@
+module Munin
+  unless defined?(::Munin::VERSION)
+    VERSION = '0.2.1'
+  end
+end

data/munin-ruby.gemspec

@@ -0,0 +1,19 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/munin-ruby/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.name            = "munin-ruby"
+  gem.version         = Munin::VERSION.dup
+  gem.author          = "Dan Sosedoff"
+  gem.email           = "dan.sosedoff@gmail.com"
+  gem.homepage        = "http://github.com/sosedoff/munin-ruby"
+  gem.description     = "Munin Node client"
+  gem.summary         = "Ruby client library to communicate with munin-node servers"
+  
+  gem.files         = `git ls-files`.split("\n")
+  gem.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  gem.executables   = `git ls-files -- bin/*`.split("\n").map{|f| File.basename(f)}
+  gem.require_paths = ['lib']
+  
+  gem.add_development_dependency 'rspec', '~> 2.6'
+end

data/spec/fixtures/config.txt

@@ -0,0 +1,47 @@
+config memory
+graph_args --base 1024 -l 0 --upper-limit 16175665152
+graph_vlabel Bytes
+graph_title Memory usage
+graph_category system
+graph_info This graph shows what the machine uses memory for.
+graph_order apps page_tables swap_cache slab cached buffers free swap 
+apps.label apps
+apps.draw AREA
+apps.info Memory used by user-space applications.
+buffers.label buffers
+buffers.draw STACK
+buffers.info Block device (e.g. harddisk) cache. Also where "dirty" blocks are stored until written.
+swap.label swap
+swap.draw STACK
+swap.info Swap space used.
+cached.label cache
+cached.draw STACK
+cached.info Parked file data (file content) cache.
+free.label unused
+free.draw STACK
+free.info Wasted memory. Memory that is not used for anything at all.
+slab.label slab_cache
+slab.draw STACK
+slab.info Memory used by the kernel (major users  are caches like inode, dentry, etc).
+swap_cache.label swap_cache
+swap_cache.draw STACK
+swap_cache.info A piece of memory that keeps track of pages that have been fetched from swap but not yet been modified.
+page_tables.label page_tables
+page_tables.draw STACK
+page_tables.info Memory used to map between virtual and physical memory addresses.
+vmalloc_used.label vmalloc_used
+vmalloc_used.draw LINE2
+vmalloc_used.info 'VMalloc' (kernel) memory used
+committed.label committed
+committed.draw LINE2
+committed.info The amount of memory allocated to programs. Overcommitting is normal, but may indicate memory leaks.
+mapped.label mapped
+mapped.draw LINE2
+mapped.info All mmap()ed pages.
+active.label active
+active.draw LINE2
+active.info Memory recently used. Not reclaimed unless absolutely necessary.
+inactive.label inactive
+inactive.draw LINE2
+inactive.info Memory not currently used.
+.

data/spec/fixtures/fetch.txt

@@ -0,0 +1,15 @@
+fetch memory
+slab.value 710025216
+swap_cache.value 823296
+page_tables.value 27803648
+vmalloc_used.value 9228288
+apps.value 1219354624
+free.value 204206080
+buffers.value 2046074880
+cached.value 11967377408
+swap.value 2961408
+committed.value 2358927360
+mapped.value 1625862144
+active.value 5164363776
+inactive.value 10039930880
+.

data/spec/fixtures/list.txt

@@ -0,0 +1 @@
+cpu memory load

data/spec/fixtures/version.txt

@@ -0,0 +1 @@
+munins node on hostname version: 1.4.4

data/spec/node_spec.rb

@@ -0,0 +1,5 @@
+require 'spec_helper'
+
+describe 'Munin::Node' do
+  # TODO
+end

data/spec/parser_spec.rb

@@ -0,0 +1,27 @@
+require 'spec_helper'
+
+class ParseTester
+  include Munin::Parser
+end
+
+describe Munin::Parser do
+  before :each do
+    @parser = ParseTester.new
+  end
+  
+  it 'parses version request' do
+    @parser.parse_version(fixture('version.txt')).should == '1.4.4'
+    
+    proc { @parser.parse_version("some other response") }.
+      should raise_error Munin::InvalidResponse, "Invalid version response"
+  end
+  
+  it 'parses config request' do
+    c = @parser.parse_config(fixture('config.txt').strip.split("\n"))
+    c.should be_a Hash
+    c['graph'].should be_a Hash
+    c['graph']['args']['raw'].should == '--base 1024 -l 0 --upper-limit 16175665152'
+    c['graph']['args']['parsed'].keys.should == %w(base l upper-limit)
+    c['metrics'].should be_an Hash
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,11 @@
+$:.unshift File.expand_path("../..", __FILE__)
+
+require 'munin-ruby'
+
+def fixture_path
+  File.expand_path("../fixtures", __FILE__)
+end
+
+def fixture(file)
+  File.read(fixture_path + '/' + file)
+end

metadata

@@ -0,0 +1,81 @@
+--- !ruby/object:Gem::Specification
+name: munin-ruby
+version: !ruby/object:Gem::Version
+  version: 0.2.1
+  prerelease: 
+platform: ruby
+authors:
+- Dan Sosedoff
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2011-12-06 00:00:00.000000000Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: &2164790540 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.6'
+  type: :development
+  prerelease: false
+  version_requirements: *2164790540
+description: Munin Node client
+email: dan.sosedoff@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .rspec
+- README.md
+- Rakefile
+- lib/munin-ruby.rb
+- lib/munin-ruby/cache.rb
+- lib/munin-ruby/connection.rb
+- lib/munin-ruby/errors.rb
+- lib/munin-ruby/node.rb
+- lib/munin-ruby/parser.rb
+- lib/munin-ruby/version.rb
+- munin-ruby.gemspec
+- spec/fixtures/config.txt
+- spec/fixtures/fetch.txt
+- spec/fixtures/list.txt
+- spec/fixtures/version.txt
+- spec/node_spec.rb
+- spec/parser_spec.rb
+- spec/spec_helper.rb
+homepage: http://github.com/sosedoff/munin-ruby
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.10
+signing_key: 
+specification_version: 3
+summary: Ruby client library to communicate with munin-node servers
+test_files:
+- spec/fixtures/config.txt
+- spec/fixtures/fetch.txt
+- spec/fixtures/list.txt
+- spec/fixtures/version.txt
+- spec/node_spec.rb
+- spec/parser_spec.rb
+- spec/spec_helper.rb