tartarus 1.0.0

data/.document

@@ -0,0 +1,5 @@
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/.gitignore

@@ -0,0 +1,5 @@
+*.sw?
+.DS_Store
+coverage
+rdoc
+pkg

data/README.rdoc

@@ -0,0 +1,54 @@
+= Tartarus
+
+It is a deep, gloomy place, a pit, or an abyss used as a dungeon of torment and suffering..
+
+Tartarus provides logging to your database for exceptions triggered by the users of 
+your Rails application. A generator is included that will give you a clean interface 
+to view and manage the exceptions.
+
+=== Dependencies
+
+If you wish to use the generator to build the exception viewing/manging interface, the following 
+dependencies are used:
+
+* will_paginate
+* jquery
+
+=== Installation
+
+1. Install the gem:
+     [sudo] gem install tartarus
+2. Add the exceptional gem dependency to your enviroment.rb:
+     config.gem "tartarus"
+3. Run the generator from the root of your Rails application:
+     script/generate tartarus
+4. Run the migration that was generated:
+     rake db:migrate
+5. Add the javascript and stylesheet includes in your layout:
+     <script type="text/javascript" src="/javascripts/tartarus.jquery.js"></script>
+     <link href="/stylesheets/tartarus.css" media="all" rel="stylesheet" type="text/css" />
+6. View the generated 'config/exceptions.yml' file and make sure the default options are correct.
+
+=== License
+
+Copyright (c) 2009 Daniel Insley
+
+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.
+

data/Rakefile

@@ -0,0 +1,50 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "tartarus"
+    gem.summary = %Q{Exception Logging for Rails}
+    gem.description = %Q{Provides exception logging and a generator for creating a clean interface to manage exceptions.}
+    gem.email = "dinsley@gmail.com"
+    gem.homepage = "http://github.com/dinsley/tartarus"
+    gem.authors = ["Daniel Insley"]
+    gem.add_dependency "will_paginate"
+    gem.add_development_dependency "rails"
+    gem.add_development_dependency "rspec"
+    gem.add_development_dependency "rspec-rails"
+    # Gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
+end
+
+require 'spec/rake/spectask'
+
+Spec::Rake::SpecTask.new(:spec) do |spec|
+  spec.spec_opts = ['--options', "spec/spec.opts"]
+  spec.libs << 'lib' << 'spec'
+  spec.spec_files = FileList['spec/**/*_spec.rb']
+  spec.rcov = true
+  spec.rcov_opts = lambda do
+    IO.readlines("spec/rcov.opts").map { |l| l.chomp.split " " }.flatten
+  end
+end
+
+task :spec => :check_dependencies
+task :default => :spec
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  if File.exist?('VERSION')
+    version = File.read('VERSION')
+  else
+    version = ""
+  end
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "tartarus #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+1.0.0

data/generators/tartarus/USAGE

@@ -0,0 +1,14 @@
+Description:
+    Generates a model, controller and views for viewing and managing exceptions.  
+
+Usage:
+    If you do not pass any arguments, the model class will default to "LoggedException".
+
+Examples:
+    script/generate tartarus
+
+        Creates default logged exception model, controller, and views.
+
+    script/generate tartarus MyException
+
+        Creates a custom model, controller, and views.

data/generators/tartarus/tartarus_generator.rb

@@ -0,0 +1,51 @@
+class TartarusGenerator < Rails::Generator::NamedBase
+  default_options :skip_migration => false
+
+  def initialize(runtime_args, runtime_options = {})
+    runtime_args << 'LoggedException' if runtime_args.empty?
+    super
+  end
+  
+  def manifest
+    record do |m|      
+      puts "\nGenerated files:\n"
+      # Directories
+      m.directory "app/views/exceptions"
+      m.directory "spec/models"
+      m.directory "spec/controllers"
+
+      # Configuration
+      m.template 'config/exceptions.yml', 'config/exceptions.yml'
+
+      #Migration        
+      m.migration_template "db/migrate/add_logged_exceptions.rb", "db/migrate", :migration_file_name => "add_#{singular_name}_table"
+
+      # Controllers
+      m.template 'app/controllers/exceptions_controller.rb', "app/controllers/exceptions_controller.rb"
+
+      # Views
+      Dir.glob( File.dirname(__FILE__) + '/templates/app/views/exceptions/*.html.erb').each do |path| 
+        view = File.basename( path )
+        m.file "app/views/exceptions/#{view}", "app/views/exceptions/#{view}"
+      end
+
+      # Models
+      m.template 'app/models/logged_exception.rb', "app/models/#{file_name}.rb"
+
+      # Specs
+      m.template 'spec/models/logged_exception_spec.rb', "spec/models/#{file_name}_spec.rb"
+      m.template 'spec/controllers/exceptions_controller_spec.rb', 'spec/controllers/exceptions_controller_spec.rb'
+
+      # Public
+      m.file 'public/javascripts/tartarus.jquery.js', 'public/javascripts/tartarus.jquery.js'
+      m.file 'public/stylesheets/tartarus.css', 'public/stylesheets/tartarus.css'
+    end
+  end
+
+  def after_generate
+    puts "\nIn order for exceptional to function properly, you'll need to complete the following steps to complete the installation process: \n\n"
+    puts "  1) Run 'rake db:migrate' to generate the logging table for your model.\n"
+    puts "  2) Add '/javascripts/tartarus.jquery.js', and 'stylesheets/tartarus.css' to your applications layout.\n"
+    puts "  3) View 'config/exceptions.yml' and make sure the default options are correct.\n\n"
+  end
+end

data/generators/tartarus/templates/app/controllers/exceptions_controller.rb

@@ -0,0 +1,31 @@
+class ExceptionsController < ApplicationController
+  def index
+    @exceptions = <%= class_name %>.all(:select => '*, COUNT(*) as count', :group => 'group_id', :order => 'created_at DESC')
+  end
+
+  def details
+    @exceptions = <%= class_name %>.paginate(:all, :conditions => { :group_id => params[:id] }, :order => 'created_at DESC', :page => params[:page], :per_page => 1)
+    @exception = @exceptions.first
+  end
+
+  def remove_all
+    <%= class_name %>.delete_all
+    redirect_to :action => :index
+  end
+
+  def remove_group
+    <%= class_name %>.delete_all(:group_id => params[:id])
+    redirect_to :action => :index
+  end
+
+  def remove_individual
+    exception = <%= class_name %>.find_by_id(params[:id])
+    exception.destroy
+
+    if <%= class_name %>.count(:conditions => { :group_id => exception.group_id }).zero?
+      redirect_to :action => :index
+    else
+      redirect_to :action => :details, :id => exception.group_id
+    end
+  end
+end

data/generators/tartarus/templates/app/models/logged_exception.rb

@@ -0,0 +1,3 @@
+class <%= class_name %> < ActiveRecord::Base
+  include Tartarus::Logger
+end

data/generators/tartarus/templates/app/views/exceptions/_exception.html.erb

@@ -0,0 +1,14 @@
+<tr id="exception_<%= exception.group_id %>">
+  <td>
+    <strong><%= link_to "#{exception.exception_class}", :action => 'details', :id => exception.group_id %></strong>
+    <br />
+    <span><%= truncate(exception.message, :length => 115) %></span>
+  </td>
+
+  <td>
+    <%= "#{exception.controller_path}##{exception.action_name}" %>
+  </td>
+
+  <td><%= exception.created_at.strftime("%m/%d/%Y %I:%M%p") %></td>
+  <td style="text-align: center;"><%= exception.count %></td>
+</tr>

data/generators/tartarus/templates/app/views/exceptions/details.html.erb

@@ -0,0 +1,86 @@
+<div id="tartarus">
+  <div id="exception_group_details">
+    <div  id="tartarus_cap">
+      <div id="tartarus_nav">
+        <%= link_to 'Return to overview', :controller => 'exceptions', :action => 'index' %>
+        <%= will_paginate @exceptions, :page_links => false, :class => 'tartarus_pagination' %>
+      </div>
+      <h2><%= @exception.exception_class %> in "<%= "#{@exception.controller_path}##{@exception.action_name}" %>"</h2>
+      <div>Viewing Exception <%= params[:page] || 1 %> of <%= @exceptions.total_pages %></div>
+    </div>
+  </div>
+
+  <h3><%= @exception.created_at.strftime("%B %e %Y at %I:%M:%S%p") %></h3>
+  <pre><%= @exception.message %></pre>
+
+  <div id="exception_actions">
+    <%= link_to 'Remove all', :action => 'remove_group', :id => @exception.group_id %>
+    &middot;
+    <%= link_to 'Remove', :action => 'remove_individual', :id => @exception.id %>
+  </div>
+
+  <div id="exception">
+    <div id="request_information" class="togglable">
+      <h3><a class="toggle_link" href="javascript:void(0);">Request</a></h3>
+      <ul class="toggle_data">
+        <% @exception.request[:http_details].each_pair do |key, value| %>
+          <% unless value.blank? %>
+            <li><strong><%= key %></strong> :
+              <% if value.is_a?(Hash) %>
+                <ul>
+                  <% value.each_pair do |key, value| %>
+                    <% unless value.blank? %>
+                      <li><strong><%= key %></strong> : <%= value %></li>
+                    <% end %>
+                    <% end%>
+                </ul>
+              <% else %>
+                <%= value %>
+                <% end %>
+            </li>
+          <% end %>
+        <% end %>
+      </ul>
+    </div>
+
+    <div id="backtrace_information" class="togglable">
+      <h3><a class="toggle_link" href="javascript:void(0);">Backtrace</a></h3>
+      <pre class="toggle_data"><%= h(@exception.backtrace) %></pre>
+    </div>
+
+    <div id="session_information" class="togglable">
+      <h3><a class="toggle_link" href="javascript:void(0);">Session & Cookies</a></h3>
+      <ul class="toggle_data">
+        <% @exception.request[:session].each_pair do |key, value| %>
+          <% unless value.blank? %>
+            <li><strong><%= key %></strong> :
+              <% if value.is_a?(Hash) %>
+                <ul>
+                  <% value.each_pair do |key, value| %>
+                    <% unless value.blank? %>
+                      <li><strong><%= key %></strong> : <%= value %></li>
+                    <% end %>
+                  <% end %>
+                </ul>
+              <% else %>
+                <%= value %>
+              <% end %>
+            </li>
+          <% end %>
+        <% end %>
+      </ul>
+    </div>
+
+    <div id="enviroment_information" class="togglable"> 
+      <h3><a class="toggle_link" href="javascript:void(0);">Enviroment</a></h3>
+      <ul class="toggle_data">
+        <% @exception.request[:enviroment].each_pair do |key, value| %>
+          <% unless value.blank? %>
+            <li><strong><%= key%></strong> : <%= value %></li>
+          <% end %>
+        <% end %>
+      </ul>
+    </div>
+  </div>
+</div>
+

data/generators/tartarus/templates/app/views/exceptions/index.html.erb

@@ -0,0 +1,28 @@
+<div id="tartarus">
+  <div id="tartarus_cap">
+    <div id="tartarus_nav">
+      <%= link_to 'Remove all', :action => :remove_all %>
+    </div>
+    <h2>Exception Overview</h2>
+    <div><%= @exceptions.length %> Exceptions</div>
+  </div>
+  
+  <table id="tartarus_overview">
+    <thead>
+      <tr>
+        <th id="exception_summary">Summary</th>
+        <th id="exception_location">Location</th>
+        <th id="exception_date">Latest</th>
+        <th id="exception_count">Count</th>
+      </tr>
+    </thead>
+    
+    <tbody>
+      <% @exceptions.each do |exception| %>  
+        <%= render :partial => 'exception', :object => exception %>
+      <% end %>
+    </tbody>
+    
+  </table>
+</div>
+

data/generators/tartarus/templates/config/exceptions.yml

@@ -0,0 +1,9 @@
+development:
+  enabled: false
+  logger_class: <%= class_name %> 
+test:
+  enabled: false
+  logger_class: <%= class_name %> 
+production:
+  enabled: true
+  logger_class: <%= class_name %> 

data/generators/tartarus/templates/db/migrate/add_logged_exceptions.rb

@@ -0,0 +1,18 @@
+class Add<%= class_name %>Table < ActiveRecord::Migration
+  def self.up
+    create_table :<%= plural_name %>, :force => true do |t|
+      t.string   :group_id
+      t.string   :exception_class
+      t.string   :controller_path
+      t.string   :action_name
+      t.text     :message
+      t.text     :backtrace
+      t.text     :request
+      t.datetime :created_at
+    end
+  end
+
+  def self.down
+    drop_table :<%= plural_name %>
+  end
+end

data/generators/tartarus/templates/public/javascripts/tartarus.jquery.js

@@ -0,0 +1,6 @@
+$(function(){
+  $('.togglable').each(function() {
+    var toggle_data = $(this).find('.toggle_data');
+    $(this).find('.toggle_link').click(function() { toggle_data.toggle(); })
+  });
+});

data/generators/tartarus/templates/public/stylesheets/tartarus.css

@@ -0,0 +1,26 @@
+#tartarus { margin: 0px 20px }
+
+#tartarus_cap { padding-bottom: 10px; border-bottom: 1px solid #777; margin: 20px 0px; }
+#tartarus h2 { margin: 10px 0px; } 
+
+#tartarus_nav { float: right }
+.tartarus_pagination { margin-top: 20px; }
+
+#tartarus table { border-collapse: collapse; width: 100%; }
+#tartarus table tr { border-bottom: 1px solid #E0DFE0; }
+#tartarus table th, #tartarus table td { padding: 5px; }
+#tartarus table th { text-align: left; }
+
+#tartarus th#exception_location { width: 150px; }
+#tartarus th#exception_date { width: 150px; }
+#tartarus th#exception_count { text-align: center; }
+
+#tartarus pre { -webkit-border-radius: 5px; -moz-border-radius: 5px; font-size: 10px; color: #fff; background-color: #222; padding: 10px; font-family: Consolas, Monaco, 'Courier New', Courier,monospace; }
+#tartarus a, #tartarus a:visited { text-decoration: underline; #bdf; } 
+#tartarus a:hover { #09f }
+
+#tartarus #exception { clear: both; }
+#tartarus #exception_actions { float: right; }
+
+.toggle_data { display: none }
+#backtrace_information .toggle_data { display: block; }

data/generators/tartarus/templates/spec/controllers/exceptions_controller_spec.rb

@@ -0,0 +1,83 @@
+require File.dirname(__FILE__) + '/../spec_helper'
+
+describe ExceptionsController do 
+  before(:each) do
+    @exception = <%= class_name %>.new
+  end
+
+  describe "#index" do
+    it 'should set an assigns of exceptions with the collection of all exception groups' do
+      <%= class_name %>.should_receive(:all).with(:select => '*, COUNT(*) as count', :group => 'group_id', :order => 'created_at DESC').and_return([@exception])
+
+      get :index
+      assigns[:exceptions].should == [@exception]
+    end
+  end
+
+  describe "#details" do
+    before(:each) do
+      @exception2 = <%= class_name %>.new
+      <%= class_name %>.stub!(:paginate).and_return([@exception, @exception2])
+    end
+
+    it 'should set an assigns of exceptions with a paginated collection' do
+      <%= class_name %>.should_receive(:paginate).with(:all, :conditions => { :group_id => '89hasd98ashdasas98dhsda' }, 
+                                                     :order => 'created_at DESC', :page => '1', :per_page => 1).and_return([@exception, @exception2])
+
+      get :details, :id => '89hasd98ashdasas98dhsda', :page => 1
+      assigns[:exceptions].should == [@exception, @exception2]
+    end
+
+    it 'should set an assigns of exception with the first exception from the paginated collection' do
+      get :details, :id => '89hasd98ashdasas98dhsda'
+      assigns[:exception].should == @exception
+    end
+  end
+  
+  describe "#remove_all" do
+    it 'should delete all exceptions' do
+      <%= class_name %>.should_receive(:delete_all)
+      get :remove_all
+    end
+
+    it 'should redirect to exceptions#index' do
+      get :remove_all
+      response.should redirect_to(:action => :index)
+    end
+  end
+
+  describe "#remove_group" do
+    it 'should delete all exceptions in a specific group' do
+      <%= class_name %>.should_receive(:delete_all).with(:group_id => '892h39fds')
+      get :remove_group, :id => '892h39fds'
+    end
+
+    it 'should redirect to exceptions#index' do
+      get :remove_group, :id => '892h39fds'
+      response.should redirect_to(:action => :index)
+    end
+  end
+
+  describe "#remove_individual" do
+    before(:each) do
+      <%= class_name %>.stub!(:find_by_id).and_return(@exception)
+    end
+
+    it 'should remove a single exception' do
+      @exception.should_receive(:destroy)
+      get :remove_individual, :id => 1      
+    end
+
+    it 'should redirect to exceptions#index if the exception group contains no more exceptions' do
+      <%= class_name %>.stub!(:count).and_return(0)
+      get :remove_individual, :id => 1
+      response.should redirect_to(:action => :index)
+    end
+
+    it 'should redirect to exceptions#details if the exception group contains more exceptions' do
+      <%= class_name %>.stub!(:count).and_return(1)
+      get :remove_individual, :id => 1
+      response.should redirect_to(:action => :details)
+    end
+  end
+end

data/generators/tartarus/templates/spec/models/logged_exception_spec.rb

@@ -0,0 +1,7 @@
+require File.dirname(__FILE__) + '/../spec_helper'
+
+describe <%= class_name %> do 
+  it "should include the Tartarus::Logger module" do
+    <%= class_name %>.included_modules.include?(Tartarus::Logger)
+  end
+end

data/lib/tartarus/logger.rb

@@ -0,0 +1,46 @@
+module Tartarus::Logger
+  def self.included(base)
+    base.extend ClassMethods
+    base.serialize :request
+  end
+
+  module ClassMethods
+    def log(controller, exception)
+      create do |logged_exception|
+        group_id = "#{exception.class.name}#{exception.message}#{controller.controller_path}#{controller.action_name}" 
+    
+        logged_exception.exception_class = exception.class.name
+        logged_exception.controller_path = controller.controller_path
+        logged_exception.action_name = controller.action_name
+        logged_exception.message = exception.message
+        logged_exception.backtrace = exception.backtrace * "\n"
+        logged_exception.request = normalize_request_data(controller.request)
+        logged_exception.group_id = Digest::SHA1.hexdigest(group_id)
+      end
+    end
+
+    def normalize_request_data(request)
+      request_details = {
+        :enviroment => {},
+        :http_details => { 
+          :method => request.method.to_s.upcase,
+          :url => "#{request.protocol}#{request.env["HTTP_HOST"]}#{request.request_uri}",
+          :format => request.format.to_s,
+          :parameters => request.parameters
+        },
+
+        :session => {
+          :variables => request.env['rack.session'],
+          :options => request.env['rack.session.options'],
+          :cookie => request.env['rack.request.cookie_hash']
+        }
+      }
+
+      request.env.each_pair do |key, value|
+        request_details[:enviroment][key.downcase] = value if key.match(/^[A-Z_]*$/)
+      end
+
+      return request_details
+    end
+  end
+end

data/lib/tartarus/rescue.rb

@@ -0,0 +1,15 @@
+module Tartarus::Rescue
+  def self.included(base)
+    base.class_eval do
+      alias_method_chain :rescue_action, :tartarus
+    end
+  end
+  
+  def rescue_action_with_tartarus(exception)
+    if response_code_for_rescue(exception) == :internal_server_error
+      Tartarus.log(self, exception)
+    end
+
+    rescue_action_without_tartarus(exception)
+  end
+end

data/lib/tartarus.rb

@@ -0,0 +1,22 @@
+require 'yaml'
+require 'will_paginate'
+
+class Tartarus
+  class << self
+    def configuration
+      @cached_config ||= YAML.load_file("#{Rails.root}/config/exceptions.yml")[Rails.env]
+    end
+
+    def logger_class
+      configuration['logger_class'].constantize
+    end
+
+    def log(controller, exception)
+      logger_class.log(controller, exception)
+    end
+  end
+
+end
+
+require 'tartarus/logger'
+require 'tartarus/rescue'

data/rails/init.rb

@@ -0,0 +1,3 @@
+require 'tartarus'
+
+ActionController::Base.send(:include, Tartarus::Rescue)

data/spec/rails/app/controllers/application_controller.rb

@@ -0,0 +1,10 @@
+# Filters added to this controller apply to all controllers in the application.
+# Likewise, all the methods added will be available for all controllers.
+
+class ApplicationController < ActionController::Base
+  helper :all # include all helpers, all the time
+  protect_from_forgery # See ActionController::RequestForgeryProtection for details
+
+  # Scrub sensitive parameters from your log
+  # filter_parameter_logging :password
+end

data/spec/rails/app/models/logged_exception.rb

@@ -0,0 +1,2 @@
+class LoggedException < ActiveRecord::Base
+end