| Path: | README |
| Last Update: | Wed Jun 13 08:26:51 MDT 2007 |
Contributors:
Fernand Galiana (fernand.galiana@gmail.com) - Conception and Initial implementation Ara Howard - Initial implementation Delynn Berry ( delynn@gmail.com) - Conception and implementation
This plugin allows you to track user interaction with your rails application and surfaces how your customers are using your web application.
Whether you are releasing a new application or improving on an old one, it is always a good thing to know if anyone is using your application and if they are, how they are using it. What features are your users most fond of and which features find their way into the abyss ? Using the mole you will be able to rapidly assess whether or not your application is a hit and if your coolest features are thought as such by your users. You will be able to elegantly record user interactions and leverage these findings for the next iteration of your application. You can also use the mole to assess your application performance. The mole will trap actions that are taking longer than a given threshold to execute. The mole can also be instructed to capture uncaught exceptions that may or may not surface to your users.
For more information about the mole, you can tune in to the following media:
Blog Site : http://liquidrail.com Video : http://www.youtube.com/watch?v=L7JGB7QsAt8 Documentation : http://liquidrail.com/mole Forum : http://groups.google.com/group/mole-plugin
As an example we’ve Moled The Beast:
svn co svn://rubyforge.org/var/svn/liquidrail/plugins/mole/samples/beast
04/07/07 -- 0.001 - Initial drop...
04/15/07 -- 0.002 - Bug fixes, Docs cleanup, Clean up tests.
06/04/07 -- 0.003 - Added ability to specify different moleable applications sharing the same database.
- NOTE: This release will require a schema migration and update. We are introducing
two new column of the mole_features table namely context and app_name.
If you need to reuse the same db across multiple applications, then you will need
to add the following line to your application.rb. This will namespace
moleable features for each applications
Moleable::init( :app_name => "SomeAppName" )
- You will no longer need to declare all the const var in your enviromment.rb file. All
these will now be defaulted. See the enviroment section.
- The mole will now track for you which IP address your users are coming on as well as
the browser type they are using. Both the IP and browser type will be displayed on the
Snitch application.
- Speaking of the Snitch, if you are using multiple moleable applications across a single
database, you will be able to pass in the app_name=SomeAppName on the request parameter
to track a particular moled application. By default this parameter will be set to "Default".
In you rails application directory issue the following command:
ruby script/plugin install svn://rubyforge.org/var/svn/liquidrail/plugins/mole/trunk
In your application.rb insert the following directive, to allow your application to be moled: Moleable::init The init method can take a hash of the following parameters to override the default behavior - :app_name the name of the moled application. The default is 'Default' - :moleable specifies weither to enable the MOle. The default is true - :perf_max_time specified the treshold in seconds for the feature to be moled if the requested feature takes more than x secs to respond
You specify what methods to mole in your application by defining the config/mole.conf file.
For example: To mole the show action on the TopicsController class:
TopicsController.after(:feature => :show) do |context, feature, ret_val, *args|
forum = context.instance_variable_get("@forum")
Mole::DbMole.mole_it( context, feature, context.session[:user_id], :forum => forum.name )
end
After the action is called you want to record the selected forum and topic. The Mole::DbMole helper will persist the information you want to trap (in this case the selected forum). The mole records its information using two tables ie mole_features and mole_logs These tables are automatically setup for you during the plugin installation. When a controller action is ‘moled’, you have access to the controller state via the context parameter that is instance vars, params, session vars, etc… as well as the actual arguments that were passed into the call. This allows you to accurately record the actual user interaction.
If you dislike the block syntax you can also delegate to a mole class as follows:
TopicsController.after( :feature => :show, :interceptor => "MyMole", :method => "mole_it" )
Then in the MyMole class you would define the following method:
def mole_it( context, feature, ret_val, *args ) ... end
This feature pertains to controllers only. Note: We are using the action_methods call on the controller that returns all public methods on the controller. So make sure to either hide and make private actions you do not wish to mole for performance.
Adding the following line to the mole.conf file will check for perf on an entire controller.
# Mole long running actions on ForumsController
ForumsController.perf do |context, action, elapsed_time, args|
Mole::DbMole.perf_it( context, context.session[:user_id],
:controller => context.class.name,
:action => action,
:elapsed_time => "%3.3f" % elapsed_time )
end
Long running actions are accessed via the MOLE_PERF_MAX_TIME env var. If the action takes longer than this threshold to return, the action will be moled as a long running action.
The mole also allows you to trap uncaught exceptions in your application. You can either log the moled actions or set up for an email notification. This feature also only applied to controllers.
To trap uncaught exceptions on a controller enter the following lines in your mole.conf file:
# Mole exceptions on ForumsController
ForumsController.unchecked do |context, action, boom, args|
Mole::DbMole.check_it( context, context.session[:user_id],
:controller => context.class.name,
:action => action,
:boom => boom )
end
So now that your application is moled. You can either use the provided ‘Snitch’ application or the Yahoo Widget ‘Molet’. These sample applications will allow you to view the mole in action and you will be able to observe your users exercising your application in real time.
The Snitch: svn co svn://rubyforge.org/var/svn/liquidrail/plugins/mole/samples/consoles/snitch Molet: svn co svn://rubyforge.org/var/svn/liquidrail/plugins/mole/samples/consoles/widgets/molet
IMPORTANT: In order to complete the Snitch installation, you will need to tell the app where and how to access your user model. You will need to run ‘rake setup’ that will ask you for your users database table name and the name of the column to display the user name. The Snitch only accesses the database in read only mode.
IMPORTANT2: In order to run the companion widget application, you will need to install the Yahoo! Widget Engine (widgets.yahoo.com/download) 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) and place the molet_widget.widget file (bundled with the plugin) in your platform widgets directory. Then double click the molet_widget.widget file to launch the widget. The widget depends on the Snitch app being up and running to fetch its data. You can right click on the widget and go to the preference dialog to point to the Snitch url. By default the preference is set to localhost:3000…
NOTE: These apps are very generic and you may need to tune them to satisfy your needs. However if you add some cool features and would like to contribute back, we will be more than happy to hear about them and help you incorporate your contributions.
We hope you find this plugin useful and add it to your rails toolset… Please report any cool findings on the forum…
NOTE TO SELF: You can also leverage the mole to assess the quality of your testing. We incidentally found it useful to use the mole during QA to assess test coverage…