radar 0.2.0 → 0.3.0

data/.yardopts

@@ -1,3 +1,4 @@
 -m markdown
+--exclude 'lib/radar/integration/rails3/templates/*'
 --files
 docs/user_guide.md

data/CHANGELOG.md

@@ -1,4 +1,17 @@
-## 0.2.0 (unreleased)
+## 0.3.0 (August 21, 2010)
+
+  - Added `KeyFilter` to filter out specific keys in the data hash.
+  - Added filters, which are called after data extensions as a way
+    to filter out information (passwords, shorten backtrace, etc.) [GH-19]
+  - Added `LoggerReporter` to log to any `Logger` object. [GH-20]
+  - Rails 3 integration. See user guide for more information.
+  - Rack integration. See user guide for more information. [GH-13]
+  - Added `IoReporter` to log to any `IO` object.
+  - Refinements to `FileReporter` and sprinkled logger statements around.
+  - Lightweight logging mechanism added so that you can verify Radar is doing
+    its job. [GH-9]
+
+## 0.2.0 (August 17, 2010)
 
   - Built in matcher: `:backtrace` (or `BacktraceMatcher`) which checks that
     the backtrace includes the given text. [GH-18]

data/Gemfile

@@ -1,11 +1,17 @@
-source :gemcutter
+source "http://rubygems.org"
 
-# Specify your gem's dependencies in radar.gemspec
-gemspec
+# Specify the path directly so that files in the examples/
+# directory just work.
+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"
+  gem "yard", :git => "http://github.com/lsegal/yard.git", :ref => "bf84275"
   gem "bluecloth"
 end
+
+group :examples do
+  gem "rack"
+  gem "rails"
+end

data/Gemfile.lock

@@ -1,24 +1,86 @@
 GIT
   remote: http://github.com/lsegal/yard.git
   revision: bf84275
+  ref: bf84275
   specs:
     yard (0.6.0.rc1)
 
 PATH
   remote: .
   specs:
-    radar (0.2.0)
+    radar (0.3.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)
+      mail (~> 2.2.5)
+    actionpack (3.0.0.rc)
+      activemodel (= 3.0.0.rc)
+      activesupport (= 3.0.0.rc)
+      builder (~> 2.1.2)
+      erubis (~> 2.6.6)
+      i18n (~> 0.4.1)
+      rack (~> 1.2.1)
+      rack-mount (~> 0.6.9)
+      rack-test (~> 0.5.4)
+      tzinfo (~> 0.3.22)
+    activemodel (3.0.0.rc)
+      activesupport (= 3.0.0.rc)
+      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)
+    builder (2.1.2)
+    erubis (2.6.6)
+      abstract (>= 1.0.0)
+    i18n (0.4.1)
     json (1.4.6)
+    mail (2.2.5)
+      activesupport (>= 2.3.6)
+      mime-types
+      treetop (>= 1.4.5)
+    mime-types (1.16)
     mocha (0.9.8)
       rake
+    polyglot (0.3.1)
+    rack (1.2.1)
+    rack-mount (0.6.9)
+      rack (>= 1.0.0)
+    rack-test (0.5.4)
+      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)
+      thor (~> 0.14.0)
     rake (0.8.7)
     shoulda (2.11.3)
+    thor (0.14.0)
+    treetop (1.4.8)
+      polyglot (>= 0.3.1)
+    tzinfo (0.3.22)
 
 PLATFORMS
   ruby
@@ -28,7 +90,9 @@ DEPENDENCIES
   bundler (>= 1.0.0.rc.5)
   json (>= 1.4.6)
   mocha
+  rack
   radar!
+  rails
   rake
   shoulda
   yard!

data/README.md

@@ -22,6 +22,15 @@ user all the same questions which could've easily have been gathered automatical
 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.
 
+## 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
+  - Run multiple Radar "applications" side-by-side to catch and report
+    different exceptions to different places
+  - Integration with 3rd party software: Rack, Rails 3.
+
 ## Quick Start
 
     gem install radar
@@ -29,7 +38,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.config.reporters.use Radar::Reporter::FileReporter
+    r.reporters.use :file
     r.report(exception)
 
 You can also tell Radar to attach itself to Ruby's `at_exit` hook

data/docs/user_guide.md

@@ -3,7 +3,15 @@
 ## Overview
 
 Radar is a tool which provides a drop-in solution to catching and reporting
-errors in your Ruby application via customizable mediums.
+errors in your Ruby application via customizable mediums. A quick feature
+breakdown of Radar:
+
+  - 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
+  - Run multiple Radar "applications" side-by-side to catch and report
+    different exceptions to different places
+  - Integration with 3rd party software: Rack, Rails 3.
 
 ## Installation
 
@@ -32,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.config.reporters.use Radar::Reporter::FileReporter
+      app.reporters.use :file
     end
 
 ### Reporting Errors
@@ -61,6 +69,26 @@ 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.
 
+## Terminology
+
+Although you've already seen a basic example, I think its a good idea to
+go over terminology quickly before moving onto to the details of every feature:
+
+  - **application** - A single exception reporter which can contain its own
+    set of matchers, reporters, data extensions, etc.
+  - **reporter** - A reporter takes Radar-generated exception data when an
+    exception is reported and does _something_ with it such as save it to a file,
+    store it on a server, etc.
+  - **data extension** - Adds additional contextual information to the exception
+    event hash before it is sent to the reporters.
+  - **matcher** - An exception must adhere to at least one matcher for Radar
+    to send the exception to reporters. This allows for filtering of specific
+    exceptions.
+  - **filter** - A class or proc that filters the data before it is reported.
+    This allows you to filter passwords, for example.
+  - **integration** - The act of integrating Radar with 3rd party software,
+    such as Rack or Rails.
+
 # Features
 
 ## Reporters
@@ -80,14 +108,14 @@ of what this means with a few examples:
 Reporters are enabled using the appilication configuration:
 
     Radar::Application.new(:my_application) do |app|
-      app.config.reporters.use FileReporter
+      app.reporters.use :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.config.reporters.use FileReporter do |reporter|
+      app.reporters.use :file do |reporter|
         reporter.output_directory = "~/.radar/exceptions"
       end
     end
@@ -96,10 +124,17 @@ 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.config.reporters.use FileReporter
-      app.config.reporters.use AnotherReporter
+      app.reporters.use FileReporter
+      app.reporters.use AnotherReporter
     end
 
+As you can see from the above examples, a reporter takes both a symbol
+or a class. If a symbol is given, Radar expects the class to be camelcased
+suffixed with `Reporter` and be under the `Radar::Reporter` namespace.
+For example, if you used the symbol `:my_place`, it would expect the reporter
+to be at `Radar::Reporter::MyPlaceReporter`. To avoid this, you can always
+use the class explicitly.
+
 ### Built-in Reporters
 
 #### FileReporter
@@ -112,7 +147,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.config.reporters.use Radar::Reporter::FileReporter do |reporter|
+      app.reporters.use :file do |reporter|
         reporter.output_directory = "~/my_application_errors"
       end
     end
@@ -133,6 +168,28 @@ A few notes:
 For complete documentation on this reporter, please see the actual {Radar::Reporter::FileReporter}
 page.
 
+#### IoReporter
+
+{Radar::Reporter::IoReporter IoReporter} outputs the exception event JSON to
+any IO object (`stdout`, `stderr`, a net stream, etc.).
+
+    Radar::Application.new(:my_application) do |app|
+      app.reporters.use :io, :io_object => STDOUT
+    end
+
+#### LoggerReporter
+
+{Radar::Reporter::LoggerReporter LoggerReporter} outputs the exception event JSON
+to any `Logger` object. This is useful if you want to integrate Radar with an
+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
+    end
+
+`log_level` will default to `:error` if not specified.
+
 ### Custom Reporters
 
 It is very easy to write custom reporters. A reporter is simply a class which
@@ -149,7 +206,7 @@ occurred:
 And then using that reporter is just as easy:
 
     Radar::Application.new(:my_application) do |app|
-      app.config.reporters.use StdoutReporter
+      app.reporters.use StdoutReporter
     end
 
 ## Data Extensions
@@ -184,7 +241,7 @@ Data extensions are enabled via the application configuration like most other
 things:
 
     Radar::Application.new(:my_application) do |app|
-      app.config.data_extensions.use UnameExtension
+      app.data_extensions.use UnameExtension
     end
 
 ### Built-In Data Extensions
@@ -211,8 +268,8 @@ really exceptional.
 Matchers are enabled in the application configuration:
 
     Radar::Application.new(:app) do |app|
-      app.config.match :class, StandardError
-      app.config.match :backtrace, /file.rb$/
+      app.match :class, StandardError
+      app.match :backtrace, /file.rb$/
     end
 
 As you can see, multiple matchers may be enabled. In this case, as long as at
@@ -237,9 +294,9 @@ A matcher which matches against the backtrace of the exception. It allows:
 
 Examples of each are shown below (respective to the above order):
 
-    app.config.match :backtrace, "my_file.rb"
-    app.config.match :backtrace, /.+_test.rb/
-    app.config.match :backtrace, /.+_test.rb/, :depth => 5
+    app.match :backtrace, "my_file.rb"
+    app.match :backtrace, /.+_test.rb/
+    app.match :backtrace, /.+_test.rb/, :depth => 5
 
 If an exception doesn't have a backtrace (can happen if you don't actually
 `raise` an exception, but instantiate one) then the matcher always returns
@@ -256,9 +313,9 @@ so it can check against:
 
 Examples of each are shown below (in the above order):
 
-    app.config.match :class, StandardError
-    app.config.match :class, StandardError, :include_subclasses => true
-    app.config.match :class, /.*Error/
+    app.match :class, StandardError
+    app.match :class, StandardError, :include_subclasses => true
+    app.match :class, /.*Error/
 
 ### Custom Matchers
 
@@ -283,7 +340,7 @@ configured message:
 And the usage is shown below:
 
     Radar::Application.new(:app) do |app|
-      app.config.match ErrorMessageMatcher, "sample message"
+      app.match ErrorMessageMatcher, "sample message"
     end
 
 And this results in the following behavior:
@@ -291,3 +348,142 @@ And this results in the following behavior:
     raise "Hello, World"   # not reported
     raise "sample message" # reported since it matches the message
 
+## Filters
+
+Filters provide a method of filtering the data hash just before it is sent
+to any reporters. This allows you to filter passwords, modify fields, etc.
+
+### Using a Filter
+
+There are two ways to use a filter: as a class or as a lambda.
+
+#### Lambda
+
+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|
+        data.delete(:password)
+        data
+      end
+    end
+
+This filter would delete the `:password` key from the data hash, and returns
+the new data hash.
+
+#### Class
+
+You can also create a filtering class if that is more convenient or if
+there is more complex logic in the filtering. The class must respond to
+`filter`.
+
+    class MyPasswordFilter
+      def filter(data)
+        data.delete(:password)
+        data
+      end
+    end
+
+    Radar::Application.new(:my_app) do |app|
+      app.filters.use MyPasswordFilter
+    end
+
+This does the same thing, functionally, as the previous lambda example. However,
+it is clear to see how a class would enable you to more easily encapsulate more
+complex filtering logic.
+
+### Built-in Filters
+
+#### KeyFilter
+
+The {Radar::Filters::KeyFilter KeyFilter} filters specific keys out of the result
+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
+    end
+
+Then, assuming an exception is raised at some point and the following event data
+is created:
+
+    { :request  => { :password => "foo" },
+      :rack_env => { :query => { :password => "foo" } } }
+
+Then before it is sent to reporters it will be filtered into this:
+
+    { :request  => { :password => "[FILTERED]" },
+      :rack_env => { :query => { :password => "[FILTERED]" } } }
+
+There are many options which can be sent to `KeyFilter`, please see the
+class documentation for more details.
+
+## Integration with Other Software
+
+### Rack
+
+Radar provides a lightweight Rack middleware to catch and report errors to a
+specified Radar application. Below is a sample `config.ru` file which would
+catch any exceptions by the rack application:
+
+    require "rubygems"
+    require "radar"
+
+    app = Radar::Application.new(:my_app)
+    app.reporters.use :io, :io_object => STDOUT
+
+    use Rack::Radar, :application => app
+    run YourWebApp
+
+If `YourWebApp` were to throw any exceptions, `Rack::Radar` would catch it,
+report it to `app`, and reraise the exception.
+
+Using the Rack middleware also enables the rack data extension, which provides
+additional information about the rack request and environment. Sample output
+of only the additional information is shown below:
+
+    { "request": {
+        "request_method": "GET",
+        "url": "http://localhost:9292/favicon.ico",
+        "parameters": {},
+        "remote_ip": "127.0.0.1",
+        "rack_env": { ... }
+      }
+    }
+
+### Rails 3
+
+Radar can integrate very easily with any Rails 3 application to automatically
+catch any Rails exceptions as well as provide additional information captured
+when the exception was raised. First, add Radar to your `Gemfile`:
+
+    gem "radar"
+
+Then `bundle install` so you pull down the gem. Then install Radar by
+running the built-in generator:
+
+    rails generate radar
+
+This will create the necessary initializer and let you know what further
+steps to take to setup Radar. Radar will already work with your application at this point,
+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.
+
+## Internals Logging
+
+Radar provides a lightweight internal log which logs information which
+can be used to easily solve the following problems:
+
+* Verifying that Radar is working
+* Investigating why Radar is/isn't reporting certain exceptions
+* Storing more information _in case_ something goes wrong
+
+By default, the logger is disabled, but it can easily be enabled on a
+per-application basis by specifying where it should log:
+
+    Radar::Application.new(:app) do |app|
+      app.config.log_location = "/var/log/radar/my_app.log"
+    end
+
+Multiple applications may be logged to the same place without issue.