naplug 1.6.1 → 1.7.1

data/README.md

@@ -1,4 +1,4 @@
-# Naplug
+# Naplug [![Gem Version](https://badge.fury.io/rb/naplug.png)](http://badge.fury.io/rb/naplug)
 
 *Naplug* is a [Nagios plugin](http://nagiosplug.sourceforge.net/developer-guidelines.html) library for Ruby focused on plugin internals: organization, status, performance data, output and exit code handling. It does not implement any functionality related to option and argument parsing, as there are fine tools already available for this purpose. It aims to ease the task of writing Nagios plugins in Ruby and _handling the paperwork_, allowing the plugin developer to concentrate on the test logic of the plugin. Its internal design is largely modeled after the very excellent [Worlkflow](https://github.com/geekq/workflow) library.
 
@@ -246,6 +246,33 @@ Which produces:
     naplug@plugin:~: examples/exception+
     OK: divided by zero is infinity
 
+### Performance Data
+
+Naplug supports plugin performance data, which is only available after a plugin has been `exec`ed. Within plugins, two methods are relevant: `perfdata!` and `perfdata`, which set and get performance data metrics, respectively:
+
+    class PerfDataPlugin
+
+      include Naplug
+
+      plugin :p do |p|
+        p.status.ok!
+        p.output! "#{p.tag}:#{p[:instance]} with argument metric #{p[:metric]}"
+        p.perfdata! :metric, p[:metric]
+        p.perfdata! '"_met ric!', 30, :max => 70
+      end
+
+    end
+
+    pd = PerfDataPlugin.new :instance => :x1, :p => { :metric => 10 }
+    pd.exec!
+
+This yields:
+
+    naplug@plugin:~: perfdata_uniplug 
+    OK: p:x1 with argument metric 10 | metric=10;;;; '"_met ric!'=30;;;;70
+    
+It is also possible to access performance data from within the user-defined plugin class through the `perfdata` method, which returns an array of [`PerformanceData`](http://rubydoc.info/gems/naplug/Naplug/PerformanceData) objects.
+
 ### Plugs: Plugins within Plugins 
 
 Up until now, *Naplug* has essentially provided *syntactic sugar* to define and use what amounts to single-purpose plugins, along with some convenience methods to represent status and produce output. But plugins sometimes need to perform a number of possibly independent tasks to reach a final, _aggregated_ status.
@@ -318,6 +345,71 @@ Tagged arguments have priority over shared ones.
                             :plug1 => { :file => '/var/tmp/file', :critical => 120 },
                             :plug2 => { :ok => 0, :warning => 5, :critical => 10 })
                             
+#### Performance Data
+
+As mentioned earlier, Naplug supports plugin performance data, through two methods of `Plugin`, `perfdata!` and `perfdata`:
+
+    class PerfDataPlugPlugin
+
+      include Naplug
+
+      plugin :p do |p|
+
+        plugin :p1 do |p1|
+          p1.status.ok!
+          p1.output! "#{p.tag}:#{p1.tag} #{p[:instance]}"
+          p1.perfdata! :metric, p1[:metric], :max => 70
+          p1.perfdata! '"_met ric!', 30, :max => 70
+        end
+
+        plugin :p2 do |p2|
+          p2.status.ok!
+          p2.output! "#{p.tag}:#{p2.tag} #{p[:instance]}"
+          p2.perfdata! 'p2/metric', p2[:metric], :crit => 70
+        end
+
+        plugin :p3 do |p3|
+          p3.status.ok!
+         p3.output! "#{p.tag}:#{p3.tag} #{p[:instance]}"
+        end
+      end
+    end
+
+    # Note: the following code is meant to show some of the behavior related to Performance Data:
+    plugin = PerfDataPlugPlugin.new :instance => :x1, :p1 => { :metric => 10 }, :p2 => { :metric => 50 }
+    plugin.exec
+    
+    # Plugin Perfdata Ancestors
+	plugin.perfdata.each do |pd|
+	  puts "#{pd.tag} has #{pd.to_a.size} labels and its tree is #{pd.ancestors :mode => :tags}"
+	end
+
+	plugin.perfdata.each do |pd|
+      puts "plugin #{pd.tag} has #{pd.labels}"
+	end
+	
+which produces:
+
+    plugin@naplug:~: perfdata_multiplug
+    perfdata p1 has 2 labels and its tree is p/p1
+    perfdata p2 has 1 labels and its tree is p/p2
+    plugin p1 has ["metric", "'\"_met ric!'"]
+    plugin p2 has ["p2/metric"]
+
+Some of this functionality is intended to ease integration with, for instance, Graphite:
+
+    g = Graphite.new :hostname => 'graphite', :port => 2013
+    h = `hostname`.gsub(/\./,'_')
+    
+    plugin.perfdata.each do |pd|
+      pd.to_a.each do |l|
+        g.push "#{h}_app_#{l}
+      end
+    end
+    g.flush!
+
+This would push the collected performance data metrics to Graphite with an invented API. Note that Nagios performance data labels are not always legal graphite metric names (`"\"_met ric!'` above). Naplug makes no attempt to address this.
+                                                            
 #### A Plugged Plugin Example
 
 Take a service for which we wish to monitor three conditions:
@@ -457,7 +549,7 @@ A future release will allow the execution order to be changed through an `order!
     
 If tags are omitted from the list, the missing plugs are pushed to the end of the line in the last order set.
 
-#### Enabling and Disabling Plugs
+### Enabling and Disabling Plugs
 
 Currently, when plugs are defined, they are assumed to be enabled and will be executed when `exec!` is invoked. There may be cases when it may be desirable or necessary to disable specific plugins, which will be accomplished through the `disable!` instance method. A disabled plug can be re-enabled via the `enable!` plugin method:
 

data/examples/multiplugins

@@ -38,7 +38,6 @@ class MultiPluginPlugin
 
 end
 
-
 x1 = MultiPluginPlugin.new :instance => :x1, :one => { :p1 => { :instance => :x1 }}
 x2 = MultiPluginPlugin.new :instance => :x2, :one => { :p1 => { :instance => :x2 }}
 x1.one!

data/examples/perfdata_multiplug

@@ -0,0 +1,48 @@
+#!/usr/bin/env ruby -rubygems
+
+lib = File.expand_path(File.dirname(__FILE__) + '/../lib')
+$LOAD_PATH.unshift(lib) if File.directory?(lib) && !$LOAD_PATH.include?(lib)
+
+require 'naplug'
+require 'awesome_print'
+
+class PerfDataPlugPlugin
+
+  include Naplug
+
+  plugin :p do |p|
+
+    plugin :p1 do |p1|
+      p1.status.ok!
+      p1.output! "#{p.tag}:#{p1.tag} #{p[:instance]}"
+      p1.perfdata! :metric, p1[:metric], :max => 70
+      p1.perfdata! '"_met ric!', 30, :max => 70
+    end
+
+    plugin :p2 do |p2|
+      p2.status.ok!
+      p2.output! "#{p.tag}:#{p2.tag} #{p[:instance]}"
+      p2.perfdata! 'p2/metric', p2[:metric], :crit => 70
+    end
+
+    plugin :p3 do |p3|
+      p3.status.ok!
+      p3.output! "#{p.tag}:#{p3.tag} #{p[:instance]}"
+    end
+
+  end
+
+end
+
+plugin = PerfDataPlugPlugin.new :instance => :x1, :p1 => { :metric => 10 }, :p2 => { :metric => 50 }
+plugin.exec
+
+# Plugin Perfdata Ancestors
+plugin.perfdata.each do |pd|
+    puts "perfdata #{pd.tag} has #{pd.to_a.size} labels and its tree is #{pd.ancestors :mode => :tags}"
+end
+
+plugin.perfdata.each do |pd|
+    puts "plugin #{pd.tag} has labels #{pd.labels}"
+end
+

data/examples/perfdata_uniplug

@@ -0,0 +1,24 @@
+#!/usr/bin/env ruby
+
+lib = File.expand_path(File.dirname(__FILE__) + '/../lib')
+$LOAD_PATH.unshift(lib) if File.directory?(lib) && !$LOAD_PATH.include?(lib)
+
+require 'rubygems'
+require 'naplug'
+#require 'awesome_print'
+
+class PerfDataPlugin
+
+  include Naplug
+
+  plugin :p do |p|
+    p.status.ok!
+    p.output! "#{p.tag}:#{p[:instance]} with argument metric #{p[:metric]}"
+    p.perfdata! :metric, p[:metric]
+    p.perfdata! '"_met ric!', 30, :max => 70
+  end
+
+end
+
+pd = PerfDataPlugin.new :instance => :x1, :p => { :metric => 10 }
+pd.exec!

data/examples/status

@@ -19,7 +19,7 @@ module Naplug
     puts "Working with a status:"
     status = Naplug::Status.new
     puts "  status #{status} has exit code #{status.to_i} after initialization"
-    status.ok
+    status.ok!
     puts "  status #{status} has exit code #{status.to_i} after status.ok"
 
     puts "Comparing statuses:"

data/lib/naplug.rb

@@ -1,3 +1,17 @@
+#--
+#
+# Author:: Gerir Lopez-Fernandez
+# Homepage::  https://github.com/gerirgaudi/naplug/
+# Date:: 25 Feb 2014
+#
+# See the file LICENSE for licensing information.
+#
+#---------------------------------------------------------------------------
+
+#--
+# Naplug::ClassMethods and Naplug::InstanceMethods
+
+
 require 'rubygems'
 require 'naplug/plugin'
 
@@ -7,31 +21,43 @@ module Naplug
 
   module ClassMethods
 
+    # @!scope class
+
+    # @!attribute [r] plugins
+    #   @return [Hash<Symbol, Plugin>] metaplugins
     attr_reader :plugins
 
+    # Create a metaplugin (which basically contains a tag and a block)
+    # @param tag [Symbol] the plugin tag
+    # @return [Plugin] a metaplugin
     def plugin(tag = :main, &block)
       @plugins = Hash.new unless @plugins
       @plugins[tag] = create_metaplugin tag, block
     end
 
+    # A list of plugin tags
+    # @return [Array<Symbol>] the list of plugin tags
     def tags
       self.plugins.keys
     end
 
     private
 
+    # Create a metaplugin (helper)
     def create_metaplugin(tag,block)
       module_eval do
-        define_method "#{tag}".to_sym  do; plugin;         end    # <tag> methods for quick access to plugins
+        define_method "#{tag}".to_sym  do; @plugins[tag];  end    # <tag> methods for quick access to plugins
         define_method "#{tag}!".to_sym do; self.exec! tag; end    # <tag>! methods to involke exec! on a given plugin
       end
-      Plugin.new tag, :meta, block
+      Plugin.new tag, block, :meta => true, :parent => self
     end
 
   end
 
   module InstanceMethods
 
+    # @!scope instancce
+
     attr_reader :plugins
 
     def initialize(args = {})
@@ -42,10 +68,14 @@ module Naplug
       args! args
     end
 
+    # Returns the arguments of the plugin
+    # @return [Hash] a hash by argument key of argument values
     def args
       @_args
     end
 
+    # Sets and propagates plugin arguments
+    # @param [Hash <Symbol, Object>] args
     def args!(args)
       @_args.merge! args
       @plugins.each do |tag,plugin|
@@ -56,25 +86,45 @@ module Naplug
     end
 
     def to_str(tag = default_plugin.tag)
-      s_format = perfdata(tag) ? '%s: %s | %s' : '%s: %s'
-      s_array = perfdata(tag) ? [@plugins[tag].status,@plugins[tag].output,perfdata(tag)] : [@plugins[tag].status,@plugins[tag].output]
+      pd = perfdata(tag)
+      if pd.empty?
+        s_format = '%s: %s'
+        s_array = [@plugins[tag].status,@plugins[tag].output]
+      else
+        s_format = '%s: %s | %s'
+        s_array = [@plugins[tag].status,@plugins[tag].output,pd.join(' ').strip]
+      end
       s_format % s_array
     end
 
+    # Execute, evaluate and exit the plugin according to the plugin status, outputting the plugin's text output (and performance data, if applicable)
+    # @param tag [Symbol] a plugin tag
     def exec!(tag = default_plugin.tag)
       exec tag
       eval tag
       exit tag
     end
 
-    def exec(tag = default_plugin.tag)
-      rexec @plugins[tag]
+    # Execute the plugin
+    # @param tag [Symbol] a plugin tag
+    def exec(t = default_plugin.tag)
+      plugin = target_plugin t
+      if plugin.has_plugins?
+        plugin.plugins.each_value { |p| exec p }
+      else
+        plexec plugin
+      end
     end
 
     def eval(tag = default_plugin.tag)
       @plugins[tag].eval
     end
 
+    def eval!(tag = default_plugin.tag)
+      @plugins[tag].eval
+      exit tag
+    end
+
     def eject!(payload = nil)
       o = case payload
             when String then payload
@@ -86,24 +136,27 @@ module Naplug
       Kernel::exit 3
     end
 
-    private
-
-    def rexec(plug)
-      if plug.has_plugins?
-        plug.plugins.each_value { |p| rexec p }
+    # @return [Array<PerformanceData>] a list of performance data objects
+    def perfdata(tag = default_plugin.tag)
+      plugin = @plugins[tag]
+      if plugin.has_plugins?
+        plugin.plugins.values.select { |plug| plug.perfdata }.map { |plug| plug.perfdata }
       else
-        plexec plug
+        plugin.perfdata ? [plugin.perfdata] : []
       end
     end
 
+    private
+
     def plexec(p)
       begin
         @_running = p.tag
         instance_exec p, &p.block
         @_running = nil
       rescue Naplug::Error => e
-          p.status.unknown!
-          p.output! "#{e.backtrace[1][/[^\/]+:\d+/]}: #{e.message}"
+        p.status.unknown!
+        p.output! "#{e.backtrace[1][/[^\/]+:\d+/]}: #{e.message}"
+        p.payload! e
       rescue => e
         p.status.unknown!
         p.output!  "#{e.backtrace[0][/[^\/]+:\d+/]}: #{e.message}"
@@ -125,12 +178,11 @@ module Naplug
       raise Naplug::Error, 'unable to determine default plugin'
     end
 
-    def perfdata(tag = default_plugin.tag)
-      plugin = @plugins[tag]
-      if plugin.has_plugins?
-        plugin.plugins.values.map { |plug| plug.perfdata }.join(' ').gsub(/^\s+$/,'').strip!
-      else
-        plugin.perfdata
+    def target_plugin(target)
+      case target
+        when Symbol then @plugins[target]
+        when Plugin then target
+        else raise Naplug::Error, "unable to determine target plugin"
       end
     end
 

data/lib/naplug/helpers.rb

@@ -1,4 +1,6 @@
 require 'json'
+require 'socket'
+require 'timeout'
 require 'naplug/status'
 
 module Naplug
@@ -47,6 +49,65 @@ module Naplug
         }
       end
 
+    end
+
+    module ENGraphite
+
+      class Client
+
+        attr_reader :metrics
+
+        def initialize(options)
+          raise ArgumentError, 'missing graphite server address' if options[:graphite].nil?
+          @graphite = options[:graphite]
+          @port = options[:port].nil? ? 2003 : options[:port].to_i
+          @prefix = options[:prefix].nil? ? '' : options[:prefix]
+          @metrics = []
+        end
+
+        def metric path, value, time = Time.now
+          @metrics.push(Metric.new(path,value,time))
+        end
+
+        def metrics!
+          @metrics.each do |metric|
+            metric = "#{@prefix}.#{metric.to_s}\n"
+            print metric
+          end
+        end
+
+        def flush!(options = { :timeout => 3})
+          begin
+            Timeout.timeout(options[:timeout]) do
+              s = TCPSocket.open(@graphite,@port)
+              @metrics.each do |metric|
+                metric = "#{@prefix}.#{metric.to_s}\n"
+                s.write metric
+              end
+              s.close
+            end
+          rescue Timeout::Error => e
+            raise Naplug::Error, "graphite timeout (#{options[:timeout]}s)"
+          rescue Errno::ECONNREFUSED, SocketError => e
+            raise Naplug::Error, 'graphite socket error'
+          end
+        end
+      end
+
+      class Metric
+
+        attr_reader :path, :value, :time
+
+        def initialize(path,value,time = Time.now)
+          @path = path
+          @value = value
+          @time = time
+        end
+
+        def to_s
+          '%s %d %d' % [@path,@value,@time.to_i]
+        end
+      end
 
     end
 

data/lib/naplug/performancedata.rb

@@ -1,52 +1,111 @@
+require 'ostruct'
+
 module Naplug
 
   class PerformanceData
 
-    attr_reader :tag, :data
+    include Enumerable
 
-    class MissingLabel < StandardError; end
-    class InvalidField < StandardError; end
-    class ThatIsNoHash < StandardError; end
+    attr_reader :tag, :data, :meta
 
-    FIELDS = [:label, :value, :uom, :warn, :crit, :min, :max] # label=value[UOM];[warn];[crit];[min];[max]
+    FIELDS = [:label, :value, :uom, :warn, :crit, :min, :max]
 
-    def initialize(tag)
-      @tag = tag
+    def initialize(plugin)
+      @tag = plugin.tag
       @data = Hash.new
+      @meta = OpenStruct.new :plugin => plugin, :ancestors => traverse_to_root(plugin)
     end
 
-    def to_s(label = nil)
-      label_ary = label.nil? ? @data.keys : [label]
+    # performance data format: 'label=value[UOM];[warn];[crit];[min];[max]'
+    def to_str(label = nil)
+      label_ary = label.nil? ? labels : [curate_label(label)]
       label_ary.map do |l|
         '%s=%s%s;%s;%s;%s;%s' % FIELDS.map { |k| @data[l][k] }
       end.join(' ').strip
     end
 
-    def []=(label,value,args = {})
-      raise ThatIsNoHash, 'hash of fields is not a hash' unless args.is_a? Hash
-      args.keys.each { |field| raise InvalidField unless FIELDS.include? field }
-      raise MissingLabel, 'missing label' unless label
-      @data[label] = { :label => label, :value => value }.merge args
+    # List of performance data label entries
+    # @return [Array<Hash<label,field_data>>] an array of hashes keyed by field
+    def to_a
+      @data.values
+    end
+
+    # @raise Naplug::Error if the label contains invalid characters, the value is not a number, or specify invalid fields
+    def []=(label,valuefields)
+      value, fields = valuefields
+      if validate_label label and validate_value value and validate_fields fields
+        @data[curate_label(label)] = { :label => curate_label(label), :value => value }.merge fields
+      else
+        raise Naplug::Error, "invalid performance data label (#{label}), value (#{value}), field representation (#{fields.class}) or field (#{fields.keys.join(',')})"
+      end
+    end
+
+    def each(&block)
+      @data.values.each(&block)
     end
-    alias_method :store, :[]=
 
     def [](label)
-      @data[label]
+      @data[curate_label(label)]
     end
-    alias_method :fetch, :[]
 
     def delete(label)
-      @data.delete(label)
+      @data.delete(curate_label(label))
     end
 
-    def has_label?(label)
-      @data.has_key? label
+    def include?(label)
+      @data.has_key? curate_label(label)
     end
-    alias_method :include?, :has_label?
+    alias_method :has_label?, :include?
+
+    def keys
+      @data.keys
+    end
+    alias_method :labels, :keys
 
     def fields
       FIELDS
     end
 
+    # @return [Plugin] plugin performance data belongs to
+    def plugin
+      @meta.plugin
+    end
+
+    # @return [Array<Plugin>] of parent plugins
+    def ancestors(options = { :mode => :tags, :separator => :/ })
+      options[:separator] = :/ if options[:separator].nil?
+      options[:mode].nil? ? @meta.ancestors : @meta.ancestors.map { |a| a.tag }.join(options[:separator].to_s)
+    end
+
+    private
+
+    # can contain any characters except the equals sign or single quote (')
+    def validate_label(l)
+      l.nil? or l.to_s.index(/['=]/) ? false : true
+    end
+
+    def validate_value(v)
+      true #      v =~ /^[0-9.-]+$/ ? true : false
+    end
+
+    def validate_fields(fields)
+      fields.is_a? Hash and fields.keys.select { |field| not FIELDS.include? field }.empty? ? true : false
+    end
+
+    # single quotes for the label are optional; required if spaces are in the label
+    def curate_label(l)
+      l.to_s.index(/\s+/) ? "'#{l}'" : l.to_s
+    end
+
+    def traverse_to_root(plugin)
+      lineage = []
+      loop do
+        break unless plugin.is_a? Plugin
+        lineage.push plugin
+        plugin = plugin.parent
+      end
+      lineage.reverse
+    end
+
   end
 end

data/lib/naplug/plugin.rb

@@ -8,27 +8,26 @@ module Naplug
 
   class Plugin
 
-    attr_reader :block, :plugins, :tag
+    attr_reader :block, :plugins, :tag, :meta
 
     class DuplicatePlugin < StandardError; end
 
-    def initialize(tag, meta = false, block)
+    DEFAULT_META = { :debug => false, :enabled => true }
+
+    def initialize(tag, block, meta = {})
       @tag = tag
       @block = block
       @plugins = Hash.new
 
       @_args = Hash.new
       @_data = OpenStruct.new :status => Status.new, :output => Output.new, :payload => nil, :perfdata => nil
-      @_meta = OpenStruct.new :status => meta, :enabled => true, :debug => true
+      @_meta = OpenStruct.new DEFAULT_META.merge meta
 
       begin; instance_eval &block ; rescue => e; nil ; end
 
     end
 
-    # @param format [Symbol] the format type, `:text` or `:html`
-    # @return [True, False<String>, nil] the object or objects to
-    #   find in the database. Can be nil.@return [String] the object converted into the expected format.
-    # # true if this plugin is a metaplugin, false otherwise
+    # @return [True, False] true if this plugin is a metaplugin, false otherwise
     def is_meta?
       @_meta.status
     end
@@ -53,6 +52,10 @@ module Naplug
       not @_meta.enabled
     end
 
+    def parent
+      @_meta.parent
+    end
+
     # true when a plugin contains plugs
     def has_plugins?
       @plugins.empty? ? false : true
@@ -91,8 +94,8 @@ module Naplug
     end
 
     def perfdata!(label,value,f = {})
-      @_data.perfdata ||= PerformanceData.new @tag
-      @_data.perfdata.store label, value, f
+      @_data.perfdata ||= PerformanceData.new self
+      @_data.perfdata[label] = value, f
     end
 
     def payload
@@ -124,7 +127,7 @@ module Naplug
       @_args[k] = v
     end
 
-    def to_s
+    def to_str
       '%s: %s' % [status,output]
     end
 
@@ -141,7 +144,7 @@ module Naplug
 
     def plugin(tag, &block)
       raise DuplicatePlugin, "duplicate definition of #{tag}" if @plugins.key? tag
-      @plugins[tag] = Plugin.new tag, block
+      @plugins[tag] = Plugin.new tag, block, :parent => self
       self.define_singleton_method tag do
         @plugins[tag]
       end

data/lib/naplug/version.rb

@@ -1,3 +1,3 @@
 module Naplug
-  VERSION = '1.6.1'
-end
+  VERSION = '1.7.1'
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: naplug
 version: !ruby/object:Gem::Version
-  version: 1.6.1
+  version: 1.7.1
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-02-24 00:00:00.000000000 Z
+date: 2014-02-26 00:00:00.000000000 Z
 dependencies: []
 description: ! 'A Ruby library for Nagios plugins '
 email: gerir@evernote.com
@@ -26,8 +26,6 @@ files:
 - lib/naplug/version.rb
 - lib/naplug.rb
 - examples/almostalwaysok
-- examples/alwaysok
-- examples/alwaysunknown
 - examples/dupplugin
 - examples/exception
 - examples/exception+
@@ -36,7 +34,11 @@ files:
 - examples/multiplug
 - examples/multiplugin
 - examples/multiplugins
+- examples/o_alwaysok
+- examples/perfdata_multiplug
+- examples/perfdata_uniplug
 - examples/status
+- examples/u_alwaysunknown
 - LICENSE
 - README.md
 homepage: https://github.com/gerirgaudi/naplug
@@ -65,3 +67,4 @@ signing_key:
 specification_version: 3
 summary: A Ruby library for Nagios plugins
 test_files: []
+has_rdoc: