radar 0.3.0 → 0.4.0

data/.gitignore

@@ -3,4 +3,5 @@ pkg/*
 .bundle/*
 doc/*
 .yardoc/*
-test.rb
+test.rb
+_site/*

data/CHANGELOG.md

@@ -1,3 +1,24 @@
+## 0.4.0 (October 5, 2010)
+
+  - Added a `LocalRequestMatcher` to detect local requests for web
+    applications. [GH-27]
+  - Added rejecters, which are the opposite as matchers. If any rejecter
+    matches, then the error is not reported.
+  - You can now enable reporters, data extensions, etc using the singular
+    version: `app.reporter`, `app.data_extension`, etc. [GH-25]
+  - Rails 2 integration added.
+  - Sinatra integration documented.
+  - Reporters can now take just a block which takes a single parameter
+    `event`.
+  - Matchers can now take just a block which takes a single parameter `event`. [GH-24]
+  - Added a `Hoptoad` reporter! Radar is now a drop-in replacement for
+    Hoptoad. [GH-21]
+  - Fixed issue with `LoggerReporter` not being able to use the Rails
+    logger.
+  - The backtrace in an `ExceptionEvent` is now a `Backtrace` object,
+    which is a subclass of Array. This is because backtraces are now
+    parsed to extract the file, line, and method of each entry.
+
 ## 0.3.0 (August 21, 2010)
 
   - Added `KeyFilter` to filter out specific keys in the data hash.

data/Gemfile

@@ -7,11 +7,12 @@ gemspec :path => File.expand_path("../", __FILE__)
 # Additional gems which I don't really want in the gemspec but
 # are useful for development
 group :development do
-  gem "yard", :git => "http://github.com/lsegal/yard.git", :ref => "bf84275"
+  gem "yard", "~> 0.6.1"
   gem "bluecloth"
 end
 
 group :examples do
   gem "rack"
-  gem "rails"
+  gem "rails", "~> 3.0.0"
+  gem "sinatra", "~> 1.0.0"
 end

data/Gemfile.lock

@@ -1,55 +1,49 @@
-GIT
-  remote: http://github.com/lsegal/yard.git
-  revision: bf84275
-  ref: bf84275
-  specs:
-    yard (0.6.0.rc1)
-
 PATH
   remote: .
   specs:
-    radar (0.3.0)
+    radar (0.4.0)
+      builder (~> 2.0)
       json (>= 1.4.6)
 
 GEM
   remote: http://rubygems.org/
   specs:
     abstract (1.0.0)
-    actionmailer (3.0.0.rc)
-      actionpack (= 3.0.0.rc)
+    actionmailer (3.0.0)
+      actionpack (= 3.0.0)
       mail (~> 2.2.5)
-    actionpack (3.0.0.rc)
-      activemodel (= 3.0.0.rc)
-      activesupport (= 3.0.0.rc)
+    actionpack (3.0.0)
+      activemodel (= 3.0.0)
+      activesupport (= 3.0.0)
       builder (~> 2.1.2)
       erubis (~> 2.6.6)
       i18n (~> 0.4.1)
       rack (~> 1.2.1)
-      rack-mount (~> 0.6.9)
+      rack-mount (~> 0.6.12)
       rack-test (~> 0.5.4)
-      tzinfo (~> 0.3.22)
-    activemodel (3.0.0.rc)
-      activesupport (= 3.0.0.rc)
+      tzinfo (~> 0.3.23)
+    activemodel (3.0.0)
+      activesupport (= 3.0.0)
       builder (~> 2.1.2)
       i18n (~> 0.4.1)
-    activerecord (3.0.0.rc)
-      activemodel (= 3.0.0.rc)
-      activesupport (= 3.0.0.rc)
-      arel (~> 0.4.0)
-      tzinfo (~> 0.3.22)
-    activeresource (3.0.0.rc)
-      activemodel (= 3.0.0.rc)
-      activesupport (= 3.0.0.rc)
-    activesupport (3.0.0.rc)
-    arel (0.4.0)
-      activesupport (>= 3.0.0.beta)
-    bluecloth (2.0.7)
+    activerecord (3.0.0)
+      activemodel (= 3.0.0)
+      activesupport (= 3.0.0)
+      arel (~> 1.0.0)
+      tzinfo (~> 0.3.23)
+    activeresource (3.0.0)
+      activemodel (= 3.0.0)
+      activesupport (= 3.0.0)
+    activesupport (3.0.0)
+    arel (1.0.1)
+      activesupport (~> 3.0.0)
+    bluecloth (2.0.9)
     builder (2.1.2)
     erubis (2.6.6)
       abstract (>= 1.0.0)
     i18n (0.4.1)
     json (1.4.6)
-    mail (2.2.5)
+    mail (2.2.6.1)
       activesupport (>= 2.3.6)
       mime-types
       treetop (>= 1.4.5)
@@ -58,41 +52,46 @@ GEM
       rake
     polyglot (0.3.1)
     rack (1.2.1)
-    rack-mount (0.6.9)
+    rack-mount (0.6.13)
       rack (>= 1.0.0)
-    rack-test (0.5.4)
+    rack-test (0.5.6)
       rack (>= 1.0)
-    rails (3.0.0.rc)
-      actionmailer (= 3.0.0.rc)
-      actionpack (= 3.0.0.rc)
-      activerecord (= 3.0.0.rc)
-      activeresource (= 3.0.0.rc)
-      activesupport (= 3.0.0.rc)
-      bundler (>= 1.0.0.rc.1)
-      railties (= 3.0.0.rc)
-    railties (3.0.0.rc)
-      actionpack (= 3.0.0.rc)
-      activesupport (= 3.0.0.rc)
-      rake (>= 0.8.3)
+    rails (3.0.0)
+      actionmailer (= 3.0.0)
+      actionpack (= 3.0.0)
+      activerecord (= 3.0.0)
+      activeresource (= 3.0.0)
+      activesupport (= 3.0.0)
+      bundler (~> 1.0.0)
+      railties (= 3.0.0)
+    railties (3.0.0)
+      actionpack (= 3.0.0)
+      activesupport (= 3.0.0)
+      rake (>= 0.8.4)
       thor (~> 0.14.0)
     rake (0.8.7)
     shoulda (2.11.3)
-    thor (0.14.0)
+    sinatra (1.0)
+      rack (>= 1.0)
+    thor (0.14.3)
     treetop (1.4.8)
       polyglot (>= 0.3.1)
-    tzinfo (0.3.22)
+    tzinfo (0.3.23)
+    yard (0.6.1)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
   bluecloth
+  builder (~> 2.0)
   bundler (>= 1.0.0.rc.5)
   json (>= 1.4.6)
   mocha
   rack
   radar!
-  rails
+  rails (~> 3.0.0)
   rake
   shoulda
-  yard!
+  sinatra (~> 1.0.0)
+  yard (~> 0.6.1)

data/README.md

@@ -2,34 +2,23 @@
 
 * Source: [http://github.com/mitchellh/radar](http://github.com/mitchellh/radar)
 * IRC: `#vagrant` on Freenode
-* User Guide: [http://mitchellh.github.com/radar/file.user_guide.html](http://mitchellh.github.com/radar/file.user_guide.html)
-* Documentation: [http://mitchellh.github.com/radar](http://mitchellh.github.com/radar)
-
-Radar is a tool which provides a drop-in solution to catching and reporting
-errors in your Ruby applications in customizable ways.
-
-Radar is not a typical exception notifier such as Hoptoad and Exceptional
-since the former are built with Rails apps in mind, logging to a central
-server. Instead, Radar was initially built for [Vagrant](http://vagrantup.com),
-a command line tool. And instead of solely logging to a central server,
-Radar supports logging in configurable ways (to a file, to a server, to
-a growl notification, etc.)
-
-Radar was built out of the need for an easy automated solution to catching
-exceptions and gathering information, since I noticed that every time a stack
-trace was outputted for [Vagrant](http://vagrantup.com), I was asking the
-user all the same questions which could've easily have been gathered automatically.
-Now, Vagrant users can simply send me the radar output and I don't have to
-ask for any more information 90% of the time.
+* User Guide: [http://radargem.com/doc/file.user_guide.html](http://radargem.com/doc/file.user_guide.html)
+* Website: [http://radargem.com](http://radargem.com)
+
+Radar is an ultra-configurable exception reporting library for Ruby which
+lets you report errors in your applications any way you want. Read about
+the [rationale behind Radar](http://radargem.com/rationale.html).
 
 ## Brief Feature Breakdown
 
   - Reporters allow Radar to report anywhere: a file, a server, email, etc.
-  - Data extensions to add additional contextual data to exceptions
-  - Matchers to filter exceptions which Radar reports
+  - Data extensions enable you to add additional contextual data to exceptions
+  - Matchers are able to filter which exceptions are reported
+  - Filters remove sensitive data from exceptions
   - Run multiple Radar "applications" side-by-side to catch and report
-    different exceptions to different places
-  - Integration with 3rd party software: Rack, Rails 3.
+    different exceptions to different places.
+  - Integration with 3rd party software: Rack, Rails 2, Rails 3, and Sinatra.
+  - Drop-in replacement and integration with [Hoptoad](http://hoptoadapp.com)
 
 ## Quick Start
 
@@ -38,7 +27,7 @@ ask for any more information 90% of the time.
 Then just begin logging exceptions in your application:
 
     r = Radar::Application.new(:my_application)
-    r.reporters.use :file
+    r.reporter :file
     r.report(exception)
 
 You can also tell Radar to attach itself to Ruby's `at_exit` hook
@@ -87,7 +76,7 @@ look it up later anywhere in your application:
 ## Documentation and User Guide
 
 For more details on configuring Radar, please view the
-[user guide](http://mitchellh.github.com/radar/file.user_guide.html), which
+[user guide](http://radargem.com/doc/file.user_guide.html), which
 is a detailed overview of Radar and all of its features.
 
 ## Reporting Bugs and Requesting Features

data/docs/user_guide.md

@@ -11,7 +11,7 @@ breakdown of Radar:
   - Matchers to filter exceptions which Radar reports
   - Run multiple Radar "applications" side-by-side to catch and report
     different exceptions to different places
-  - Integration with 3rd party software: Rack, Rails 3.
+  - Integration with frameworks: Rack, Rails 2, Rails 3, and Sinatra.
 
 ## Installation
 
@@ -40,7 +40,7 @@ remote server, etc.). Radar comes with some built-in reporters. Below, we config
 the application to log errors to a file (by default at `~/.radar/errors/my_application`):
 
     Radar::Application.new(:my_application) do |app|
-      app.reporters.use :file
+      app.reporter :file
     end
 
 ### Reporting Errors
@@ -69,6 +69,14 @@ Now, whenever your application is about to crash (an exception not caught by
 a `rescue`), Radar will catch your exception and report it just prior to
 crashing.
 
+### Framework Integration
+
+Radar provides framework integration out of the box for Rack, Rails 2, Rails 3, and
+Sinatra. These all require little or no extra configuration to your Radar
+applications.
+
+For more information on framework integration, see the [framework integration section](#__toc__section33).
+
 ## Terminology
 
 Although you've already seen a basic example, I think its a good idea to
@@ -108,14 +116,14 @@ of what this means with a few examples:
 Reporters are enabled using the appilication configuration:
 
     Radar::Application.new(:my_application) do |app|
-      app.reporters.use :file
+      app.reporter :file
     end
 
 And can be configured by passing a block to the reporter, which is yielded with
 the instance of that reporter:
 
     Radar::Application.new(:my_application) do |app|
-      app.reporters.use :file do |reporter|
+      app.reporter :file do |reporter|
         reporter.output_directory = "~/.radar/exceptions"
       end
     end
@@ -124,8 +132,8 @@ Radar also allows multiple reporters to be used, which are then called
 in the order they are defined when an exception occurs:
 
     Radar::Application.new(:my_application) do |app|
-      app.reporters.use FileReporter
-      app.reporters.use AnotherReporter
+      app.reporter FileReporter
+      app.reporter AnotherReporter
     end
 
 As you can see from the above examples, a reporter takes both a symbol
@@ -147,7 +155,7 @@ where `timestamp` is the time that the exception occurred and `uniquehash` is th
 The directory where these files will be stored is configurable:
 
     Radar::Application.new(:my_application) do |app|
-      app.reporters.use :file do |reporter|
+      app.reporter :file do |reporter|
         reporter.output_directory = "~/my_application_errors"
       end
     end
@@ -174,7 +182,7 @@ page.
 any IO object (`stdout`, `stderr`, a net stream, etc.).
 
     Radar::Application.new(:my_application) do |app|
-      app.reporters.use :io, :io_object => STDOUT
+      app.reporter :io, :io_object => STDOUT
     end
 
 #### LoggerReporter
@@ -185,17 +193,44 @@ existing logging system, or if you simply want a backup for your exceptions (e.g
 report to both a server and a logger).
 
     Radar::Application.new(:my_application) do |app|
-      app.reporters.use :logger, :log_object => Logger.new(STDOUT), :log_level => :error
+      app.reporter :logger, :log_object => Logger.new(STDOUT), :log_level => :error
     end
 
 `log_level` will default to `:error` if not specified.
 
+#### HoptoadReporter
+
+{Radar::Reporter::HoptoadReporter HoptoadReporter} sends an exception event to
+the [Hoptoad service](http://hoptoadapp.com). If Radar is integrated with a Rack
+or Rails application, then the reporter will automatically add request information
+to the Hoptoad notice as well.
+
+    Radar::Application.new(:my_application) do |app|
+      app.reporter :hoptoad, :api_key => "your_key_here"
+    end
+
+There are many other options which can be set, though `api_key` is the only required
+one. See the class docs for more information.
+
+**Note:** Due to a limitation of the Hoptoad service, only a very specific
+set of data can be sent to the service. Therefore, your data extension information
+likely won't be sent to Hoptoad.
+
 ### Custom Reporters
 
-It is very easy to write custom reporters. A reporter is simply a class which
-responds to `report` and takes a single {Radar::ExceptionEvent} as a parameter.
-Below is an example of a reporter which simply prints out that an error
-occurred:
+It is very easy to write custom reporters. A reporter is either a class which
+responds to `report` and takes a single {Radar::ExceptionEvent} as a parameter,
+or it is a lambda function which takes a single {Radar::ExceptionEvent} as a
+parameter. Below is an example of a lambda function reporter which simply
+prints out that an error occurred to `stdout`:
+
+    Radar::Application.new(:my_application) do |app|
+      app.reporter do |event|
+        puts "An exception occurred! Message: #{event.exception.message}"
+      end
+    end
+
+And the same example as above except implemented using a class:
 
     class StdoutReporter
       def report(event)
@@ -203,10 +238,8 @@ occurred:
       end
     end
 
-And then using that reporter is just as easy:
-
     Radar::Application.new(:my_application) do |app|
-      app.reporters.use StdoutReporter
+      app.reporter StdoutReporter
     end
 
 ## Data Extensions
@@ -241,7 +274,7 @@ Data extensions are enabled via the application configuration like most other
 things:
 
     Radar::Application.new(:my_application) do |app|
-      app.data_extensions.use UnameExtension
+      app.data_extension UnameExtension
     end
 
 ### Built-In Data Extensions
@@ -317,15 +350,44 @@ Examples of each are shown below (in the above order):
     app.match :class, StandardError, :include_subclasses => true
     app.match :class, /.*Error/
 
+#### `:local_request`
+
+A matcher which matches if a web request came from a local address. This
+matcher requires that a remote IP be available at `event.to_hash[:request][:remote_ip]`
+(which is set by the Rack and Rails data extensions if you're using it
+in any framework).
+
+Examples of how it can be used below:
+
+    app.match :local_request
+    app.match :local_request, :remote_ip_getter => Proc.new { |event| event.to_hash[:my_ip] }
+    app.match :local_request, :localhost => /^192\.168\.0\.1$/
+
+Usually the defaults are what you want. Also, this matcher is more useful
+as a rejecter, typically, since you don't want local requests during
+development firing off exception reports:
+
+    app.reject :local_request
+
 ### Custom Matchers
 
-Matchers are simply classes which respond to `matches?` which returns a boolean
-noting if the given {Radar::ExceptionEvent} matches. If true, then the exception
+Matchers are simply classes which respond to `matches?` or a lambda function,
+both of which are expected to take a single {Radar::ExceptionEvent} as a
+parameter and must return a boolean `true` or `false. If true, then the exception
 is reported, otherwise other matchers are tried, or if there are no other matchers,
 the exception is ignored.
 
-Below is a simple custom matcher which only matches exceptions with the
-configured message:
+Below is a simple custom matcher which only matches exceptions with a
+specific message, implemented using a lambda function:
+
+    Radar::Application.new(:app) do |app|
+      app.match do |event|
+        event.exception.message == "Hello"
+      end
+    end
+
+And now the same matcher as above is implemented using a class, with a
+little more flexibility:
 
     class ErrorMessageMatcher
       def initialize(message)
@@ -337,16 +399,37 @@ configured message:
       end
     end
 
-And the usage is shown below:
-
     Radar::Application.new(:app) do |app|
-      app.match ErrorMessageMatcher, "sample message"
+      app.match ErrorMessageMatcher, "Hello"
     end
 
-And this results in the following behavior:
+Both of the above result in the following behavior:
 
     raise "Hello, World"   # not reported
-    raise "sample message" # reported since it matches the message
+    raise "Hello"          # reported since it matches the message
+
+As you can see, for quick, easy matchers, lambda functions are the way to
+go and provide an easy solution to matching. However, if you need more
+customizability or complex logic, classes are the ideal solution.
+
+### Rejecters
+
+Matchers are useful for setting up a whitelist of exactly what is allowed
+to be reported. Sometimes it is more useful to setup a blacklist, instead
+(or a combination of the both). "Rejecters" is the term given to the blacklist,
+although they use the exact same matchers as above. The only difference is
+that if any of the rejecters match, then the error is not reported.
+
+Another important difference is that rejecters take precedence over matchers.
+This means that even if a matcher would have matched the exception, if
+a rejecter matches it, then the exception will never be reported by Radar.
+
+Using rejecters is the exact same as matchers, and use the exact same
+classes:
+
+    Radar::Application.new(:app) do |app|
+      app.reject :backtrace, "my_file.rb"
+    end
 
 ## Filters
 
@@ -363,7 +446,7 @@ The easiest way, if the filtering is really simple, is to just
 use a lambda. Below is a small example:
 
     Radar::Application.new(:my_app) do |app|
-      app.filters.use do |data|
+      app.filter do |data|
         data.delete(:password)
         data
       end
@@ -386,7 +469,7 @@ there is more complex logic in the filtering. The class must respond to
     end
 
     Radar::Application.new(:my_app) do |app|
-      app.filters.use MyPasswordFilter
+      app.filter MyPasswordFilter
     end
 
 This does the same thing, functionally, as the previous lambda example. However,
@@ -402,7 +485,7 @@ data and replaces it with specified text ("[FILTERED]" by default). Below we
 configure the key filter to filter passwords:
 
     Radar::Application.new(:my_app) do |app|
-      app.filters.use :key, :key => :password
+      app.filter :key, :key => :password
     end
 
 Then, assuming an exception is raised at some point and the following event data
@@ -431,7 +514,7 @@ catch any exceptions by the rack application:
     require "radar"
 
     app = Radar::Application.new(:my_app)
-    app.reporters.use :io, :io_object => STDOUT
+    app.reporter :io, :io_object => STDOUT
 
     use Rack::Radar, :application => app
     run YourWebApp
@@ -452,6 +535,24 @@ of only the additional information is shown below:
       }
     }
 
+### Rails 2
+
+Radar can integrate with any Rails 2 application to automatically
+catch any exceptions thrown by actions as well as provide additional
+information capture when the exception is raised. First, add the `radar`
+dependency to your environment (via a `Gemfile` or `environment.rb`) and
+make sure it is installed. Then create an initializer in `config/initializers/radar.rb`
+to create your application:
+
+    Radar::Application.new(:my_app) do |app|
+      # Enable any reporters here and configure the app as usual
+
+      # Integrate with rails 2
+      app.integrate :rails2
+    end
+
+Radar will immediately begin to catch and report any errors.
+
 ### Rails 3
 
 Radar can integrate very easily with any Rails 3 application to automatically
@@ -470,6 +571,30 @@ steps to take to setup Radar. Radar will already work with your application at t
 but it won't report to anywhere by default, so at the very least you must
 open up `config/initializers/radar.rb` and add a reporter.
 
+### Sinatra
+
+Radar can easily integrate with Sinatra, since Sinatra is built on top of
+Rack. Below is a very simple example Sinatra application showing Radar
+integration:
+
+    require "rubygems"
+    require "sinatra"
+    require "radar"
+
+    # First define the Radar application, like normal.
+    Radar::Application.new(:my_app) do |app|
+      # ...
+    end
+
+    # And the Sinatra application
+    class MyApp < Sinatra::Base
+      use Rack::Radar, :application => Radar[:my_app]
+
+      get "/" do
+        raise "BOOM!"
+      end
+    end
+
 ## Internals Logging
 
 Radar provides a lightweight internal log which logs information which