rackamole 0.0.6 → 0.0.7

data/README.rdoc

@@ -82,7 +82,7 @@ interactions and leverage these findings for the next iteration of your applicat
 
 (The MIT License)
 
-Copyright (c) 2008 FIXME (different license?)
+Copyright (c) 2009
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/Rakefile

@@ -28,4 +28,6 @@ PROJ.rcov.opts       = ["--sort", "coverage", "-T", '-x mongo']
 depend_on "logging"      , ">= 1.2.2"
 depend_on "hitimes"      , ">= 1.0.3"
 depend_on "mongo"        , ">= 0.17.1"
-depend_on "darkfish-rdoc", ">= 1.1.5"
+depend_on "darkfish-rdoc", ">= 1.1.5"
+depend_on "twitter4r"    , ">= 0.3.0"
+depend_on "actionmailer" , ">= 2.1.0"

data/aa.txt

@@ -0,0 +1,10 @@
+:twitt_if       => [Rackamole.feature, Rackamole.fault, Rackamole.perf],
+:twitter        => { :username => 'moled', :password => 'fernand~1' },
+        
+require 'action_mailer'
+ActionMailer::Base.delivery_method       = :sendmail
+ActionMailer::Base.raise_delivery_errors = true                                       
+        
+:email          => { :from => 'fernand@collectiveintellect.com', :to => ['fernand@collectiveintellect.com'] },
+:email_if       => [Rackamole.feature, Rackamole.fault],
+        

data/lib/rackamole.rb

@@ -1,21 +1,24 @@
 module Rackamole
 
   # :stopdoc:
-  VERSION = '0.0.6'
+  VERSION = '0.0.7'
   LIBPATH = ::File.expand_path(::File.dirname(__FILE__)) + ::File::SEPARATOR
   PATH = ::File.dirname(LIBPATH) + ::File::SEPARATOR
   # :startdoc:
 
   # Returns the version string for the library.
-  #
   def self.version
     VERSION
   end
 
+  # Defines the default moled activity types
+  def self.feature() 0; end
+  def self.perf()    1; end
+  def self.fault()   2; end
+
   # Returns the library path for the module. If any arguments are given,
   # they will be joined to the end of the libray path using
   # <tt>File.join</tt>.
-  #
   def self.libpath( *args )
     args.empty? ? LIBPATH : ::File.join(LIBPATH, args.flatten)
   end
@@ -23,7 +26,6 @@ module Rackamole
   # Returns the lpath for the module. If any arguments are given,
   # they will be joined to the end of the path using
   # <tt>File.join</tt>.
-  #
   def self.path( *args )
     args.empty? ? PATH : ::File.join(PATH, args.flatten)
   end
@@ -32,7 +34,6 @@ module Rackamole
   # directory below this file that has the same name as the filename passed
   # in. Optionally, a specific _directory_ name can be passed in such that
   # the _filename_ does not have to be equivalent to the directory.
-  #
   def self.require_all_libs_relative_to( fname, dir = nil )
     dir ||= ::File.basename(fname, '.*')
     search_me = ::File.expand_path(

data/lib/rackamole/alert/emole.rb

@@ -0,0 +1,67 @@
+require 'action_mailer'
+
+module Rackamole::Alert
+  class Emole < ActionMailer::Base        
+    self.template_root = File.join( File.dirname(__FILE__), %w[templates] )
+        
+    # Send an email notification for particular moled feature. An email will
+    # be sent based on the two configuration :emails and :mail_on defined on the
+    # Rack::Mole component. These specify the to and from addresses and the conditions
+    # that will trigger the email, currently :enabled and :features for the type of
+    # moled features to track via email. The notification will be sent via actionmailer,
+    # so you will need to make sure it is properly configured for your domain.
+    # NOTE: This is just a notification mechanism. All moled event will be either logged 
+    # or persisted in the db regardless.
+    #
+    # === Parameters:
+    # from       :: The from address address. Must be a valid domain.
+    # recipients :: An array of email addresses for recipients to be notified.
+    # args       :: The gathered information from the mole.
+    #
+    def alert( from, recipients, args )
+      buff = []
+      
+      dump( buff, args, 0 )
+      
+      from        from
+      recipients  recipients
+      subject     "[M()le] (#{alert_type( args )}#{request_time?( args )}) -#{args[:app_name]}@#{args[:host]}- for user #{args[:user_name]}"        
+      body        :args  => args,
+                  :dump  => buff.join( "\n" )
+    end
+        
+    # =========================================================================               
+    private
+           
+      # Dump request time if any...
+      def request_time?( args )
+        args[:type] == Rackamole.perf ? ":#{args[:request_time]}" : ''        
+      end
+      
+      # Identify the type of alert...        
+      def alert_type( args ) 
+        case args[:type]
+          when Rackamole.feature : "Feature"
+          when Rackamole.perf    : "Performance"
+          when Rackamole.fault   : "Fault"
+        end
+      end
+
+      # Dump args...
+      def dump( buff, env, level=0 )
+        env.each_pair do |k,value|
+          if value.respond_to?(:each_pair) 
+            buff << "%s %-#{40-level}s" % ['  '*level,k]
+            dump( buff, env[k], level+1 )
+          elsif value.instance_of?(Array)
+            buff << "%s %-#{40-level}s" % ['  '*level,k]
+            value.each do |v| 
+              buff << "%s %-#{40-(level+1)}s" % ['  '*(level+1),v]
+            end
+          else
+            buff << "%s %-#{40-level}s %s" % [ '  '*level, k, value.inspect ]
+          end        
+        end
+      end
+  end
+end

data/lib/rackamole/alert/templates/rackamole/alert/emole/alert.erb

@@ -0,0 +1,9 @@
+A watched feature was triggered in application `<%= @args[:app_name] %> on host `<%=@args[:host]%>
+
+Details...
+
+<%= @dump %>
+
+- Your Rackamole
+
+This message was generated automatically. Please do not respond directly.

data/lib/rackamole/alert/twitt.rb

@@ -0,0 +1,73 @@
+require 'twitter'
+
+module Rackamole::Alert
+  # Leverage twitter as a notification client. You can setup a private twitter account
+  # and have your moled app twitt exception/perf alerts...
+  class Twitt
+                
+    # This class is used to send out moled twitter notification. This feature is enabled
+    # by setting both :twitter_auth and twitt_on options on the Rack::Mole. When a moled 
+    # feature comes around it will be twitted on your configured account. This allow your
+    # app to twitt about it's status and issues. Currently there are no provisions to throttle
+    # the twitts, hence sending out twitt notifications of every moled features would not be 
+    # a very good idea. Whereas sending twitts when your application bogs down or throws exception,
+    # might be more appropriate. Further work will take place to throttle these events...
+    # Creating a private twitter account and asking folks in your group to follow might be an
+    # alternative to email.
+    #
+    # NOTE: This is just an alert mechanism. All moled events will be either logged or persisted in the db
+    # regardless.
+    #
+    # === Params:
+    # username :: The name on the twitter account
+    # password :: The password of your twitter account
+    def initialize( username, password )
+      raise "You must specify your twitter account credentials" unless username or password
+      @username = username
+      @password = password
+    end
+       
+    # Send out a twitt notification based of the watched features. A short message will be blasted to your twitter
+    # account based on information reported by the mole. The twitt will be automatically truncated
+    # to 140 chars.
+    #
+    # === Params:
+    # args :: The moled info for a given feature. 
+    #
+    def send_alert( args )
+      twitt_msg = "#{args[:app_name]}:#{args[:host]}\n#{args[:user_name]} : #{display_feature(args)}"
+      twitt_msg = case args[:type]
+        when Rackamole.feature : "[Feature] -- #{twitt_msg}"
+        when Rackamole.perf    : "[Perf]    -- #{twitt_msg} : #{args[:request_time]} secs"
+        when Rackamole.fault   : "[Fault]   -- #{twitt_msg} : #{args[:fault]}"
+        else nil
+      end      
+      twitt.status( :post, truncate( twitt_msg ) ) if twitt_msg
+      twitt_msg
+    rescue => boom
+      $stderr.puts "TWITT mole failed with #{boom}"
+    end                                  
+        
+    private
+    
+       attr_reader :username, :password #:nodoc:
+       
+       # Fetch twitter connection...
+       def twitt
+         @twitt ||= ::Twitter::Client.new( :login => username, :password => password )
+       end
+       
+       # Display controller/action or path depending on frmk used...
+       def display_feature( args )
+         return args[:path] unless args[:route_info]
+         "#{args[:route_info][:controller]}##{args[:route_info][:action]}"
+       end
+
+      # Truncate for twitt max size       
+      def truncate(text, length = 140, truncate_string = "...")
+        return "" if text.nil?
+        l = length - truncate_string.mb_chars.length
+        text.mb_chars.length > length ? (text.mb_chars[0...l] + truncate_string).to_s : text
+      end       
+  end
+end

data/lib/rackamole/interceptor.rb

@@ -1,9 +1,15 @@
 module Rackamole
   module Interceptor
     
+    # === For Rails only!
+    #
+    # Rails handles raised exception in a special way. 
+    # Thus special care need to be taken to enable exception to bubble up
+    # to the mole.
+    #
     # In order for the mole to trap framework exception, you must include
     # the interceptor in your application controller.
-    # ie include Wackamole::Interceptor
+    # ie include Rackamole::Interceptor
     def self.included( base )
       base.send( :alias_method_chain, :rescue_action_in_public, :mole )
       base.send( :alias_method_chain, :rescue_action_locally, :mole )

data/lib/rackamole/logger.rb

@@ -5,7 +5,7 @@ module Rackamole
   class Logger
     class ConfigurationError < StandardError ; end  #:nodoc:
 
-    attr_reader :log # here for testing, don't really use it.
+    attr_reader :log #:nodoc:
 
     extend Forwardable
     def_delegators :@log, :debug, :warn, :info, :error, :fatal 
@@ -47,7 +47,10 @@ module Rackamole
       }
     end
 
-    # create a new logger
+    # Creates a logger for mole usage by leveraging the most excellent logging gem.
+    # This provides for a semi persistent storage for mole information, typically set up
+    # for the console or a file. By default moled features will be sent out to the console.
+    # Alternatively you can store the moled info to a file.
     #
     def initialize( opts = {} )
       @options = ::Rackamole::Logger.default_options.merge(opts)

data/lib/rackamole/mole.rb

@@ -2,21 +2,59 @@ require 'hitimes'
 require 'json'
 require 'mongo'
 
+# BOZO !! - Need args validator or use dsl as the args are out of control...
 module Rack
   class Mole
     
-    # Initialize The Mole with the possible options
-    # <tt>:app_name</tt>    - The name of the application [Default: Moled App]
-    # <tt>:environment</tt> - The environment for the application ie :environment => RAILS_ENV
-    # <tt>:perf_threshold</tt> - Any request taking longer than this value will get moled [Default: 10]    
-    # <tt>:moleable</tt>    - Enable/Disable the MOle [Default:true]
-    # <tt>:store</tt>       - The storage instance ie log file or mongodb [Default:stdout]
-    # <tt>:user_key</tt>    - If session is enable, the session key for the user name or user_id. ie :user_key => :user_name 
+    # Initialize The Mole rack component. It is recommended that you specify at a minimum a user_key to track
+    # interactions on a per user basis. If you wish to use the mole for the same application in different 
+    # environments you should set the environment attribute RAILS_ENV for example. The perf_threshold setting 
+    # is also recommended to get performance notifications should your web app start sucking. 
+    # By default your app will be moleable upon installation and you should see mole features spewing out in your 
+    # logs. This is the default setting. Alternatively you can store mole information in a mongo database by 
+    # specifying a different store option.
+    #
+    # === Options
+    #
+    # :app_name       :: The name of the application (Default: Moled App)
+    # :environment    :: The environment for the application ie :environment => RAILS_ENV
+    # :perf_threshold :: Any request taking longer than this value will get moled. Default: 10secs
+    # :moleable       :: Enable/Disable the MOle (Default:true)
+    # :store          :: The storage instance ie log file or mongodb [Default:stdout]
+    # :user_key       :: If sessions are enable, this represents the session key for the user name or 
+    #                    user_id.
+    # ==
+    #  If the username resides in the session hash with key :user_name the you can use:
+    #    :user_key => :user_name
+    #  Or you can eval it on the fly - though this will be much slower and not recommended
+    #    :user_key => { :session_key => :user_id, :extractor => lambda{ |id| User.find( id ).name} }
+    # ==
+    #
+    # :twitter_auth  :: You can setup the MOle twit interesting events to a private (public if you indulge pain!) twitter account.
+    #                   Specified your twitter account information using a hash with :username and :password key
+    # :twitt_on      :: You must configure your twitter auth and configuration using this hash. By default this option is disabled.
+    # ==
+    #   :twitt_on => { :enabled  => false, :features => [Rackamole.perf, Rackamole.fault] }
+    # ==
+    # ==== BOZO! currently there is not support for throttling or monitoring these alerts. 
+    # ==
+    # :emails        :: The mole can be configured to send out emails bases on interesting mole features.
+    #                   This feature uses actionmailer. You must specify a hash for the from and to options.
+    # ==
+    #   :emails => { :from => 'fred@acme.com', :to => ['blee@acme.com', 'doh@acme.com'] }
+    # ==
+    # :mail_on      :: Hash for email alert triggers. May be enabled or disabled per env settings. Default is disabled
+    # ==
+    #   :mail_on => {:enabled => true, :features => [Rackamole.perf, Rackamole.fault] }
     def initialize( app, opts={} )
       @app = app
       init_options( opts )
+      validate_options
     end
-            
+          
+    # Entering the MOle zone...
+    # Watches incoming requests and report usage information. The mole will also track request that
+    # are taking longer than expected and also report any requests that are raising exceptions. 
     def call( env )
       # Bail if application is not moleable
       return @app.call( env ) unless moleable?
@@ -27,27 +65,22 @@ module Rack
           status, headers, body = @app.call( env )
         rescue => boom
           env['mole.exception'] = boom
-          @store.mole( mole_info( env, elapsed, status, headers, body ) )
+          mole_feature( env, elapsed, status, headers, body )
           raise boom
         end
       end
-      @store.mole( mole_info( env, elapsed, status, headers, body ) )
+      mole_feature( env, elapsed, status, headers, body )
       return status, headers, body
     end 
 
   # ===========================================================================  
   private
        
+    attr_reader :options #:nodoc:
+        
     # Load up configuration options
     def init_options( opts )
-      options          = default_options.merge( opts )      
-      @environment     = options[:environment]
-      @perf_threshold  = options[:perf_threshold]
-      @moleable        = options[:moleable]
-      @app_name        = options[:app_name]
-      @user_key        = options[:user_key]
-      @store           = options[:store]
-      @excluded_paths  = options[:excluded_paths]
+      @options = default_options.merge( opts )      
     end
     
     # Mole default options
@@ -57,13 +90,61 @@ module Rack
         :excluded_paths  =>  [/.?\.ico/, /.?\.png/],
         :moleable        =>  true,
         :perf_threshold  =>  10,
-        :store           =>  Rackamole::Store::Log.new
+        :store           =>  Rackamole::Store::Log.new,
+        :twitt_on        =>  { :enabled => false, :features => [Rackamole.perf, Rackamole.fault] },
+        :mail_on         =>  { :enabled => false, :features => [Rackamole.perf, Rackamole.fault] }
       }
     end
-       
+           
+    # Validates all configured options... Throws error if invalid configuration
+    def validate_options
+      %w[app_name moleable perf_threshold store].each do |k|
+        raise "[M()le] -- Unable to locate required option key `#{k}" unless options[k.to_sym]
+      end
+    end
+    
+    # Send moled info to store and potentially send out alerts...
+    def mole_feature( env, elapsed, status, headers, body )
+      attrs = mole_info( env, elapsed, status, headers, body )
+      
+      # send info to configured store
+      options[:store].mole( attrs )
+      
+      # send email alert ?
+      if configured?( :emails, [:from, :to] ) and alertable?( options[:mail_on], attrs[:type] )
+        Rackamole::Alert::Emole.deliver_alert( options[:emails][:from], options[:emails][:to], attrs ) 
+      end
+      
+      # send twitter alert ?
+      if configured?( :twitter_auth, [:username, :password] ) and alertable?( options[:twitt_on], attrs[:type] )
+        twitt.send_alert( attrs ) 
+      end      
+    rescue => boom
+      $stderr.puts "!! MOLE RECORDING CRAPPED OUT !! -- #{boom}"
+      boom.backtrace.each { |l| $stderr.puts l }
+    end
+    
+    # Check if an options is set and configured
+    def configured?( key, configs )
+      return false unless options[key]
+      configs.each { |c| return false unless options[key][c] }
+      true
+    end
+    
+    # Check if feature should be send to alert clients ie email or twitter
+    def alertable?( filters, type )
+      return false if !filters or filters.empty? or !filters[:enabled]
+      filters[:features].include?( type )
+    end
+    
+    # Create or retrieve twitter client
+    def twitt
+      @twitt ||= Rackamole::Alert::Twitt.new( options[:twitter_auth][:username], options[:twitter_auth][:password] )
+    end
+        
     # Check if this request should be moled according to the exclude filters        
     def mole_request?( request )
-      @excluded_paths.each do |exclude_path|
+      options[:excluded_paths].each do |exclude_path|
         return false if request.path.match( exclude_path )
       end
       true
@@ -87,19 +168,21 @@ module Rack
            
       # BOZO !! This could be slow if have to query db to get user name...
       # Preferred store username in session and give at key
-      if session and @user_key
-        if @user_key.instance_of? Hash
-          user_id  = session[ @user_key[:session_key] ]
-          if @user_key[:extractor]
-            user_name = @user_key[:extractor].call( user_id )
+      user_key = options[:user_key]
+      if session and user_key
+        if user_key.instance_of? Hash
+          user_id  = session[ user_key[:session_key] ]
+          if user_key[:extractor]
+            user_name = user_key[:extractor].call( user_id )
           end
         else
-          user_name = session[@user_key]
+          user_name = session[user_key]
         end
       end
-            
-      info[:app_name]     = @app_name
-      info[:environment]  = @environment || "Unknown"
+          
+      info[:type]         = (elapsed and elapsed > options[:perf_threshold] ? Rackamole.perf : Rackamole.feature)
+      info[:app_name]     = options[:app_name]
+      info[:environment]  = options[:environment] || "Unknown"
       info[:user_id]      = user_id      if user_id
       info[:user_name]    = user_name || "Unknown"
       info[:ip]           = ip
@@ -107,7 +190,6 @@ module Rack
       info[:host]         = env['SERVER_NAME']
       info[:software]     = env['SERVER_SOFTWARE']
       info[:request_time] = elapsed if elapsed
-      info[:performance]  = (elapsed and elapsed > @perf_threshold)
       info[:url]          = request.url
       info[:method]       = env['REQUEST_METHOD']
       info[:path]         = request.path
@@ -129,13 +211,12 @@ module Rack
       exception = env['mole.exception']
       if exception
         info[:ruby_version]   = %x[ruby -v]
+        info[:fault]          = exception.to_s
         info[:stack]          = trim_stack( exception )
+        info[:type]           = Rackamole.fault
         env['mole.exception'] = nil
       end      
       info
-    rescue => boom
-      $stderr.puts "!! MOLE RECORDING CRAPPED OUT !! -- #{boom}"
-      boom.backtrace.each { |l| $stderr.puts l }
     end
         
     # Attempts to detect browser type from agent info.
@@ -162,7 +243,7 @@ module Rack
             
     # Checks if this application is moleable
     def moleable?
-      @moleable
+      options[:moleable]
     end
     
     # Fetch route info if any...