wat_catcher 0.5.2 → 0.5.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ca3288fba4d7e3a5f53af3b8fdfe19d7f2cf6816
-  data.tar.gz: d626b7f399746367f991c32abf49f311352641a1
+  metadata.gz: 4aa334c6634706d075857044218ed559877c0dc6
+  data.tar.gz: 9f7a7c8af3e7c3a34a4cc490b7e6907253f56b1c
 SHA512:
-  metadata.gz: 82c045b71a0350a3b556747adf338ca697a9c0fe48be94b30a835a746cb547b0cac8d115b5f051c1a86685a4b32b4a99a057dd84701271ec608ca2a962c9fe5d
-  data.tar.gz: 8a0feafeb82845a4752f67dd5990941beb8d9cf72692564bc17ccef85e4e19392621e20415892c3958a7b76aaf2308965cc5d545375bfac92a82e8549d887159
+  metadata.gz: e7fced4c2bc850dee9bb309be2f0bd82a4add929e1f6a958df1c1eda1ffd2a0c979ef79e8baa2db6c75fa40da6769dd01e13c37fc6a47f96c8ad39b346cbb08c
+  data.tar.gz: e7e5ad54fc6e647d53dd7e608857d858693ae85ec3fcee80129ac602efbbf0475cef2e10cbc194e6e50123929671fdafc54688658ddae102da9c9566e578f5ae

data/README.md

@@ -18,7 +18,162 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+### Configuration
+You can configure the wat_catcher in 2 ways; 1) via a config/wat_catcher.yml file or in ruby.
+
+Currently there are only 2 configuration options:
+host: This is the beginning of the url used to post wats to wattle.  It should look something like "https://yourwattleserver.com".
+disabled: If truthy this will stop any wats from being posted.
+
+Here are 2 identical configs specified in the yml and in ruby.
+
+config/wat_catcher.yml
+```yml
+production: &default
+  host: "https://wattle.yourhost.com"
+
+development:
+  <<: *default
+  disabled: true
+
+test:
+  <<: *default
+  disabled: true
+```
+
+OR
+
+config/application.rb
+```ruby
+module YourApp
+  class Application < Rails::Application
+    WatCatcher.configuration.host =  "https://wattle.yourhost.com"
+  end
+end
+```
+
+config/environments/development.rb
+```ruby
+YourApp::Application.configure do
+  WatCatcher.configuration.disabled = true
+end
+```
+
+config/environments/test.rb
+```ruby
+YourApp::Application.configure do
+  WatCatcher.configuration.disabled = true
+end
+```
+
+
+### Mount the engine in your app for javascript errors
+To get around cross-origin issues, an engine was created that accepts POSTs of client exceptions and puts a sidekiq
+job in to post the wat to wattle.
+
+In your routes.rb:
+```ruby
+YourApp::Application.routes.draw do
+  mount WatCatcher::Engine => '/wat_catcher'
+end
+```
+
+### Integrating with a controller
+
+Posting errors from a controller action is done by simply including the CatcherOfWats concern into your controller
+```ruby
+class ApplicationController < ActionController::Base
+  include WatCatcher::CatcherOfWats
+end
+```
+
+That will install an around_filter that reports and re-raises anything raised in an action.
+
+If you want to record some info about what user saw the error simply implement a 'wat_user' method on the controller
+```ruby
+class ApplicationController < ActionController::Base
+
+  def wat_user
+    {id: logged_in? ? "account_#{current_user.id}" : nil }
+  end
+
+end
+```
+
+The wat_user will be turned into a json object.  You may put any field in the wat_user, but the 'id' field will be used
+by wattle to decide how many unique users have seen an exception.
+
+### Integrating with sidekiq
+
+To have sidekiq post exceptions from sidekiq jobs you must install the sidekiq middleware:
+```ruby
+::Sidekiq.configure_server do |config|
+  config.server_middleware do |chain|
+    chain.add ::WatCatcher::SidekiqMiddleware
+  end
+end
+```
+
+If you want to some info about what user saw the error you need to implement a 'wat_user' method on the worker.  The user
+object returned by this wat_user follows the same rules as the wat_user on a controller, but the way it's called is
+more complicated.
+
+Whatever method is being called by sidekiq to start the job, make sure it implements a wat_user method that accepts
+the same arguments.
+
+Here are some ways that a wat_user method could be implemented:
+```ruby
+class SomeModel < ActiveRecord::Base
+  belongs_to :account
+  class << self
+    def notify(some_model_id)
+      SomeModel.find(some_model_id).some_delayed_method
+    end
+
+    def wat_user(some_model_id)
+    { id: "some_model_#{some_model_id}" }
+    end
+  end
+
+
+  def wat_user(*args)
+    { id: "some_model_#{id}" }
+  end
+
+  def some_delayed_method
+    raise 'herp'
+  end
+
+  def some_other_delayed_method(an_arg)
+    raise 'derp'
+  end
+
+end
+
+# Queuing on SomeModel like the following should generate a wat_user with a reasonable id.
+SomeModel.last.delay.some_delayed_method
+SomeModel.last.delay.some_other_delayed_method('blarg')
+SomeModel.delay.notify(12)
+
+
+class SomeWorker
+  include Sidekiq::Worker
+
+  def perform(some_arg)
+    raise "wat? #{some_arg}"
+  end
+
+  def wat_user(some_arg)
+    { id: "SomeWorker: #{some_arg}" }
+  end
+end
+
+# The queued job will raise an error and register a wat with the user "SomeWorker: derp"
+SomeWorker.perform_async("derp")
+```
+
+
+When in doubt, check out the cconstantine/wattle.  It uses itself to report errors and uses all of the above features.
 
 ## Contributing
 

data/lib/wat_catcher/report.rb

@@ -11,6 +11,7 @@ module WatCatcher
     end
 
     def send_report
+      return if WatCatcher.configuration.disabled
       ::WatCatcher::SidekiqPoster.perform_async("#{WatCatcher.configuration.host}/wats", params)
     end
 

data/lib/wat_catcher/version.rb

@@ -1,3 +1,3 @@
 module WatCatcher
-  VERSION = "0.5.2"
+  VERSION = "0.5.3"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: wat_catcher
 version: !ruby/object:Gem::Version
-  version: 0.5.2
+  version: 0.5.3
 platform: ruby
 authors:
 - Chris Constantine