nagi 0.1.1 → 0.2.0

data/NEWS

@@ -0,0 +1,10 @@
+0.2.0: 2012-05-31
+- Added support for collecting multiple statuses during check
+
+0.1.1: 2012-05-30
+- Made Utility::execute() work with Ruby 1.8
+- Properly escape quotes in Utility::execute()
+- Fixed syntax errors in README example
+
+0.1.0: 2012-05-18
+- Initial release

data/README.md

@@ -9,11 +9,50 @@ GNU GPL v3.
 
 ## Example
 
-A typical plugin looks like this:
+A very simple plugin looks like this:
 
 ```ruby
 #!/usr/bin/env ruby
+require 'nagi'
+
+Nagi do
+  name 'check_true'
+  version '0.1'
+  prefix 'TRUE'
+
+  check do |args|
+    if true
+      ok 'True is still true'
+    else
+      critical 'Uh oh'
+    end
+  end
+end
+```
+
+The first few methods just set some basic info for the plugin - the name,
+version, and a prefix for the check output. These are all optional.
+
+Next, the check block is defined, which runs the actual Nagios check. `args`
+will contains any options (see command-line parsing below), and the methods ok,
+warning, critical, and unknown are used to return the check status. A missing
+status or uncaught exception will result in an 'unknown' status.
 
+The plugin is run as any regular script - save it as a file, make it executable
+and run it:
+
+```
+$ ./test.rb 
+TRUE OK: True is still true
+```
+
+### Command-line options
+
+Nagi can automatically parse command-line arguments when requested, and provide
+them as input to the check block. Here is a simple example:
+
+```ruby
+#!/usr/bin/env ruby
 require 'nagi'
 require 'resolv'
 
@@ -40,23 +79,99 @@ Nagi do
 end
 ```
 
-Here we first set up some basic info like name and version, and specify a few
-command-line options. Then we write a block of code containing the actual
-check, which is given the parsed command-line options as a hash, and returns a
-status via methods like `ok` and `critical`.
+The `argument` method specifies a required positional argument, and only takes
+the name of the argument. `switch` specifies an optional switch, which may or
+may not take an argument of its own. The first `switch` parameter is its name,
+while the rest are passed to the standard Ruby OptionParser.on method - see its
+documentation for details.
+
+The parsed arguments are passed to the `check` block via the `args` parameter,
+which is a hash containing argument names and values. In the case of a switch
+with no argument of its own, the value will be `true`.
+
+A few usage examples of this plugin:
+
+```
+$ ./check_dns.rb 
+Error: Argument 'hostname' not given
+
+Usage: ./check_dns.rb [options] <hostname>
+    -i, --ip IP                      Expected IP address
+    -h, --help                       Display this help message
+    -V, --version                    Display version information
+
+$ ./check_dns.rb www.google.com
+DNS OK: www.google.com resolves to 173.194.35.148
+
+$ ./check_dns.rb -i 1.2.3.4 www.google.com
+DNS CRITICAL: www.google.com resolves to 173.194.35.148, expected 1.2.3.4
+```
+
+Nagi will automatically set up the -h/--help and -V/--version switches and
+handle them appropriately.
+
+### Handling multiple statuses
+
+In some cases it is useful to collect several statuses and return the most
+severe, rather than returning the first status encountered. This is typically
+used when monitoring multiple resources with a single check.
+
+The `collect` setting tells Nagi to continue running the check when a status
+is given. It can be set to either `:severe`, in which case the most severe
+status will be returned at the end, or `:all` which will use the most severe
+status code but also combine all status messages into one.
+
+This example checks used space on all disk drives, and returns critical if
+any of the drives are above a threshold:
+
+```ruby
+#!/usr/bin/env ruby
+require 'nagi'
+
+Nagi do
+  name 'check_df'
+  version '0.1'
+  prefix 'DF'
+  argument :percentage
+  collect :all
+
+  check do |args|
+    execute('df').lines.each do |line|
+      if line =~ /^.*?(\d+)%\s*(.*)$/
+        if $1.to_i > args[:percentage].to_i
+          critical "#{$2} #{$1}% used"
+        else
+          ok "#{$2} #{$1}% used"
+        end
+      end
+    end
+  end
+end
+```
+
+When run, it will output something like this:
+
+```
+$ ./check_df.rb 90
+DF OK: / 80% used, /Volumes/Media 57% used
 
-To run the plugin, type `./check_dns.rb --ip 127.0.0.1 localhost`, or try
-`./check_dns.rb --help` for more info.
+$ ./check_df.rb 70
+DF CRITICAL: / 80% used, /Volumes/Media 57% used
+```
 
 ## Reference
 
-### Metadata
+### Plugin info
 
 These describe the program, and are usually given first, if necessary.
 
 * `name` *name*: the program name.
 * `version` *version*: the program version.
 * `prefix` *prefix*: a prefix for the check output.
+* `collect` *type*: collect statuses and continue the check, rather than
+  returning. *type* can be either `:severe` or `:all` - `:severe` will
+  return the last, most severe status, and `:all` will use the most severe
+  status but join all the status messages together into one.
 
 ### Command-line arguments
 
@@ -77,6 +192,9 @@ parsed command-line arguments as a hash. It should use one of the methods `ok`,
 `warning`, `critical`, or `unknown` to return a status. If no status is given,
 or the block raises an unhandled exception, an Unknown status will be returned.
 
+The `collect` setting (see above) can be used to collect statuses and continue
+the check, rather than returning the first status encountered.
+
 * `check` *block*: the code block the the check. Parsed command-line arguments
   are passed as a hash.
 * `ok` *message*: returns an OK status.

data/lib/nagi/dsl.rb

@@ -4,6 +4,8 @@ module Nagi
 
     def initialize(&block)
       @plugin = Nagi::Plugin.new
+      @collect = nil
+      @collected = []
       instance_eval &block
     end
 
@@ -12,14 +14,36 @@ module Nagi
     end
 
     def check(&block)
+      # make data available to block
+      collect = @collect
+      collected = @collected
+
       p = class << @plugin; self; end
       p.send(:define_method, :check) do |options|
-        return catch(:status) { block.call(options) }
+        status = catch(:status) {
+          block.call(options)
+          nil # to avoid returning status if not thrown
+        }
+        return status if status or not collect
+        return nil if collected.empty?
+        return collected.reverse.max if collect == :severe
+        return collected.reverse.max.class.new(
+          collected.map { |s| s.message }.join(', ')
+        ) if collect == :all
+        return nil
       end
     end
 
+    def collect(type)
+      raise "Invalid collect type #{type.to_s}" unless [:all, :severe].include?(type)
+      @collect = type
+    end
+
     def critical(message)
-      throw :status, Nagi::Status::Critical.new(message)
+      status = Nagi::Status::Critical.new(message)
+      throw :status, status unless @collect
+      @collected.push(status)
+      return status
     end
 
     def execute(command)
@@ -31,7 +55,10 @@ module Nagi
     end
 
     def ok(message)
-      throw :status, Nagi::Status::OK.new(message)
+      status = Nagi::Status::OK.new(message)
+      throw :status, status unless @collect
+      @collected.push(status)
+      return status
     end
 
     def prefix(prefix)
@@ -43,7 +70,10 @@ module Nagi
     end
 
     def unknown(message)
-      throw :status, Nagi::Status::Unknown.new(message)
+      status = Nagi::Status::Unknown.new(message)
+      throw :status, status unless @collect
+      @collected.push(status)
+      return status
     end
 
     def version(version)
@@ -51,7 +81,10 @@ module Nagi
     end
 
     def warning(message)
-      throw :status, Nagi::Status::Warning.new(message)
+      status = Nagi::Status::Warning.new(message)
+      throw :status, status unless @collect
+      @collected.push(status)
+      return status
     end
   end
 end

data/lib/nagi/status.rb

@@ -1,9 +1,21 @@
 module Nagi
   module Status
     class Status
+      include Comparable
       attr_accessor :message
       attr_reader :code, :name
 
+      def <=>(other)
+        if not other.is_a? Nagi::Status::Status
+          raise ArgumentError.new("comparison of Nagi::Status::Status with #{other.class} failed.")
+        end
+
+        # Make Unknown the least severe status
+        c = @code >= 3 ? -1 : @code
+        o = other.code >= 3 ? -1 : other.code
+        return c <=> o
+      end
+
       def initialize(code, name, message)
         @code = code
         @name = name

data/lib/nagi/version.rb

@@ -1,3 +1,3 @@
 module Nagi
-  VERSION = '0.1.1'
+  VERSION = '0.2.0'
 end

data/spec/nagi/dsl_spec.rb

@@ -38,6 +38,58 @@ describe Nagi::DSL do
       end
       @dsl.plugin.check({}).should eq 'status'
     end
+
+    it 'catches throwns :status and returns payload, even when collect is set' do
+      @dsl.collect(:all)
+      @dsl.check do |options|
+        throw :status, 'status'
+      end
+      @dsl.plugin.check({}).should eq 'status'
+    end
+
+    it 'returns first, most severe status for collect :severe' do
+      @dsl.collect(:severe)
+      @dsl.check do |o|
+        @dsl.warning 'w1'
+        @dsl.critical 'c1'
+        @dsl.ok 'o1'
+        @dsl.critical 'c2'
+        @dsl.ok 'o2'
+      end
+
+      status = @dsl.plugin.check({})
+      status.class.should eq Nagi::Status::Critical
+      status.message.should eq 'c2'
+    end
+
+    it 'returns most severe status with all messages joined for collect :all' do
+      @dsl.collect(:all)
+      @dsl.check do |o|
+        @dsl.warning 'w1'
+        @dsl.critical 'c1'
+        @dsl.ok 'o1'
+        @dsl.critical 'c2'
+        @dsl.ok 'o2'
+      end
+
+      status = @dsl.plugin.check({})
+      status.class.should eq Nagi::Status::Critical
+      status.message.should eq 'w1, c1, o1, c2, o2'
+    end
+  end
+
+  describe '.collect' do
+    it 'accepts :all' do
+      @dsl.collect(:all)
+    end
+
+    it 'accepts :severe' do
+      @dsl.collect(:severe)
+    end
+
+    it 'raises exception on other value' do
+      lambda { @dsl.collect(:dummy) }.should raise_error
+    end
   end
 
   describe '.critical' do
@@ -46,6 +98,11 @@ describe Nagi::DSL do
         @dsl.critical('message')
       end.class.should eq Nagi::Status::Critical
     end
+
+    it 'returns status if collection is enabled' do
+      @dsl.collect(:all)
+      @dsl.critical('message').class.should eq Nagi::Status::Critical
+    end
   end
 
   describe '.execute' do
@@ -67,6 +124,11 @@ describe Nagi::DSL do
         @dsl.ok('message')
       end.class.should eq Nagi::Status::OK
     end
+
+    it 'returns status if collection is enabled' do
+      @dsl.collect(:all)
+      @dsl.ok('message').class.should eq Nagi::Status::OK
+    end
   end
 
   describe '.prefix' do
@@ -90,6 +152,11 @@ describe Nagi::DSL do
         @dsl.unknown('message')
       end.class.should eq Nagi::Status::Unknown
     end
+
+    it 'returns status if collection is enabled' do
+      @dsl.collect(:all)
+      @dsl.unknown('message').class.should eq Nagi::Status::Unknown
+    end
   end
 
   describe '.version' do
@@ -105,5 +172,10 @@ describe Nagi::DSL do
         @dsl.warning('message')
       end.class.should eq Nagi::Status::Warning
     end
+
+    it 'returns status if collection is enabled' do
+      @dsl.collect(:all)
+      @dsl.warning('message').class.should eq Nagi::Status::Warning
+    end
   end
 end

data/spec/nagi/status_spec.rb

@@ -5,6 +5,22 @@ describe Nagi::Status::Status do
     @status = Nagi::Status::Status.new(0, 'name', 'message')
   end
 
+  describe '<=>' do
+    it 'compares status code' do
+      (@status <=> Nagi::Status::Status.new(1, 'n', 'm')).should eq -1
+      (@status <=> Nagi::Status::Status.new(0, 'n', 'm')).should eq 0
+      (@status <=> Nagi::Status::Status.new(-1, 'n', 'm')).should eq 1
+    end
+
+    it 'compares Unknown (3) as less severe than Ok (0)' do
+      (@status <=> Nagi::Status::Status.new(3, 'n', 'm')).should eq 1
+    end
+
+    it 'raises ArgumentError if compared with non-Status object' do
+      lambda { @status <=> 1 }.should raise_error ArgumentError
+    end
+  end
+
   describe '.code' do
     it 'contains status code' do
       @status.code.should eq 0

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: nagi
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-05-30 00:00:00.000000000 Z
+date: 2012-05-31 00:00:00.000000000Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
-  requirement: &70354822658820 !ruby/object:Gem::Requirement
+  requirement: &70342039915540 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70354822658820
+  version_requirements: *70342039915540
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &70354822658200 !ruby/object:Gem::Requirement
+  requirement: &70342039911220 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,7 +32,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70354822658200
+  version_requirements: *70342039911220
 description: A DSL for writing Nagios plugins
 email:
 - erik@bengler.no
@@ -42,6 +42,7 @@ extra_rdoc_files: []
 files:
 - .gitignore
 - Gemfile
+- NEWS
 - README.md
 - Rakefile
 - lib/nagi.rb
@@ -78,7 +79,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.11
+rubygems_version: 1.8.10
 signing_key: 
 specification_version: 3
 summary: A DSL for writing Nagios plugins