Ragios Plugin System

Ragios uses plugins to monitor various systems and services. A plugin could monitor URLs, http, processes, database servers etc. Plugins define the tests performed by Ragios to determine whether a monitored service is still available or offline. Plugins may also define conditions that may trigger alerts by Ragios. Using plugins Ragios could be extended to monitor any type of system.

Monitoring websites for uptime is handled by the http plugin and monitoring URLs for availability is done with the url plugin. We used both plugins and gave examples in the beginning of this document. Now lets walkthrough the simple process of creating a plugin.

Writing a Ragios plugin in 5 easy steps:

Step 1: The plugin must be saved in the lib/ragios/monitors/plugins directory.

Step 2: The plugin must be in a Module called Monitors

Module Monitors
end

Step 3: The plugin is a simple Ruby Class. (The class name should be in CamelCase.)

Module Monitors
  class Service
  end
end

Step 4: The plugin must have 2 methods init(options) and test_command()

Module Monitors
  class Service
    def init(options)
    end
 
    def test_command
     return TRUE #or return FALSE if test fails
    end
  end
end

test_command() performs a test on the service being monitored. When the test fails, test_command() returns FALSE. When the test passes test_command returns TRUE. (The most common test is checking availability of a service like DNS, http etc. test_command() should return TRUE when the service is available and FALSE when its not available).

Final Step 5: The plugin must define and assign values to 2 variables @describe_test_result and @test_result.

Module Monitors
  class Service
 
    attr_accessor :describe_test_result 
    attr_accessor :test_result
 
    def init(options)
       @describe_test_result = "Sample test on a service "   
    end
 
    def test_command
      @test_result = 'PASSED'
      return TRUE #or return FALSE if test fails
    end
  end
end

@describe_test_result should describe the expected results of the test performed by the plugin. @test_result should contain the result of the test performed by the plugin.

Our plugin is now ready to run. We use it to monitor a fictional service called ‘service’. To use the plugin from main.rb;

monitoring = [{monitor:'service',
                  every:'5m',
                  test:'sample test',
                  contact:'admin@mysite.com',
                  via:'gmail',
                  notify_interval:'6h'
                 }]
 
Ragios::Monitor.start monitoring

The code above means that Ragios will run our plugin every 5 minutes, and contact admin via gmail when the test fails etc. monitor:‘service’ tells Ragios to use the Monitors::Service plugin we created. (If we used monitor:‘http’ Ragios will use the Monitors::Http plugin which ships with the system).

The hash value in the DSL is passed to our plugin’s init(options) method as options.

options =  {monitor:'service',
                every:'5m',
                test:'sample test',
                contact:'admin@mysite.com',
                via:'gmail',
                notify_interval:'6h'
               }

If our plugin needs more values, we would make it a requirement that those values are added to the hash in the DSL. For example, lets say our plugin needs the hostname and IP address of the system running the service its monitoring. We will just make the DSL for our plugin collect that information, see example below;

monitoring = [{monitor:'service',
                  every:'5m',
                  test:'sample test',
 
                  ip:'192.168.2.19'
                  hostname:'ubuntu-server1'
 
                  contact:'admin@mysite.com',
                  via:'gmail',
                  notify_interval:'6h'
                 }]
 
Ragios::Monitor.start monitoring

Our plugin will collect the values of the IP address and hostname from the options hash. We just re-write the plugin like this. See below:

Module Monitors
  class Service
 
    attr_accessor :describe_test_result 
    attr_accessor :test_result
 
    attr_accessor :ip_address
    attr_hostname :hostname
 
    def init(options)
       @ip_address = options[:ip] 
       @hostname = options[:hostname]
 
       raise "ip must be assigned a value" if @ip_address.nil?
       raise "hostname must be assigned a value" if @hostname.nil?
 
       @describe_test_result = "Sample test on a service"  
    end
 
    def test_command
      @test_result = 'PASSED'
      return TRUE #or return FALSE if test fails
    end
  end
end

Below is the DSL syntax for the http plugin:

  monitoring = [{monitor:'http',
                 every:'5m',
                 test:'Http connection to my site',
                 domain:'www.mysite.com',
                 contact:'admin@mysite.com',
                 via:'gmail',
                 notify_interval:'6h'
                }]
 
Ragios::Monitor.start monitoring

Source code for the http plugin, notice how the init(options) and test_command() methods uses the domain value from the DSL:

module Monitors
 
# Plugin: Monitors a domain to check if its online  
# It establishes a HTTP connection to the domain
# PASSED if it establishes the HTTP connection successfully and FAILED if it throws an exception
class Http 
  attr_reader :domain 
  attr_accessor :describe_test_result 
  attr_accessor :test_result
 
  def init(options)
       @domain = options[:domain] 
       raise "domain must be assigned a value" if @domain.nil?
       @describe_test_result = "HTTP Connection to " + @domain     
  end 
 
  #connects to the domain via HTTP
  #PASSED when it establishes a successful HTTP connection with the domain
  def test_command
    begin  
         Net::HTTP.start(@domain) 
         @test_result = 'PASSED'
         return TRUE 
 
    rescue Exception
           @test_result =  $! # $! global variable reference to the Exception object
           return FALSE  
    end      
  end   
end
end

Testing your plugin

Ragios uses RSpec for testing. The specs for your plugin should cover a Passing and failing condition for the plugin. Below is an example of a plugin specs. Using the specs for the http plugin as an example:

#spec/plugins/http_plugin_spec.rb
require 'spec_base.rb'
 
options1 = { monitor: 'http',
            every: '10m',
            test: 'google site test',
            domain: 'www.google.com',
            contact: 'admin@mail.com',
            via: 'gmail',  
            notify_interval: '6h'
            }
options2 =  { monitor: 'http',
             every: '2m',
             test: 'domain doesnt exist',
             domain: 'www.ragios-ruby.com',
             contact: 'admin@mail.com',
             via: 'gmail',  
             notify_interval: '6h'
            }
 
describe Monitors::Http do
 
 it "should establish a http connection with google.com" do
   h = Monitors::Http.new
   h.init(options1) 
   h.test_command.should == TRUE
 end
 
 it "should fail to establish a http connection" do 
   f = Monitors::Http.new
   f.init(options2)
   f.test_command.should ==  FALSE
 end 
end

To run the above specs from the spec/plugins directory

rspec http_plugin_spec.rb

To run the complete test suite for Ragios (this will ensure that the Ragios system is still working fine). From the Ragios root directory type

bundle exec rake spec

Save specs for your plugins in the spec/plugins directory.

If any questions please email me: obi.akubue@gmail.com

Thanks for reading. I am updating this document as I code the project. This document is changing daily.