watcher

→ ‘watcher’

What

• Exception handling without the boiler-plate code.
• Multiple tiers of verbosity.
• Flexible logging capabilities, including to files, STDERR, email.
• Nested, and hierarchical log output for descriptive stack-frame level
  understanding where an exception was thrown.
• Ability to change the time format of your logs by supplying an arbitrary
  Proc to return the time in the format of your choice.
• Ability to customize the layout of the logs, by turning off hierarchical
  view, or changing Strings used to indicate events.
• Email log files automatically, based on number of errors or warnings.
• Ability to invoke arbitrary sequence of events if exception is thrown,
  including invocation of Proc objects.

Installing

sudo gem install watcher

The basics

A simple example demonstrating multiple embedded levels, and how the
inside block simply logs the error so that the second puts statement still executes.

# create Watcher instance with defaults
$watcher = Watcher.create

$watcher.verbose("doing something dangerous") do
  puts "be careful..."
  $watcher.debug("going to do something very dangerous", :failure => :warn) do
    raise "ouch!"
  end
  puts "that wasn't so bad... just a log entry!"
end

h2. Demonstration of usage

A more complicated example of sending a reference to a Proc to attempt
to recover from an condition.

# create Watcher instance with slightly modified defaults
$watcher = Watcher.create(:output => log_file)

$watcher.debug("starting #{File.basename($0)}") do
  # Look for CONFIG_PATH.  If not found, log warning then re-write it
  params = {:tries => 2, :failure => :error,
            :proc => lambda { |e| write_config(config_path) }}
  msg = "ensuring existance of config file [#{config_path}]"
  $watcher.verbose(msg, params) do
    raise "file not found" unless File.file?(File.expand_path(config_path))
  end

  # invoke utility, which uses $watcher as well
  fsc = FileSystemChecker.new(:config_path => config_path)
  fsc.check_file_systems(:all => all_flag, :remount => remount_flag)
end

if email_flag and ($watcher.errors > 0 or $watcher.warnings > 0)
  $watcher.send_email(email, 'FAIL: Required filesystems are not mounted')
end

Forum

http://groups.google.com/group/watcher

TODO – create Google Group – watcher

How to submit patches

Read the 8 steps for fixing other people’s code and for section 8b: Submit patch to Google Groups, use the Google Group above.

TODO – pick SVN or Git instructions

The trunk repository is svn://rubyforge.org/var/svn/watcher/trunk for anonymous access.

OOOORRRR

You can fetch the source from either:

• rubyforge: MISSING IN ACTION

TODO – You can not created a RubyForge project, OR have not run rubyforge config
yet to refresh your local rubyforge data with this projects’ id information.

When you do this, this message will magically disappear!

Or you can hack website/index.txt and make it all go away!!

• github: http://github.com/GITHUB_USERNAME/watcher/tree/master

git clone git://github.com/GITHUB_USERNAME/watcher.git

TODO – add “github_username: username” to ~/.rubyforge/user-config.yml and newgem will reuse it for future projects.

• gitorious: git://gitorious.org/watcher/mainline.git

git clone git://gitorious.org/watcher/mainline.git

Build and test instructions

Sorry, no unit tests yet…

cd watcher
rake install_gem

License

This code is free to use under the terms of the Simplified BSD license.

Contact

Comments are welcome. Send an email to Karrick McDermott via the forum

Karrick McDermott, 30th July 2008
Theme extended from Paul Battley