Ara Howard, Delynn Berry and I, are pleased to announce the MOle plugin.

The MOle allows you to precisely analyze how your customers are interacting with your rails application. Instead of sitting on the console and watching your controller actions and db queries fly by, you can easily leverage the MOle and let it do this work for you by trapping events of interest. This plugin allows you to figure out if your latest application features are a success or a bust. You will be able to trap certain user interactions and record them for your next iterations. This is not yet another page hit or heat map type plugin, within a few steps you will be able to monitor your users interactions LIVE and assess your application usability from the comfort of your own machine...

We've produced an introduction to the MOle, you can watch the video MOle Video

Getting Started...

1. Download the plugin:
   ruby script/plugin install svn://rubyforge.org/var/svn/liquidrail/plugins/mole/trunk
   Upon install, the plugin will create 2 tables in your db namely mole_features and mole_logs
   
   
2. Set up the MOle in config/environment.rb:
   
   MOLE = File.new( "#{RAILS_ROOT}/config/mole.conf" )
   MOLEABLE_APP = true
   MOLE_PERF_MAX_TIME = 5
    
   
   All the interactions of your moled application is orchestrated via the mole.conf file. A sample mole.conf file has been dropped in the config dir during the plugin installation. You can turn the mole on/off via the MOLEABLE_APP var. A built in feature of the mole is also to record long running actions, we will cover this later but the last variable will set the default perf threshold in this case 5 seconds.
   
   
3. Load the MOle configuration:
   In your ApplicationController, add the following line:
   load MOLE.path if File.exists?(MOLE.path) and MOLEABLE_APP
   This will load the mole configuration that instruct what/how to mole your rails application. All mole interactions occur in one single file, no need to sprinkle mole code all over your controllers. In the configuration file you simply instruct the mole where and what to capture when a particular interaction occurs.
   
   
4. Moling a controller action:
   MyController.before( :feature => :show ) do |context, feature, args|
     Mole::DbMole.mole_it( context, feature, context.session[:user_id],
         :some_var => context.instance_variable_get('@myVar'))
   
   
   or
   MyController.after( :feature => :show ) do |context, feature, ret_val, args|
     Mole::DbMole.mole_it( context, feature, context.session[:user_id],
         :some_var => context.instance_variable_get('@myVar'), :return => ret_val
   
   
   
5. That's all !!




We have also bundle a couple of consoles to allow you to view the mole in action aka The Snitch and the Yahoo! Widget MOlet...

The Snitch source can be downloaded here:

svn co svn://rubyforge.org/var/svn/liquidrail/plugins/mole/samples/consoles/snitch
Once you've downloaded The Snitch you will need to run the following command to complete the installation:
rake setup
This will tell the application how to access your user model by specifying the users db table name and which column to use to display the user name. Also you will need to edit the database.yml to point to your db. No worries this app does not alter your db in any ways...

In order to run the companion widget application, you will need to install the Yahoo! Widget Engine for your platform and then download the MOlet Widget and save it to your platform specific widgets directory ( MAC Documents/widgets -- WIN Document And Setting/user/widgets)

svn co svn://rubyforge.org/var/svn/liquidrail/plugins/mole/samples/consoles/widgets/molet



You can find out more about the MOle by reading the documentation or tuning to the MOle Forum

Let us know what you think...