| Path: | README.txt |
| Last Update: | Tue Mar 25 00:45:18 -0600 2008 |
The MOle
by Fernand Galiana
liquidrail.com
The MOle allows you to track user‘s interactions with your ruby application and closely monitors how your customers are using your application. This is a must cheaper way than to hire a monitoring service and produces much more detailed information on your application behavior and usage. To boot your managers will love you !
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‘ll 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.
The MOle was initialy released as a Rails plugin, but we found the behavior usefull in other types of projects such as Merb or straight up ruby applications, and decided to re-release it as a gem instead.
The MOle allows you to easily
> cd my_non_moled_application > molify --up --config config/database.yml --env test
This command will update your test database and create the MOle tables required when the MOle is in a persistent mode. Namely, these tables are mole_features and mole_logs.
You can use molify —help to see usage information.
require 'mole'
Mole.initialize( :moleable => true,
:application => "Smf",
:emole_from => "MoleBeatch@liquidrail.com",
:emole_recipients => ['fernand@liquidrail.com'],
:mode => :persistent,
:log_file => $stdout,
:log_level => :debug,
:perf_threshold => 2,
:mole_config => File.join( File.dirname(__FILE__), %w[mole.rb] ) )
# Load the MOle configuration file(s)
::Mole.load_configuration
NOTE: The mole_config can either be a single ruby file or a directory containing multiple MOle configuration files. Thanks to Ian Schreuder for the suggestion !
NOTE: For rails applications you can either put the MOle initialization code in a custom initializer ie config/initializers/mole.rb or in your environment file (config/environments/production.rb). You will need to make the load_configuration call in your application controller(application.rb) as follows:
::Mole.load_mole_configuration rescue nil
In dev env, the MOle will reload the configuration so you can tweak your app on the fly. In production env the MOle configuration will be loaded once.
To trap a feature before or after it occurs you can use the mole_before/mole_after interceptors. The following will mole the "Posts" class after the "show" method is called. The context argument hands you an execution context. In a rails/merb environment this will be your controller object. You can handle this interaction any way you want. The MOle provides a convenience class to record this interaction via the database or the MOle logger in the guise of Mole::Moler. But you can also log it to any media you‘ll find suitable. In a rails/merb context, you‘ll be able to extract session/params information as in this case.
Posts.mole_after( :feature => :show ) { |context, feature, ret, block, *args|
# Records the interaction to the database
Mole::Moler.mole_it( context, feature,
context.session[:user_id], # Retrieves which user performed this action
:post_id=> context.params[:post_id], # Records request parameter post id
:url => context.instance_variable_get( "@url" ) ) # Retrieves controller state
end
}
To record performance issues, you will need to provide a collection of methods that must be watched on a given class. In the case of rails or merb you can easily fetch the list of actions from the controller api and pass it to the MOle. The MOle provides convenience classes to log the perf issues to your database and send out alerts when a perf condition is met. Upon invocation, you will be handed a calling context, that comprises the feature (method) being called, the actual time it took to complete the call and any args/block that was passed into the feature that causes the performance threshold to be triggered. Setting the :email option to true will also send out an email alert.
Posts.mole_perf( :features => merb_actions ) do |context, feature, elapsed_time, ret, block, *args|
user = context.instance_variable_get( "@user" )
key = context.params[:key], "N/A"
request = context.request.nil? ? "N/A" : context.request.remote_ip,
Mole::Moler.perf_it( context, user.id,
:controller => context.class.name,
:feature => feature,
:key => key,
:request => request,
:user => user.user_name,
:elapsed_time => "%3.3f" % elapsed_time,
:email => true )
end
The unchecked exception trap works very similarly to the mole_perf trap. It will pass in the context of the method that triggered the exception.
Posts.mole_unchecked( :features => merb_actions ) do |context, action, boom, block, *args|
sub = context.instance_variable_get("@sub")
user_id = "N/A"
user_id = sub.user.id if sub and sub.user
Mole::Moler.check_it( context, user_id,
:controller => context.class.name,
:action => action,
:boom => boom,
:email => true )
end
To view MOle interaction simply, we‘ve created the "Snitch" a rails console application that allows you to see the results of your MOled application. The Snitch is a Rails 2.0 application. It is available at mole.rubyforge.org/svn/snitch/trunk/.
In order to start using the Snitch you will have to perform the following steps:
svn co http://mole.rubyforge.org/svn/snitch/trunk/
> rake setup
> script/server
Then in your browser
MIT Copyright (c) 2008
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the ‘Software’), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED ‘AS IS’, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.