effective_logging 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 6ffec40703187b420ab31ea83ccb1c7d54f480c5
+  data.tar.gz: 1d61908e31c154fb6b61250f6b9ca8a521eae13f
+SHA512:
+  metadata.gz: 9dcf971011fb02748255f89d58f5c534bbe7a5b8c694e39077589db39775efc4f41ee57a74b6590cefda73dcba32fb1b7453adfc5afdcbd420338ff1ea47b316
+  data.tar.gz: 29e2c73f69b919bb725ea5a15727dd8667017f66754e5b208ae77cbd0a4d9f3179226ad0ab8fdbfb233533a6a7c02d05f1a030649ff5243fa27d94cd6435ed6e

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2014 Code and Effect Inc.
+
+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/README.md

@@ -0,0 +1,280 @@
+# Effective Logging
+
+Automatically log all sent emails, user logins, and page views. This also will log custom events from Ruby and JavaScript.
+
+A Rails3 / Rails4 engine to completely handle logging of events.
+
+Logs are stored in a single database table. A Log (one logged event) can have many children Logs, nested to any depth.
+
+Provides a ruby one-liner to log a message, status, user, associated object and any number of additional details.
+
+Works great for single fire-and-forget events and long running tasks.
+
+Provides a simple Javascript API for logging front-end events.
+
+Automatically logs any email sent by the application, any successful user login via Devise, and all page views.
+
+Has an effective_datatables driven admin interface to display and search/sort/filter all logs.
+
+
+## Getting Started
+
+Add to your Gemfile:
+
+```ruby
+gem 'effective_logging'
+```
+
+Run the bundle command to install it:
+
+```console
+bundle install
+```
+
+Then run the generator:
+
+```ruby
+rails generate effective_logging:install
+```
+
+The generator will install an initializer which describes all configuration options and creates a database migration.
+
+If you want to tweak the table name (to use something other than the default 'logs'), manually adjust both the configuration file and the migration now.
+
+Then migrate the database:
+
+```ruby
+rake db:migrate
+```
+
+## Usage
+
+### Basic
+
+Log an event from anywhere in the application:
+
+```ruby
+EffectiveLogger.info 'something happened'
+```
+
+Each status, as per the config/initializers/effective_logging.rb initializer, will be created as a class level method:
+
+```ruby
+EffectiveLogger.info 'something happened'
+EffectiveLogger.success 'it worked!'
+EffectiveLogger.error 'now we are in trouble'
+```
+
+The :user and :associated options may be passed to indicate the user and associated (ActiveRecord) object which belong to this event:
+
+```ruby
+EffectiveLogger.info 'product purchased', :user => current_user, :associated => @product
+```
+
+Any other passed options will be serialized and stored as additional details:
+
+```ruby
+EffectiveLogger.info 'feedback given', :user => current_user, :feedback => 'your app is great!', :rating => 'good'
+```
+
+### Sub Logs
+
+Any log can have children logs.  This is perfect for long-running tasks where there are multiple sub events:
+
+```ruby
+log = EffectiveLogger.info('importing important records')
+
+log.success('record 1 imported', :associated => @record1)
+log.error('record 2 failed to import', :associated => @record2)
+log.success('record 3 imported', :associated => @record3)
+```
+
+
+### Automatic Logging of E-mails
+
+Any email sent by the application will be automatically logged.
+
+This behaviour can be disabled in the config/initializers/effective_logging.rb initializer.
+
+If the TO email address match a User, the :user will be set appropriately.
+
+
+### Automatic Logging of User Logins
+
+Any successful User logins via Devise will be automatically logged.
+
+This behaviour can be disabled in the config/initializers/effective_logging.rb initializer.
+
+The User's IP address will also be logged.
+
+
+### Logging Page Views
+
+All page views, whether initiated by a logged in user or not, may be logged.
+
+To enable application wide logging for every request, add the following to your ApplicationController:
+
+```ruby
+class ApplicationController < ActionController::Base
+  log_page_views
+end
+```
+
+The above command sets an after_filter to log every request. This is probably too much.  Try instead:
+
+```ruby
+class ApplicationController < ActionController::Base
+  log_page_views :except => [:new, :create, :edit, :update, :destroy], :skip_namespace => [Admin, Devise], :details => false
+end
+```
+
+The above command will log all requests to index, show and non-RESTful controller actions which are not from controllers in the Admin or Devise namespaces.
+
+Page views always log the current_user when present.
+
+By default, the request.params, request.format, request.referrer and request.user_agent information is also logged, unless :details => false is set.
+
+
+Instead of logging all requests as per the ApplicationController, it may be easier to selectively log page views on just one or more controllers:
+
+```ruby
+class ProductsController < ApplicationController
+  log_page_views
+end
+```
+
+However, if log_page_views is set by the ApplicationController, you can still opt out of logging specific actions in two different ways:
+
+```ruby
+class ApplicationController < ActionController::Base
+  log_page_views
+end
+
+class ProductsController < ApplicationController
+  skip_log_page_views :only => [:show]   # Skip logging with a before_filter
+
+  def index
+    @products = Product.all
+
+    skip_log_page_view if current_user.admin?    # Skip logging with a method
+  end
+end
+```
+
+The above command will skip logging of the :show action and will skip logging of the :index action if the current_user is an admin.
+
+log_page_views accepts any options that an after_filter would accept and has access to the request object
+
+```ruby
+class ProductsController < ApplicationController
+  log_page_views :if => Proc.new { request.get? }  # Only log GET requests
+end
+```
+
+Similarly, skip_log_page_views also accepts any options that a before_filter would accept.
+
+
+### Logging From JavaScript
+
+First, require the javascript in your application.js:
+
+```ruby
+//= require effective_logging
+```
+
+then logging an event from JavaScript is almost the same one-liner as from ruby:
+
+```javascript
+EffectiveLogger.success('clicked start on a video');
+```
+
+the above command sends an AJAX request that creates the Log.  If the current_user is present :user will be automatically set.
+
+The syntax to attach (any number of) additional information fields is very forgiving:
+
+```javascript
+EffectiveLogger.info('clicked start on a video', {video_title: 'cool video', video_time: '5:00'});
+```
+
+and
+
+```javascript
+EffectiveLogger.success('some other event', 'additional', 'information', {subject: 'my subject', from: 'someone'}, 'and more');
+```
+
+The same statuses available to ruby will be available to JavaScript.
+
+Creating child logs via JavaScript is not yet supported.
+
+
+## Admin Screen
+
+To use the Admin screen, please also install the [effective_datatables](https://github.com/code-and-effect/effective_datatables/) gem:
+
+```ruby
+gem 'effective_datatables'
+```
+
+Then you should be able to visit:
+
+```ruby
+link_to 'Logs', effective_logging.admin_logs_path   # /admin/logs
+```
+
+### Build an All Logs Screen
+
+If you don't want to use the builtin Admin screen, and would rather render the effective_datatable of logs elsewhere
+
+In your controller:
+
+```ruby
+@datatable = Effective::Datatables::Logs.new()
+```
+
+And then in your view:
+
+```ruby
+render_datatable(@datatable)
+```
+
+### Build a User Specific Logs Screen
+
+We can also use a similar method to create a datatable of logs for just one user.
+
+When initialized with :user_id, the 'User' column is hidden and the Logs are scoped to the User.
+
+In your controller:
+
+```ruby
+@user = User.find(params[:id])
+@datatable = Effective::Datatables::Logs.new(:user_id => @user.id)
+```
+
+
+## License
+
+MIT License.  Copyright [Code and Effect Inc.](http://www.codeandeffect.com/)
+
+Code and Effect is the product arm of [AgileStyle](http://www.agilestyle.com/), an Edmonton-based shop that specializes in building custom web applications with Ruby on Rails.
+
+
+## Testing
+
+The test suite for this gem is unfortunately not yet complete.
+
+Run tests by:
+
+```ruby
+rake spec
+```
+
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Bonus points for test coverage
+6. Create new Pull Request
+

data/Rakefile

@@ -0,0 +1,20 @@
+#!/usr/bin/env rake
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+# Testing tasks
+APP_RAKEFILE = File.expand_path("../spec/dummy/Rakefile", __FILE__)
+load 'rails/tasks/engine.rake'
+
+Bundler::GemHelper.install_tasks
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+
+desc "Run all specs in spec directory (excluding plugin specs)"
+RSpec::Core::RakeTask.new(:spec => 'app:db:test:prepare')
+
+task :default => :spec

data/app/assets/javascripts/effective_logging.js

@@ -0,0 +1 @@
+//= require_tree ./effective_logging

data/app/assets/javascripts/effective_logging/effective_logger.js.coffee.erb

@@ -0,0 +1,15 @@
+class @EffectiveLogger
+  @log = (message, status = 'info', details...) ->
+    $.ajax
+      type: 'POST',
+      url: '/logs.json'
+      data:
+        effective_log:
+          message: message
+          status: status
+          details: JSON.stringify(details)
+    true
+
+<% EffectiveLogging.statuses.each do |status| %>
+  <%= "@#{status} = (message, details...) -> @log(message, '#{status}', details)" %>
+<% end %>

data/app/controllers/admin/logs_controller.rb

@@ -0,0 +1,31 @@
+module Admin
+  class LogsController < ApplicationController
+    before_filter :authenticate_user!   # This is devise, ensure we're logged in.
+
+    layout (EffectiveLogging.layout.kind_of?(Hash) ? EffectiveLogging.layout[:admin_logs] : EffectiveLogging.layout)
+
+    skip_log_page_views :quiet => true
+    helper EffectiveLoggingHelper
+
+    def index
+      @datatable = Effective::Datatables::Logs.new() if defined?(EffectiveDatatables)
+      @page_title = 'Logs'
+
+      EffectiveLogging.authorized?(self, :index, Effective::Log)
+    end
+
+    def show
+      @log = Effective::Log.includes(:logs).find(params[:id])
+      @log.next_log = Effective::Log.unscoped.order(:id).where(:parent_id => @log.parent_id).where('id > ?', @log.id).first
+      @log.prev_log = Effective::Log.unscoped.order(:id).where(:parent_id => @log.parent_id).where('id < ?', @log.id).last
+
+      @page_title = "Log ##{@log.to_param}"
+
+      if @log.logs.present?
+        @log.datatable = Effective::Datatables::Logs.new(:log_id => @log.id) if defined?(EffectiveDatatables)
+      end
+
+      EffectiveLogging.authorized?(self, :show, @log)
+    end
+  end
+end

data/app/controllers/effective/logs_controller.rb

@@ -0,0 +1,71 @@
+module Effective
+  class LogsController < ApplicationController
+    skip_log_page_views
+    before_filter :authenticate_user!, :only => [:index, :show] # Devise ensure logged in
+
+    # This is a post from our Javascript
+    def create
+      EffectiveLogging.authorized?(self, :create, Effective::Log.new())
+
+      @log = Effective::Log.new().tap do |log|
+        log.message = log_params[:message]
+        log.status = (EffectiveLogging.statuses.include?(log_params[:status]) ? log_params[:status] : 'info')
+        log.user = (current_user rescue nil)
+
+        #log.parent = options.delete(:parent)
+        #log.associated = options.delete(:associated)
+
+        count = -1
+        Array((JSON.parse(log_params[:details]) rescue [])).flatten(1).each do |obj|
+          if obj.kind_of?(Hash)
+            obj.each { |k, v| log.details[k] = v if v.present? }
+          else
+            log.details["param_#{(count += 1)}"] = obj if obj.present?
+          end
+        end
+
+        log.details[:referrer] = request.referrer
+
+        log.save
+      end
+
+      render :text => "ok", :status => :ok
+    end
+
+    # This is the User index event
+    def index
+      @datatable = Effective::Datatables::Logs.new(:user_id => current_user.id) if defined?(EffectiveDatatables)
+      @page_title = 'My Activity'
+
+      EffectiveLogging.authorized?(self, :index, Effective::Log.new(:user_id => current_user.id))
+    end
+
+    # This is the User show event
+    def show
+      @log = Effective::Log.where(:user_id => current_user.id).includes(:logs).find(params[:id])
+      @log.next_log = Effective::Log.unscoped.where(:user_id => current_user.id).order(:id).where(:parent_id => @log.parent_id).where('id > ?', @log.id).first
+      @log.prev_log = Effective::Log.unscoped.where(:user_id => current_user.id).order(:id).where(:parent_id => @log.parent_id).where('id < ?', @log.id).last
+
+      @page_title = "Log ##{@log.to_param}"
+
+      if @log.logs.present?
+        @log.datatable = Effective::Datatables::Logs.new(:user_id => current_user.id, :log_id => @log.id) if defined?(EffectiveDatatables)
+      end
+
+      EffectiveLogging.authorized?(self, :show, @log)
+    end
+
+
+    private
+
+    # StrongParameters
+    def log_params
+      begin
+        params.require(:effective_log).permit(:message, :status, :details)
+      rescue => e
+        params[:effective_log] || {}
+      end
+    end
+
+  end
+end