<commit_before>=Ragios (Saint Ruby)


While reading the book “Nagios: system and Network Monitoring” by <NAME>, I thought it will be a good idea to write a Ruby based Object Oriented System and Network Monitoring tool similar to Nagios.

So I started writing such a tool. Since it was inspired by Nagios, I will call it Ragios (Ruby Agios) aka Saint Ruby since Agios is Saint in Greek.

This is all just for fun and educational purposes.

Ragios could be used to monitor any type of system including servers, workstations, switches, routers, system services and applications, locally or over a network. The system admin can define the tests he wants to run on the system or re-use tests written by other developers. The tests run periodically on the system. When a test fails the admin receives an email or SMS alert from Ragios. Everything is written in ruby, the configuration settings are all in ruby syntax. The Ragios system itself is written in ruby.

==Requirements
Ragios v0.5.0 requires Ruby 1.9.2 or higher. 

==Installation
I assume you are using a linux/unix system (Most likely debian/Ubuntu). However, Ragios is written in ruby and runs on any platform that supports Ruby including BSD, OS X, any Linux distro, Windows etc..

Using Git:

Download Ragios 

 git clone git://github.com/obi-a/Ragios.git

Change to the Ragios directory :

   $cd Ragios

Switch to the Ragios release branch

   git checkout release

Install the bundler rubygem :

   $sudo gem install bundler

Ragios uses bundler to manage dependencies. Bundler will install the right version of all the gems required for Ragios to run on your system.

Now while inside the ragios directory, run Bundler to install all the required gems and dependencies :
   
   $sudo bundle install

Installation is complete! Ragios is ready to use. 

To update to the latest version of Ragios anytime, from the root of the Ragios directory:
  $git pull

==Usage

===To Monitor a Website 


To monitor a website for availability; enter the following in the ragios/main.rb script


    monitoring = [{monitor:'http', 
                   every:'5m',
                   test:'Http connection to my site',
                   domain:'www.mysite.com',
                   contact:'<EMAIL>',
                   via:'gmail',  
                   notify_interval:'6h'
                  }]

  Ragios::Monitor.start monitoring

This will try to establish a http connection with the domain:'www.mysite.com' every '5m' (5 minutes), when it fails to establish a connection it will send a notification to the system admin specified by contact:'<EMAIL>' via 'gmail'. if the website is still offline it will notify the admin again after 6 hours specified by notify_interval:'6h'. test: is a description of the test being performed. It helps Ragios notify the system admin with accurate details of what went wrong on the system.

To send notifications via twitter use via:'twitter' and to send notifications via sendmail installed on the system use via:'email', using via:'gmail' means the notifications will be sent via gmail.
 

==To monitor multiple sites
   
   monitoring	= {monitor:'http', 
                   every:'5m',
                   test:'Http connection to my site',
                   domain:'www.mysite.com',
                   contact:'<EMAIL>',
                   via:'gmail',  
                   notify_interval:'6h'
                  },
                   {monitor:'http', 
                    every:'30s',
                    test:'Http connection to client A website',
                    domain:'www.clientA.com',
                    contact:'<EMAIL>',
                    via:'twitter',  
                    notify_interval:'6h'
                  },
                  {monitor:'http', 
                   every:'3h',
                   test:'Http connection to client B website',
                   domain:'www.clientB.com',
                   contact:'<EMAIL>',
                   via:'twitter',  
                   notify_interval:'6h'
                  }

  Ragios::Monitor.start monitoring
  
The time interval between tests could be in seconds, minutes, hours or combined,
  every:'5m', #every 5 minutes
  every:'30s', #every 30 seconds
  every:'4h', #every 5 hours
  every:'6h30m', #every 5 minutes

Same thing applies to the values of the notify_interval, they can be in seconds, minutes, hours or combined. 


===Monitoring URLs
To monitor a URL,
     
     monitoring	=  [{ monitor:'url',
                    every:'5m',
                    test:'video datafeed test',
                    url:'http://www.datafeed.com/resources/videos/1',
                    contact:'<EMAIL>',
                    via:'gmail',  
                    notify_interval:'6h'
                    }]

    Ragios::Monitor.start monitoring

This will send a Http GET request to the specified url 'http://www.datafeed.com/resources/videos/1' every 5 minutes, it will  notify the contact '<EMAIL>' via gmail if it gets an ERROR response code from the url. Every 6 hours it will re-send a notification message to contact if the issue has not been fixed. When the issue is fixed it will send an issue resolved message to the contact.

You can monitor a combination of websites and URLs,

    monitoring	={monitor:'url',
                    every:'5m',
                    test:'video datafeed test',
                    url:'http://www.datafeed.com/resources/videos/1',
                    contact:'<EMAIL>',
                    via:'gmail',  
                    notify_interval:'6h'
                    },
                 {monitor:'http', 
                   every:'30s',
                   test:'Http connection to client A website',
                   domain:'www.clientA.com',
                   contact:'<EMAIL>',
                   via:'twitter',  
                   notify_interval:'6h'
                   },
                 {monitor:'url',
                   every:'5m',
                   test:'My blog URL test',
                   url:'http://www.myblog.com',
                   contact:'<EMAIL>',
                   via:'email',  
                   notify_interval:'6h'
                  }
                
   Ragios::Monitor.start monitoring

    
Ragios also notifies the system admin when an issue is resolved example when a website comes back online.

===main.rb 

The Ragios configuration settings should in the Ragios/main.rb script. A sample copy of the script looks like this:

  require 'rubygems'
  require "bundler/setup"
  dir = Pathname(__FILE__).dirname.expand_path
  require dir + 'lib/ragios'
  require dir + 'config'
    
  #Add your code here
     monitoring = { monitor:'http',
                    every:'2m',
                    test:'Http connection to my blog',
                    domain:'obi-akubue.org',
                    contact:'<EMAIL>',
                    via:'gmail',  
                    notify_interval:'6h'
                  } ,
                  { monitor:'url',
                    every:'2m',
                    test:'My Website Test',
                    url:'http://www.whisperservers.com/blog/',
                    contact:'<EMAIL>',
                    via:'gmail',  
                    notify_interval:'6h'
                  }

     Ragios::Monitor.start monitoring

     #trap Ctrl-C to exit gracefully
     puts "PRESS CTRL-C to QUIT"
      loop do
       trap("INT") { puts "\nExiting"; exit; }
      sleep(3)
     end

Since main.rb is pure ruby code we can run it directly, from the Ragios/ directory : 

 $ruby main.rb

This will run the ragios system on our terminal as a top program. This can be useful for debugging purposes, to test our configuration script for errors.

Output from running the above main.rb script will look like this :

	Welcome to Ragios
	Initializing
	3 Monitors detected

	test 1. Http connection to my blog
	Scheduled to run every 2m
	Running First Test...
	  [PASSED] Created on: February 06, 2011 20:18
	HTTP Connection to obi-akubue.org = PASSED

	test 2. My Website Test
	Scheduled to run every 2m
	Running First Test...
	  [PASSED] Created on: February 06, 2011 20:18
	HTTP Request to http://www.whisperservers.com/blog/ = 200

	PRESS CTRL-C to QUIT

We can also run Ragios as a daemon by running the ragiosd ruby script also in the Ragios/ directory. 

===Starting the Ragios System
Ragios runs as a daemon in unix/linux systems. 

To Start Ragios as a daemon from the terminal :

	$ruby ragiosd start

Stop the daemon :

	$ruby ragiosd stop

Restart the daemon :

	$ruby ragiosd restart

Check Status of the daemon :

	$ruby ragiosd status

To run Ragios as a top program, useful for testing purposes :

	$ruby ragiosd run

The ragiosd script simply demonizes the Ragios/main.rb script and runs it as a daemon. The logs and output of the daemon is saved in the Ragios/log directory as ragios.log and ragios.output respectively.

Run Ragios as 'sudo' when you need it to restart processes i.e.
 
  sudo ruby ragiosd start

===Notifications
When a test fails the system sends out a notification to the system admin about the problem.

===Sending Notifications via Sendmail
To send out notifications via sendmail use via:'email', example

    monitoring	=  [{ monitor:'url',
                      every:'5m',
                      test:'video datafeed test',
                      url:'http://www.datafeed.com/resources/videos/1',
                      contact:'<EMAIL>',
                      via:'email',  
                      notify_interval:'6h'
                  }]

You just need to have sendmail installed in your system, Ragios will use it to send the notification.


===Sending Notifications via Gmail
To send out notifications via gmail, first create a Gmail account for the Ragios system. The email notifications will be sent out from this Gmail account.

Edit the script Ragios/config.rb, add the username & password of the Gmail account you created. See below;

  gmail_account = {username:'Gmail Username', #replace with gmail username
                   password:'<PASSWORD>'}  #replace with gmail password

Example

  gmail_account = {username:'Ragios', 
                   password:'<PASSWORD>'}  


Now on the main.rb script use via:'gmail', see example below


    monitoring	= [{ monitor:'url',
                      every:'5m',
                      test:'video datafeed test',
                      url:'http://www.datafeed.com/resources/videos/1',
                      contact:'<EMAIL>',
                      via:'gmail',  
                      notify_interval:'6h'
                    }]

===Sending Notifications via Twitter
First you need to create and register a twitter app at http://twitter.com/apps/new. Ragios will use this app to tweet the notifications. After you register the App, Twitter will give you a consumer_key and a consumer_secret. We will use them later.

Next you need to create a new twitter account for the Ragios system. This is the Twitter account that will tweet the notifications. To receive the tweets the system admin should follow this account on twitter. The account should be set to private on twitter.

After you create the account, you need to grant your registered twitter app access to it.

To do this you need the oauth rubygem

 sudo gem install oauth

This ruby script below will do the trick, copy and run the script in your system: 

  #twitter_auth.rb
  #!/usr/bin/ruby
  require 'rubygems'
  require 'oauth'
 
  consumer = OAuth::Consumer.new(
    'consumer key',
    'consumer secret',
    {:site => 'http://twitter.com'}
  )
 
  request_token = consumer.get_request_token
 
  puts "Twitter App Authorize URL \n" + request_token.authorize_url
  puts "Enter PIN:"
  pin = STDIN.readline.chomp
 
  access_token = request_token.get_access_token(:oauth_verifier => pin)
 
  puts "access token: " + access_token.token
  puts "access secret: " + access_token.secret


Use the ‘consumer_key’ and ‘consumer secret’ Twitter generated for your app earlier. Add it to these lines in the script: 

	consumer = OAuth::Consumer.new(
    	    'consumer key',
    	    'consumer secret',
        {:site => 'http://twitter.com'}
       )

When you run the script it will display an authorization URL, this is the url that you will use to ALLOW or DENY your twitter app access to the Twitter account you created for Ragios. Open the authorization URL in a web browser, choose ALLOW to grant access to your twitter app. Twitter will give you a PIN number, enter that PIN number on the prompt displayed by the ruby script. 
After this, the script will display your access_token and access_secret. The access_token and access_secret is all Ragios needs to gain read and write access to the twitter account.

Now open the config.rb script located in Ragios/ directory. Add the real values for the access_token, access_secret, consumer key and consumer secret. Replace the string in quotes.

  twitter_cred = {consumer_key: 'Consumer Key', 
                 consumer_secret: 'Consumer secret',
                 access_token: 'Access Token',
                 access_secret: 'Access Secret'}
          

Now on the main.rb script use via:'twitter' example


     monitoring = [{monitor:'url',
                     every:'5m',
                     test:'video datafeed test',
                     url:'http://www.datafeed.com/resources/videos/1',
                     contact:'<EMAIL>',
                     via:'twitter',  
                     notify_interval:'6h'
                    }]

Example of an email notification may look like this: 

 Subject: Http connection to my blog FAILED
 
 Http connection to my blog FAILED! HTTP Connection to obi-akubue.org = getaddrinfo: Name or service not known
 Created on: September 22, 2010 13:55


A tweet notification may look like this:

 Http connection to my blog FAILED! HTTP Request to http://obi-akubue.org/ = getaddrinfo: Name or service not known 
 Created on: October 16, 04:48

The notifications messages are generated from ERB templates stored in the Ragios/lib/ragios/messages folder. You can edit the templates to change the format or layout of the notification messages. 
 
===Status Report
Ragios can be configured to regularly send you a Status Report on all the active monitors running in the system.
This Status Report includes:
* The number of monitors running on the system
* How long the monitors have been running 
Also includes a summary of each active monitor  
* how many times the monitor has been tested
* how many tests it passed
* how many tests failed
* results of the last test
* date/time the last test was performed etc.

To configure Ragios to send Status Reports
  Ragios::Monitor.update_status({every:'1d',
			         contact:'<EMAIL>',
			         via:'gmail'}) 

The above sample means that Ragios will send a Status Report every day '1d' to the email address '<EMAIL>' via gmail. 
Ragios can send Status Reports every (n) minutes, hours, days, weeks or combined. 

Example
   every:'40m' #every 40 minutes
   every:'2d'  #every 2 days
   every:'6h'  #every 6 hours
   every:'1w'  #every week
   every:'4w'  #every 4 weeks
   every:'1w2d' #every week and 2 days i.e every 9 days


The Status Report can be sent via gmail or sendmail, 
   via:gmail # sends the report via gmail
   via:email # sends the report via sendmail installed on the system

Example with 2 monitors:
      monitoring = {monitor:'url',
                    every:'5m',
                    test:'video datafeed test',
                    url:'http://www.datafeed.com/resources/videos/1',
                    contact:'<EMAIL>',
                    via:'gmail',  
                    notify_interval:'6h'
                  },
                  { monitor:'http', 
                    every:'30s',
                    test:'Http connection to client A website',
                    domain:'www.clientA.com',
                    contact:'<EMAIL>',
                    via:'twitter',  
                    notify_interval:'6h'
                  }
                
  Ragios::Monitor.start monitoring  
  
  Ragios::Monitor.update_status({ every:'5d',
			          contact:'<EMAIL>',
			          via:'gmail'}) 

This above example will send a Status Report to the email '<EMAIL>' every 5 days via gmail. 

===Editing the Status Report

The Status report is generated from the ERB Template file Ragios/lib/ragios/messages/status_report.erb. You can edit this template to add or remove attributes of the monitors you want to see in the report. You can also format the layout or text of the report from this template.
  

===Editing the Notification Messages
All notifcation messages are generated from ERB template files in the Ragios/lib/ragios/messages folder. You can edit any of the ERB template files to change the format of messages sent by the system. The ERB templates have access to all attributes of the monitor, so you can easily edit the template to add or remove attributes you would like to see on messages.

Below is a list of ERB templates used by the system:
 lib/ragios/messages/email_notify.erb    -- template for all email notification messages 
 lib/ragios/messages/tweet_notify.erb    -- template for all notifications sent by a tweet
 lib/ragios/messages/email_resolved.erb  -- template for all issue resolved email messages sent to the admin
 lib/ragios/messages/tweet_resolved.erb  -- template for all issue resolved messages sent via twitter
 lib/ragios/messages/status_report.erb   -- template for the Status Reports sent out to the admin by the system

== Adding Failure Recovery Code to your monitors
You can add failure recovery code to your monitors, when a monitored system fails the failure recovery code will be excuted by Ragios. 

You can add 2 types of failure recovery code.
* Code to be excuted when a monitored system fails.
* Code to be excuted when a monitored system recovers from failure. 

When a server is being monitored for availability, failure recovery code could be used to switch to a backup server when the main server goes down, and then switch back to the main server when it recovers. This also applies to any type of system being monitored databases, websites, datafeeds, API etc. 

Lets say you want your web app to switch to a backup datafeed when your main datafeed goes offline.

  run_when_failed = lambda{ 
                            puts 'switch to backup datafeed'
                            puts 'do something'
                           }
 
  run_on_fixed = lambda{
                         puts 'switch to main datafeed'
                         puts 'do something'
                       }

  monitoring = [{ monitor: 'url',
                   every: '2m',
                   test: 'XYZ data feed',
                   url: 'http://www.website.com/89843/videos.xml',
                   contact: '<EMAIL>',
                   via: 'gmail',  
                   notify_interval: '6h',

                   failed: run_when_failed, 
                   fixed: run_on_fixed  

                    }]

 Ragios::Monitor.start monitoring

failed: points to a code block that will be excuted when the monitored system goes down while fixed: points to a code block that will be excuted when the monitored system recovers from failure.
When the above monitored url fails the code block run_when_failed will be excuted and when it recovers from failure the code block run_when_fixed will be executed.<commit_msg>minor correction<commit_after>=Ragios (Saint Ruby)


While reading the book “Nagios: system and Network Monitoring” by <NAME>, I thought it will be a good idea to write a Ruby based Object Oriented System and Network Monitoring tool similar to Nagios.

So I started writing such a tool. Since it was inspired by Nagios, I will call it Ragios (Ruby Agios) aka Saint Ruby since Agios is Saint in Greek.

This is all just for fun and educational purposes.

Ragios could be used to monitor any type of system including servers, workstations, switches, routers, system services and applications, locally or over a network. The system admin can define the tests he wants to run on the system or re-use tests written by other developers. The tests run periodically on the system. When a test fails the admin receives an email or SMS alert from Ragios. Everything is written in ruby, the configuration settings are all in ruby syntax. The Ragios system itself is written in ruby.

==Requirements
Ragios v0.5.0 requires Ruby 1.9.2 or higher. 

==Installation
I assume you are using a linux/unix system (Most likely debian/Ubuntu). However, Ragios is written in ruby and runs on any platform that supports Ruby including BSD, OS X, any Linux distro, Windows etc..

Using Git:

Download Ragios 

 git clone git://github.com/obi-a/Ragios.git

Change to the Ragios directory :

   $cd Ragios

Switch to the Ragios release branch

   git checkout release

Install the bundler rubygem :

   $sudo gem install bundler

Ragios uses bundler to manage dependencies. Bundler will install the right version of all the gems required for Ragios to run on your system.

Now while inside the ragios directory, run Bundler to install all the required gems and dependencies :
   
   $sudo bundle install

Installation is complete! Ragios is ready to use. 

To update to the latest version of Ragios anytime, from the root of the Ragios directory:
  $git pull

==Usage

===To Monitor a Website 


To monitor a website for availability; enter the following in the ragios/main.rb script


    monitoring = [{monitor:'http', 
                   every:'5m',
                   test:'Http connection to my site',
                   domain:'www.mysite.com',
                   contact:'<EMAIL>',
                   via:'gmail',  
                   notify_interval:'6h'
                  }]

  Ragios::Monitor.start monitoring

This will try to establish a http connection with the domain:'www.mysite.com' every '5m' (5 minutes), when it fails to establish a connection it will send a notification to the system admin specified by contact:'<EMAIL>' via 'gmail'. if the website is still offline it will notify the admin again after 6 hours specified by notify_interval:'6h'. test: is a description of the test being performed. It helps Ragios notify the system admin with accurate details of what went wrong on the system.

To send notifications via twitter use via:'twitter' and to send notifications via sendmail installed on the system use via:'email', using via:'gmail' means the notifications will be sent via gmail.
 

==To monitor multiple sites
   
   monitoring	= {monitor:'http', 
                   every:'5m',
                   test:'Http connection to my site',
                   domain:'www.mysite.com',
                   contact:'<EMAIL>',
                   via:'gmail',  
                   notify_interval:'6h'
                  },
                   {monitor:'http', 
                    every:'30s',
                    test:'Http connection to client A website',
                    domain:'www.clientA.com',
                    contact:'<EMAIL>',
                    via:'twitter',  
                    notify_interval:'6h'
                  },
                  {monitor:'http', 
                   every:'3h',
                   test:'Http connection to client B website',
                   domain:'www.clientB.com',
                   contact:'<EMAIL>',
                   via:'twitter',  
                   notify_interval:'6h'
                  }

  Ragios::Monitor.start monitoring
  
The time interval between tests could be in seconds, minutes, hours or combined,
  every:'5m', #every 5 minutes
  every:'30s', #every 30 seconds
  every:'4h', #every 5 hours
  every:'6h30m', #every 5 minutes

Same thing applies to the values of the notify_interval, they can be in seconds, minutes, hours or combined. 


===Monitoring URLs
To monitor a URL,
     
     monitoring	=  [{ monitor:'url',
                    every:'5m',
                    test:'video datafeed test',
                    url:'http://www.datafeed.com/resources/videos/1',
                    contact:'<EMAIL>',
                    via:'gmail',  
                    notify_interval:'6h'
                    }]

    Ragios::Monitor.start monitoring

This will send a Http GET request to the specified url 'http://www.datafeed.com/resources/videos/1' every 5 minutes, it will  notify the contact '<EMAIL>' via gmail if it gets an ERROR response code from the url. Every 6 hours it will re-send a notification message to contact if the issue has not been fixed. When the issue is fixed it will send an issue resolved message to the contact.

You can monitor a combination of websites and URLs,

    monitoring	={monitor:'url',
                    every:'5m',
                    test:'video datafeed test',
                    url:'http://www.datafeed.com/resources/videos/1',
                    contact:'<EMAIL>',
                    via:'gmail',  
                    notify_interval:'6h'
                    },
                 {monitor:'http', 
                   every:'30s',
                   test:'Http connection to client A website',
                   domain:'www.clientA.com',
                   contact:'<EMAIL>',
                   via:'twitter',  
                   notify_interval:'6h'
                   },
                 {monitor:'url',
                   every:'5m',
                   test:'My blog URL test',
                   url:'http://www.myblog.com',
                   contact:'<EMAIL>',
                   via:'email',  
                   notify_interval:'6h'
                  }
                
   Ragios::Monitor.start monitoring

    
Ragios also notifies the system admin when an issue is resolved example when a website comes back online.

===main.rb 

The Ragios configuration settings should in the Ragios/main.rb script. A sample copy of the script looks like this:

  require 'rubygems'
  require "bundler/setup"
  dir = Pathname(__FILE__).dirname.expand_path
  require dir + 'lib/ragios'
  require dir + 'config'
    
  #Add your code here
     monitoring = { monitor:'http',
                    every:'2m',
                    test:'Http connection to my blog',
                    domain:'obi-akubue.org',
                    contact:'<EMAIL>',
                    via:'gmail',  
                    notify_interval:'6h'
                  } ,
                  { monitor:'url',
                    every:'2m',
                    test:'My Website Test',
                    url:'http://www.whisperservers.com/blog/',
                    contact:'<EMAIL>',
                    via:'gmail',  
                    notify_interval:'6h'
                  }

     Ragios::Monitor.start monitoring

     #trap Ctrl-C to exit gracefully
     puts "PRESS CTRL-C to QUIT"
      loop do
       trap("INT") { puts "\nExiting"; exit; }
      sleep(3)
     end

Since main.rb is pure ruby code we can run it directly, from the Ragios/ directory : 

 $ruby main.rb

This will run the ragios system on our terminal as a top program. This can be useful for debugging purposes, to test our configuration script for errors.

Output from running the above main.rb script will look like this :

	Welcome to Ragios
	Initializing
	3 Monitors detected

	test 1. Http connection to my blog
	Scheduled to run every 2m
	Running First Test...
	  [PASSED] Created on: February 06, 2011 20:18
	HTTP Connection to obi-akubue.org = PASSED

	test 2. My Website Test
	Scheduled to run every 2m
	Running First Test...
	  [PASSED] Created on: February 06, 2011 20:18
	HTTP Request to http://www.whisperservers.com/blog/ = 200

	PRESS CTRL-C to QUIT

We can also run Ragios as a daemon by running the ragiosd ruby script also in the Ragios/ directory. 

===Starting the Ragios System
Ragios runs as a daemon in unix/linux systems. 

To Start Ragios as a daemon from the terminal :

	$ruby ragiosd start

Stop the daemon :

	$ruby ragiosd stop

Restart the daemon :

	$ruby ragiosd restart

Check Status of the daemon :

	$ruby ragiosd status

To run Ragios as a top program, useful for testing purposes :

	$ruby ragiosd run

The ragiosd script simply demonizes the Ragios/main.rb script and runs it as a daemon. The logs and output of the daemon is saved in the Ragios/log directory as ragios.log and ragios.output respectively.

Run Ragios as 'sudo' when you need it to restart processes i.e.
 
  sudo ruby ragiosd start

===Notifications
When a test fails the system sends out a notification to the system admin about the problem.

===Sending Notifications via Sendmail
To send out notifications via sendmail use via:'email', example

    monitoring	=  [{ monitor:'url',
                      every:'5m',
                      test:'video datafeed test',
                      url:'http://www.datafeed.com/resources/videos/1',
                      contact:'<EMAIL>',
                      via:'email',  
                      notify_interval:'6h'
                  }]

You just need to have sendmail installed in your system, Ragios will use it to send the notification.


===Sending Notifications via Gmail
To send out notifications via gmail, first create a Gmail account for the Ragios system. The email notifications will be sent out from this Gmail account.

Edit the script Ragios/config.rb, add the username & password of the Gmail account you created. See below;

  gmail_account = {username:'Gmail Username', #replace with gmail username
                   password:'<PASSWORD>'}  #replace with gmail password

Example

  gmail_account = {username:'Ragios', 
                   password:'<PASSWORD>'}  


Now on the main.rb script use via:'gmail', see example below


    monitoring	= [{ monitor:'url',
                      every:'5m',
                      test:'video datafeed test',
                      url:'http://www.datafeed.com/resources/videos/1',
                      contact:'<EMAIL>',
                      via:'gmail',  
                      notify_interval:'6h'
                    }]

===Sending Notifications via Twitter
First you need to create and register a twitter app at http://twitter.com/apps/new. Ragios will use this app to tweet the notifications. After you register the App, Twitter will give you a consumer_key and a consumer_secret. We will use them later.

Next you need to create a new twitter account for the Ragios system. This is the Twitter account that will tweet the notifications. To receive the tweets the system admin should follow this account on twitter. The account should be set to private on twitter.

After you create the account, you need to grant your registered twitter app access to it.

To do this you need the oauth rubygem

 sudo gem install oauth

This ruby script below will do the trick, copy and run the script in your system: 

  #twitter_auth.rb
  #!/usr/bin/ruby
  require 'rubygems'
  require 'oauth'
 
  consumer = OAuth::Consumer.new(
    'consumer key',
    'consumer secret',
    {:site => 'http://twitter.com'}
  )
 
  request_token = consumer.get_request_token
 
  puts "Twitter App Authorize URL \n" + request_token.authorize_url
  puts "Enter PIN:"
  pin = STDIN.readline.chomp
 
  access_token = request_token.get_access_token(:oauth_verifier => pin)
 
  puts "access token: " + access_token.token
  puts "access secret: " + access_token.secret


Use the ‘consumer_key’ and ‘consumer secret’ Twitter generated for your app earlier. Add it to these lines in the script: 

	consumer = OAuth::Consumer.new(
    	    'consumer key',
    	    'consumer secret',
        {:site => 'http://twitter.com'}
       )

When you run the script it will display an authorization URL, this is the url that you will use to ALLOW or DENY your twitter app access to the Twitter account you created for Ragios. Open the authorization URL in a web browser, choose ALLOW to grant access to your twitter app. Twitter will give you a PIN number, enter that PIN number on the prompt displayed by the ruby script. 
After this, the script will display your access_token and access_secret. The access_token and access_secret is all Ragios needs to gain read and write access to the twitter account.

Now open the config.rb script located in Ragios/ directory. Add the real values for the access_token, access_secret, consumer key and consumer secret. Replace the string in quotes.

  twitter_cred = {consumer_key: 'Consumer Key', 
                 consumer_secret: 'Consumer secret',
                 access_token: 'Access Token',
                 access_secret: 'Access Secret'}
          

Now on the main.rb script use via:'twitter' example


     monitoring = [{monitor:'url',
                     every:'5m',
                     test:'video datafeed test',
                     url:'http://www.datafeed.com/resources/videos/1',
                     contact:'<EMAIL>',
                     via:'twitter',  
                     notify_interval:'6h'
                    }]

Example of an email notification may look like this: 

 Subject: Http connection to my blog FAILED
 
 Http connection to my blog FAILED! HTTP Connection to obi-akubue.org = getaddrinfo: Name or service not known
 Created on: September 22, 2010 13:55


A tweet notification may look like this:

 Http connection to my blog FAILED! HTTP Request to http://obi-akubue.org/ = getaddrinfo: Name or service not known 
 Created on: October 16, 04:48

The notifications messages are generated from ERB templates stored in the Ragios/lib/ragios/messages folder. You can edit the templates to change the format or layout of the notification messages. 
 
===Status Report
Ragios can be configured to regularly send you a Status Report on all the active monitors running in the system.
This Status Report includes:
* The number of monitors running on the system
* How long the monitors have been running 
Also includes a summary of each active monitor  
* how many times the monitor has been tested
* how many tests it passed
* how many tests failed
* results of the last test
* date/time the last test was performed etc.

To configure Ragios to send Status Reports
  Ragios::Monitor.update_status({every:'1d',
			         contact:'<EMAIL>',
			         via:'gmail'}) 

The above sample means that Ragios will send a Status Report every day '1d' to the email address '<EMAIL>' via gmail. 
Ragios can send Status Reports every (n) minutes, hours, days, weeks or combined. 

Example
   every:'40m' #every 40 minutes
   every:'2d'  #every 2 days
   every:'6h'  #every 6 hours
   every:'1w'  #every week
   every:'4w'  #every 4 weeks
   every:'1w2d' #every week and 2 days i.e every 9 days


The Status Report can be sent via gmail or sendmail, 
   via:gmail # sends the report via gmail
   via:email # sends the report via sendmail installed on the system

Example with 2 monitors:
      monitoring = {monitor:'url',
                    every:'5m',
                    test:'video datafeed test',
                    url:'http://www.datafeed.com/resources/videos/1',
                    contact:'<EMAIL>',
                    via:'gmail',  
                    notify_interval:'6h'
                  },
                  { monitor:'http', 
                    every:'30s',
                    test:'Http connection to client A website',
                    domain:'www.clientA.com',
                    contact:'<EMAIL>',
                    via:'twitter',  
                    notify_interval:'6h'
                  }
                
  Ragios::Monitor.start monitoring  
  
  Ragios::Monitor.update_status({ every:'5d',
			          contact:'<EMAIL>',
			          via:'gmail'}) 

This above example will send a Status Report to the email '<EMAIL>' every 5 days via gmail. 

===Editing the Status Report

The Status report is generated from the ERB Template file Ragios/lib/ragios/messages/status_report.erb. You can edit this template to add or remove attributes of the monitors you want to see in the report. You can also format the layout or text of the report from this template.
  

===Editing the Notification Messages
All notifcation messages are generated from ERB template files in the Ragios/lib/ragios/messages folder. You can edit any of the ERB template files to change the format of messages sent by the system. The ERB templates have access to all attributes of the monitor, so you can easily edit the template to add or remove attributes you would like to see on messages.

Below is a list of ERB templates used by the system:
 lib/ragios/messages/email_notify.erb    -- template for all email notification messages 
 lib/ragios/messages/tweet_notify.erb    -- template for all notifications sent by a tweet
 lib/ragios/messages/email_resolved.erb  -- template for all issue resolved email messages sent to the admin
 lib/ragios/messages/tweet_resolved.erb  -- template for all issue resolved messages sent via twitter
 lib/ragios/messages/status_report.erb   -- template for the Status Reports sent out to the admin by the system

== Adding Failure Recovery Code to your monitors
You can add failure recovery code to your monitors, when a monitored system fails the failure recovery code will be excuted by Ragios. 

You can add 2 types of failure recovery code.
* Code to be excuted when a monitored system fails.
* Code to be excuted when a monitored system recovers from failure. 

When a server is being monitored for availability, failure recovery code could be used to switch to a backup server when the main server goes down, and then switch back to the main server when it recovers. This also applies to any type of system being monitored databases, websites, datafeeds, API etc. 

Lets say you want your web app to switch to a backup datafeed when your main datafeed goes offline.

  run_when_failed = lambda{ 
                            puts 'switch to backup datafeed'
                            puts 'do something'
                           }
 
  run_when_fixed = lambda{
                         puts 'switch to main datafeed'
                         puts 'do something'
                       }

  monitoring = [{ monitor: 'url',
                   every: '2m',
                   test: 'XYZ data feed',
                   url: 'http://www.website.com/89843/videos.xml',
                   contact: '<EMAIL>',
                   via: 'gmail',  
                   notify_interval: '6h',

                   failed: run_when_failed, 
                   fixed: run_when_fixed  

                    }]

 Ragios::Monitor.start monitoring

failed: points to a code block that will be excuted when the monitored system goes down while fixed: points to a code block that will be excuted when the monitored system recovers from failure.
When the above monitored url fails the code block run_when_failed will be excuted and when it recovers from failure the code block run_when_fixed will be executed.
{'fraction_non_alphanumeric': 0.06926384633210599, 'fraction_numerical': 0.007055127842006334, 'mean_word_length': 2.305924412665986, 'pattern_counts': {'":': 0, '<': 53, '<?xml version=': 0, '>': 59, 'https://': 0, 'lorem ipsum': 0, 'www.': 36, 'xml': 2}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7074279', 'n_tokens_mistral': 10500, 'n_tokens_neox': 9572, 'n_words': 4458}