radar 0.2.0 → 0.3.0

data/examples/README.md

@@ -0,0 +1,5 @@
+# Radar Examples
+
+This directory contains various examples of using Radar in various
+ways. Each subdirectory is an example with its own `README` file explaining
+the purpose and usage of the example.

data/examples/rack/README.md

@@ -0,0 +1,15 @@
+# Radar Examples: Rack
+
+This example shows Radar's Rack integration.
+
+## Usage
+
+First make sure you install the dependencies using Bundler, then just
+run `rackup` (`bundle exec` is used to verify that it uses the bundle
+environment to get the binary):
+
+    bundle install
+    bundle exec rackup
+
+Then access `localhost:9292`, which should throw an exception. Go back
+to your console and see that Radar caught and reported the exception!

data/examples/rack/config.ru

@@ -0,0 +1,18 @@
+require "rubygems"
+require "bundler/setup"
+require "radar"
+
+# Create a Radar::Application, configured to simply log to the
+# STDERR stream.
+app = Radar::Application.new(:rack_example) do |a|
+  a.config.reporters.use :io, :io_object => STDERR
+end
+
+# Use the Radar Rack middleware for the created application,
+# and make the Rack app just throw an exception so we can see it
+# working.
+use Rack::Radar, :application => app
+run lambda { |env|
+  raise "Uh oh, an error!"
+  [200, { "Content-Type" => "text/html" }, ["This shouldn't be reached."]]
+}

data/lib/radar.rb

@@ -1,23 +1,41 @@
 require 'radar/version'
 require 'radar/error'
+require 'radar/integration/rails3/railtie' if defined?(Rails::Railtie)
 
 module Radar
   autoload :Application,    'radar/application'
   autoload :Config,         'radar/config'
   autoload :ExceptionEvent, 'radar/exception_event'
+  autoload :Logger,         'radar/logger'
   autoload :Reporter,       'radar/reporter'
   autoload :Support,        'radar/support'
 
   module DataExtensions
     autoload :HostEnvironment, 'radar/data_extensions/host_environment'
+    autoload :Rack, 'radar/data_extensions/rack'
   end
 
-  class Reporter
-    autoload :FileReporter, 'radar/reporter/file_reporter'
+  module Filters
+    autoload :KeyFilter, 'radar/filters/key_filter'
+  end
+
+  module Integration
+    autoload :Rack,   'radar/integration/rack'
+    autoload :Rails3, 'radar/integration/rails3'
   end
 
   module Matchers
     autoload :BacktraceMatcher, 'radar/matchers/backtrace_matcher'
     autoload :ClassMatcher,     'radar/matchers/class_matcher'
   end
+
+  class Reporter
+    autoload :FileReporter,   'radar/reporter/file_reporter'
+    autoload :IoReporter,     'radar/reporter/io_reporter'
+    autoload :LoggerReporter, 'radar/reporter/logger_reporter'
+  end
+end
+
+module Rack
+  autoload :Radar, 'radar/integration/rack'
 end

data/lib/radar/application.rb

@@ -1,4 +1,5 @@
 require 'thread'
+require 'forwardable'
 
 module Radar
   # A shortcut for {Application.find}.
@@ -10,12 +11,16 @@ module Radar
   # Represents an instance of Radar for a given application. Every
   # application which uses Radar must instantiate an {Application}.
   class Application
+    extend Forwardable
+
     @@registered = {}
     @@mutex = Mutex.new
 
     attr_reader :name
     attr_reader :creation_location
 
+    def_delegators :config, :reporters, :data_extensions, :matchers, :filters
+
     # Looks up an application which was registered with the given name.
     #
     # @param [String] name Application name.
@@ -71,6 +76,16 @@ module Radar
       @_config
     end
 
+    # Returns the logger for the application. Each application gets
+    # their own logger which is used for lightweight (single line)
+    # logging so users can sanity check that Radar is working as
+    # expected.
+    #
+    # @return [Logger]
+    def logger
+      @_logger ||= Logger.new(self)
+    end
+
     # Reports an exception. This will send the exception on to the
     # various reporters configured for this application. If any
     # matchers are defined, using {Config#match}, then at least one
@@ -82,9 +97,14 @@ module Radar
 
       # If there are matchers, then verify that at least one matches
       # before continuing
-      return if !config.matchers.empty? && !config.matchers.values.find { |m| m.matches?(data) }
+      if !config.matchers.empty?
+        return if !config.matchers.values.find do |m|
+          m.matches?(data) && logger.info("Reporting exception. Matches: #{m}")
+        end
+      end
 
       # Report the exception to each of the reporters
+      logger.info "Invoking reporters for exception: #{exception.class}"
       config.reporters.values.each do |reporter|
         reporter.report(data)
       end
@@ -93,9 +113,18 @@ module Radar
     # Hooks this application into the `at_exit` handler so that
     # application crashing exceptions are properly reported.
     def rescue_at_exit!
+      logger.info "Attached to application exit."
       at_exit { report($!) if $! }
     end
 
+    # Integrate this application with some external system, such as
+    # Rack, Rails, Sinatra, etc. For more information on Radar integrations,
+    # please read the user guide.
+    def integrate(integrator, *args, &block)
+      integrator = Support::Inflector.constantize("Radar::Integration::#{Support::Inflector.camelize(integrator)}") if !integrator.is_a?(Class)
+      integrator.integrate!(self, *args, &block)
+    end
+
     # Converts application to a serialization-friendly hash.
     #
     # @return [Hash]

data/lib/radar/config.rb

@@ -7,21 +7,17 @@ module Radar
     attr_reader :reporters
     attr_reader :data_extensions
     attr_reader :matchers
+    attr_reader :filters
+    attr_accessor :log_location
 
     def initialize
-      @reporters = UseArray.new do |klass, &block|
-        instance = klass.new
-        block.call(instance) if block
-        [klass, instance]
-      end
+      @reporters       = UseArray.new(&method(:add_reporter))
+      @data_extensions = UseArray.new(&method(:add_data_extension))
+      @matchers        = UseArray.new(&method(:add_matcher))
+      @filters         = UseArray.new(&method(:add_filter))
+      @log_location    = nil
 
-      @data_extensions = UseArray.new
       @data_extensions.use DataExtensions::HostEnvironment
-
-      @matchers = UseArray.new do |matcher, *args|
-        matcher = Support::Inflector.constantize("Radar::Matchers::" + Support::Inflector.camelize(matcher)) if !matcher.is_a?(Class)
-        [matcher, matcher.new(*args)]
-      end
     end
 
     # Adds a matcher rule to the application. An application will only
@@ -45,6 +41,51 @@ module Radar
     def match(matcher, *args)
       @matchers.use(matcher, *args)
     end
+
+    protected
+
+    # The callback that is used to add a reporter to the {UseArray}
+    # when `reporters.use` is called.
+    def add_reporter(klass, *args)
+      klass = Support::Inflector.constantize("Radar::Reporter::#{Support::Inflector.camelize(klass)}Reporter") if !klass.is_a?(Class)
+
+      block = args.pop if args.last.is_a?(Proc)
+      instance = klass.new(*args)
+      block.call(instance) if block
+
+      [klass, instance]
+    end
+
+    # The callback that is used to add a data extension to the {UseArray}
+    # when `data_extensions.use` is called.
+    def add_data_extension(ext, *args)
+      ext = Support::Inflector.constantize("Radar::DataExtensions::#{Support::Inflector.camelize(ext)}") if !ext.is_a?(Class)
+      [ext, ext]
+    end
+
+    # The callback that is used to add a matcher to the {UseArray}
+    # when `matchers.use` is called.
+    def add_matcher(matcher, *args)
+      matcher = Support::Inflector.constantize("Radar::Matchers::#{Support::Inflector.camelize(matcher)}Matcher") if !matcher.is_a?(Class)
+      [matcher, matcher.new(*args)]
+    end
+
+    # The callback that is used to add a filter to the {UseArray}
+    # when `filters.use` is called.
+    def add_filter(*args)
+      block = args.pop if args.last.is_a?(Proc)
+      raise ArgumentError.new("`filters.use` requires at least a class or a lambda to be given.") if args.empty? && !block
+
+      if !args.empty?
+        # Detect the proper class then get the `filter` method from it,
+        # since that is all we care about
+        klass = args.shift
+        klass = Support::Inflector.constantize("Radar::Filters::#{Support::Inflector.camelize(klass)}Filter") if !klass.is_a?(Class)
+        block = klass.new.method(:filter)
+      end
+
+      [block, block]
+    end
   end
 
   class Config
@@ -80,7 +121,8 @@ module Radar
       # Insert the given key at the given index or directly before the
       # given object (by key).
       def insert(key, *args, &block)
-        @_array.insert(index(key), @_use_block.call(*args, &block))
+        args.push(block) if block
+        @_array.insert(index(key), @_use_block.call(*args))
       end
       alias_method :insert_before, :insert
 

data/lib/radar/data_extensions/rack.rb

@@ -0,0 +1,72 @@
+module Radar
+  module DataExtensions
+    # Data extensions which adds information about a rack request,
+    # if it exists in the `:rack_request` extra data of the {ExceptionEvent}.
+    class Rack
+      def initialize(event)
+        @event = event
+      end
+
+      def to_hash
+        result = {}
+
+        request = @event.extra[:rack_request]
+        if request
+          Support::Hash.deep_merge!(result, { :request => {
+              :request_method => request.request_method.to_s,
+              :url        => request.url.to_s,
+              :parameters => request.params,
+              :remote_ip  => request.ip
+            }
+          })
+        end
+
+        if @event.extra[:rack_env]
+          Support::Hash.deep_merge!(result, :request => { :headers => extract_http_headers(@event.extra[:rack_env]) })
+          Support::Hash.deep_merge!(result, :request => { :rack_env => extract_rack_env(@event.extra[:rack_env]) })
+        end
+
+        result
+      end
+
+      protected
+
+      # Extracts only the HTTP headers from the rack environment,
+      # converting them to the proper HTTP format: `HTTP_CONTENT_TYPE`
+      # to `Content-Type`
+      #
+      # @param [Hash] env
+      # @return [Hash]
+      def extract_http_headers(env)
+        env.inject({}) do |acc, data|
+          k, v = data
+
+          if k =~ /^HTTP_(.+)$/
+            # Convert things like HTTP_CONTENT_TYPE to Content-Type (standard
+            # HTTP header style)
+            k = $1.to_s.split("_").map { |c| c.capitalize }.join("-")
+            acc[k] = v
+          end
+
+          acc
+        end
+      end
+
+      # Extracts the rack environment, ignoring HTTP headers and
+      # converting the values to strings if they're not an Array
+      # or Hash.
+      def extract_rack_env(env)
+        env.inject({}) do |acc, data|
+          k, v = data
+
+          if !(k =~ /^HTTP_/)
+            v = v.to_s if !v.is_a?(Array) && !v.is_a?(Hash) && !v.is_a?(Integer)
+            acc[k] = v
+          end
+
+          acc
+        end
+      end
+    end
+  end
+end

data/lib/radar/error.rb

@@ -3,4 +3,5 @@ module Radar
   # for users of radar to catch all radar related errors.
   class Error < StandardError; end
   class ApplicationAlreadyExists < Error; end
+  class ReporterError < Error; end
 end

data/lib/radar/exception_event.rb

@@ -35,10 +35,12 @@ module Radar
         :occurred_at => occurred_at.to_i
       }
 
-      if !application.config.data_extensions.empty?
-        application.config.data_extensions.values.each do |extension|
-          Support::Hash.deep_merge!(result, extension.new(self).to_hash)
-        end
+      application.config.data_extensions.values.each do |extension|
+        Support::Hash.deep_merge!(result, extension.new(self).to_hash || {})
+      end
+
+      application.config.filters.values.each do |filter|
+        result = filter.call(result)
       end
 
       result

data/lib/radar/filters/key_filter.rb

@@ -0,0 +1,54 @@
+module Radar
+  module Filters
+    # Filters the event data by filtering out a given key which
+    # can exist anywhere in the data hash. For example, given
+    # the following hash:
+    #
+    #     { :request  => { :password => "foo" },
+    #       :rack_env => { :params => { :password => "foo" } } }
+    #
+    # If the KeyFilter was configured like so:
+    #
+    #     app.filters.use :key, :key => :password
+    #
+    # Then the data hash would turn into:
+    #
+    #     { :request  => { :password => "[FILTERED]" },
+    #       :rack_env => { :params => { :password => "[FILTERED]" } } }
+    #
+    # ## Options
+    #
+    # * `:key` - A single element or array of elements which represent the
+    #   keys to filter out of the event hash.
+    # * `:filter_text` - The text which replaces keys which are caught by the
+    #   filter. This defaults to "[FILTERED]"
+    #
+    class KeyFilter
+      attr_accessor :key
+      attr_accessor :filter_text
+
+      def initialize(opts=nil)
+        (opts || {}).each do |k,v|
+          send("#{k}=", v)
+        end
+
+        @filter_text ||= "[FILTERED]"
+      end
+
+      def filter(data)
+        # Convert the keys to strings, since we always compare against strings
+        filter_keys = [key].flatten.collect { |k| k.to_s }
+
+        data.each do |k,v|
+          if filter_keys.include?(k.to_s)
+            data[k] = filter_text
+          elsif v.is_a?(Hash)
+            filter(v)
+          end
+        end
+
+        data
+      end
+    end
+  end
+end

data/lib/radar/integration/rack.rb

@@ -0,0 +1,41 @@
+module Radar
+  module Integration
+    # Allows drop-in integration with Rack for Radar. This class
+    # should not ever actually be used with {Application#integrate}.
+    # Instead, use the middleware provided by {Rack::Radar}, passing
+    # in your application like so:
+    #
+    #     use Rack::Radar, :application => radar_app
+    #
+    class Rack
+      def self.integrate!(app)
+        raise "To enable Rack integration, please do: `use Rack::Radar, :application => app` instead."
+      end
+    end
+  end
+end
+
+module Rack
+  # A rack middleware which allows Radar to catch any exceptions
+  # thrown down a Rack app and report it to the given Radar application.
+  #
+  #     use Rack::Radar, :application => radar_app
+  #
+  class Radar
+    def initialize(app, opts=nil)
+      @app = app
+      @opts = { :application => nil }.merge(opts || {})
+      raise ArgumentError.new("Must provide a radar application in `:application`") if !@opts[:application] || !@opts[:application].is_a?(::Radar::Application)
+
+      # Enable the rack data extension
+      @opts[:application].config.data_extensions.use :rack
+    end
+
+    def call(env)
+      @app.call(env)
+    rescue Exception => e
+      @opts[:application].report(e, :rack_request => Rack::Request.new(env), :rack_env => env)
+      raise
+    end
+  end
+end

data/lib/radar/integration/rails3.rb

@@ -0,0 +1,19 @@
+require "rails"
+
+module Radar
+  module Integration
+    # Allows drop-in integration with Rails 3 for Radar. This
+    # basically enables a middleware in your Rails 3 application
+    # which catches any exceptions and adds some additional
+    # information to the exception (such as the rack environment,
+    # request URL, etc.)
+    class Rails3
+      def self.integrate!(app)
+        raise ArgumentError.new("Rails integration requires a Rails application to be defined.") if !Rails.application
+
+        # For now just use the Rack::Radar
+        Rails.application.config.middleware.use "Rack::Radar", :application => app
+      end
+    end
+  end
+end