The MOle Plugin

The Cone Of Silence

The trend for many companies these days is to claim their entire devotion to the Agile process. We all iterate, sit or stand in SCRUM meeting often for longer than we care for and we are all sworn into delivering early and often... But how can you really measure if your application is a success or a bust? We all know that page hits and heat maps are only good in the eyes of marketeers, or some usability PHD... How do you accurately assess that the "must have" features in your application are actually being used and how are your customers actually using them ? More importantly, how can you accurately assess you are iterating down the right path for your product and company success, and not simply digging further in a rat hole ?

These very questions motivated the conception of the MOle. I was recently getting close to the delivery stage for an application. The features were abundant, the code tested and the bitchin prod machines roared. We had several bells and whistles that we all slaved long hours to implement based on our product requirements. One of the features was an nice Ajax based slider that allowed the users to filter out content based on some ranking algorithm. Then we began to wonder: 'Will customers use the slider ? If so, what settings will they use?" Sure a few thousand dollars worth of usability lab equipment and countless hours of drilling the poor souls that volunteered, would shed some light on this mystery. But who can stomach the price and time drain? So, short of babysitting, the logs and attempt to munge the one out of thousand actions scrolling by, we needed a way to intercept that particular feature and log the event, so that we could establish metrics and reporting around this valued feature. We needed a mole, an agent that would do just that in our application (i.e. intercept features and record these precious events). The MOle allowed us to gather the valuable user inputs. It provided us the necessary feedback to make the adjustments for our next iterations. As it turns out some of the features that were qualified as "must have" in our requirement documents were not being used at all. Worth noting as well, the MOle proved valuable in our test cycles to assess the coverage and efficiency of our QA team...

Getting Started

Now that we have hopefully whetted your appetite, here are the steps necessary to MOle your own application.

1. Download the plugin:

   Related Sponsored Content

   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 are 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 performance threshold in this case 5 seconds.

3. Load the MOle configuration:
   
   In your ApplicationController, add the following line:

   loadMOLE.path ifFile.(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')) 

   This intercept the show action on the MyController and before, show is called, will log the controller state namely 'myVar' to the database. So not only do you persist the mere fact that this action got called but also you will record the very essence of this call via the state used to make this particular call.

   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)) 

   Same idea but intercept the show action after it was called...

5. That's it !!

Supporting Consoles

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

The Snitch source can be downloaded here:

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 way.

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://rubyforge.org/var/svn/liquidrail/plugins/mole/samples/consoles/widgets/molet

Conclusion

Thank you all for stopping by and taking a fresh look at the MOle. Whether you have solid requirements, or think it would be easier to find a pizza at a WeightWatchers convention, we hope you will take it out for a spin. We are looking forward to hear all about your 'moling' experiences and will do our best to help you getting it working correctly for you. If you have comments and suggestions on how to help us improve the MOle by all means fire away...

Resources

• Blog Site: liquidrail
• Video: The MOle - Getting started
• Forum: MOle Forum
• Docs: Documentation

About the author

Fernand Galiana is the owner of Imhotep Software LLC a consulting and Rails training company located in Denver, Colorado. He possesses over 15 years experience in software development mainly around user interface and middle tier. He is also the author of ZiYa a rails charting plugin. He is currently hosting the Denver Rails User Group Chapter (aka DeRailed).