exception_manager 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: eb305107f1c6f84dd05546de27dbfe8981d0abf7
+  data.tar.gz: 532f25870f02b30b67307f43edcff07951ae9b08
+SHA512:
+  metadata.gz: e397bf900e4f40e762ecc2d37465b3415bc51ae15d6d22423285529ab0b832599bc4357a295d7d495f6ebef22c4278b99b56b95c0d699d9e8a4828ef6adf2794
+  data.tar.gz: ccf737eb0b0bf15288bd19ec90bbecd15eaf7e9fe3fa8685577df191e87a4545d75b48f0aea46da49768ace6dae303c27fe52c016fe66bdca99713937ca9fced

data/.gitignore

@@ -0,0 +1,16 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log
+.ruby-version
+.ruby-gemset

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--require spec_helper

data/Gemfile

@@ -0,0 +1,6 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in exception_manager.gemspec
+gemspec
+
+gem 'pry'

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2015 Ilya Bylich
+
+MIT License
+
+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,121 @@
+# ExceptionManager
+
+Gem for better exception recording.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'exception_manager'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install exception_manager
+
+## Usage
+
+First of all, make sure that ExceptionManager is enabled in your application.
+
+```ruby
+# config/initializers/exception_manager.rb
+ExceptionManager.enable!
+```
+
+That's it! Now you can use it.
+
+```ruby
+class TestClassThatRaisesException
+  @@class_variable = :class_value
+
+  def test_error(*args)
+    @instance_variable = :instance_value
+
+    raise 'Test error'
+  end
+end
+
+begin
+  TestClassThatRaisesException.new.test_error(1, 2, 3)
+rescue => e
+  puts "Subject: #{e.subject}"
+  puts "Locals: #{e.locals}"
+  puts "Instance variables: #{e.subject_instance_variables}"
+  puts "Class variables: #{e.subject_class_variables}"
+  puts "Summary: #{e.summary.inspect}"
+end
+```
+
+And if you have `pry`, you can combine it:
+```ruby
+e._binding.pry
+```
+
+## Integration with monitoring systems like NewRelic
+
+NewRelic uses `to_s` method for fetching message from exception:
+[source](https://github.com/newrelic/rpm/blob/master/lib/new_relic/noticed_error.rb#L33).
+
+Unfortunately you cannot override `to_s` method like this:
+
+```ruby
+# DO NOT ADD THIS CODE TO YOUR PROJECT
+# IF YOU DON'T WANT TO GET SEGFAULT
+class YourApiBaseException < StandardError
+  def to_s
+    [super, summary.inspect].join(' ')
+  end
+end
+```
+
+The solution is in this line:
+[source](https://github.com/newrelic/rpm/blob/master/lib/new_relic/noticed_error.rb#L31)
+
+Instead of overriding `to_s` method we can override `original_exception` method:
+
+```ruby
+# This code is safe
+class YourApiBaseException < StandardError
+  def original_exception
+    message_for_new_relic = [message, summary.inspect].join(' ')
+    self.exception(message_for_new_relic)
+  end
+end
+```
+
+From this moment all exceptions inherited from `YourApiBaseException` will have message
+with exception summary:
+```ruby
+begin
+  raise YourApiBaseException, 'my custom message'
+rescue YourApiBaseException => e
+  puts e.original_exception.to_s # this is exactly what NewRelic gem calls
+end
+# => 'my custom message {:locals=>..., :subject=>..., }'
+```
+
+
+Other systems may use `message` method, so the code will look like:
+```ruby
+class YourApiBaseException < StandardError
+  def message
+    [super, summary.inspect].join(' ')
+  end
+end
+```
+
+If you don't know exactly which method is used in your monitoring system,
+you can simply override both :smile:
+
+## Contributing
+
+1. Fork it ( https://github.com/[my-github-username]/exception_manager/fork )
+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. Create a new Pull Request

data/Rakefile

@@ -0,0 +1,5 @@
+require 'bundler/gem_tasks'
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec)
+task default: :spec

data/exception_manager.gemspec

@@ -0,0 +1,25 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'exception_manager/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'exception_manager'
+  spec.version       = ExceptionManager::Version::STRING
+  spec.authors       = ['Ilya Bylich']
+  spec.email         = ['ibylich@gmail.com']
+  spec.summary       = 'Tool for managing exceptions'
+  spec.description   = %q{Gem for inspecting local and class/instance variables when raising exceptions}
+  spec.homepage      = ''
+  spec.license       = 'MIT'
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ['lib']
+
+  spec.add_development_dependency 'bundler', '~> 1.7'
+  spec.add_development_dependency 'rake', '~> 10.0'
+  spec.add_development_dependency 'rspec', '~> 3.2.0'
+  spec.add_development_dependency 'rspec-its', '~> 1.2.0'
+end

data/lib/exception_manager/config.rb

@@ -0,0 +1,50 @@
+require 'logger'
+
+module ExceptionManager::Config
+  def enable!
+    tracepoint.enable
+  end
+
+  def disable!
+    tracepoint.disable
+  end
+
+  def enabled?
+    tracepoint.enabled?
+  end
+
+  def disabled?
+    !enabled?
+  end
+
+  def tracepoint
+    @tracepoint ||= TracePoint.new(:raise) do |tp|
+      if ExceptionManager.applicable?(tp.raised_exception)
+        tp.raised_exception._binding = tp.binding
+      end
+    end
+  end
+
+  def filters
+    @filters ||= []
+  end
+
+  def add_filter(&block)
+    filters << block
+  end
+
+  def reset_filters!
+    @filters = []
+  end
+
+  def applicable?(exception)
+    filters.all? do |filter|
+      filter.call(exception)
+    end
+  end
+
+  def logger
+    @logger = Logger.new(STDOUT)
+  end
+  attr_writer :logger
+end

data/lib/exception_manager/methods/locals.rb

@@ -0,0 +1,10 @@
+class ExceptionManager::Methods::Locals
+  def self.run(exception_binding)
+    exception_binding.eval %q{
+      local_variables.inject({}) do |hash, local_variable_name|
+        hash[local_variable_name] = eval(local_variable_name.to_s)
+        hash
+      end
+    }
+  end
+end

data/lib/exception_manager/methods/subject.rb

@@ -0,0 +1,5 @@
+class ExceptionManager::Methods::Subject
+  def self.run(exception_binding)
+    exception_binding.eval('self')
+  end
+end

data/lib/exception_manager/methods/subject_class_variables.rb

@@ -0,0 +1,11 @@
+class ExceptionManager::Methods::SubjectClassVariables
+  def self.run(exception_binding)
+    exception_binding.eval %q{
+      klass = is_a?(Class) ? self : self.class
+      klass.class_variables.inject({}) do |hash, class_variable_name|
+        hash[class_variable_name] = klass.class_variable_get(class_variable_name)
+        hash
+      end
+    }
+  end
+end

data/lib/exception_manager/methods/subject_instance_variables.rb

@@ -0,0 +1,10 @@
+class ExceptionManager::Methods::SubjectInstanceVariables
+  def self.run(exception_binding)
+    exception_binding.eval %q{
+      instance_variables.inject({}) do |hash, instance_variable_name|
+        hash[instance_variable_name] = instance_variable_get(instance_variable_name)
+        hash
+      end
+    }
+  end
+end

data/lib/exception_manager/patch.rb

@@ -0,0 +1,30 @@
+module ExceptionManager::ExceptionPatch
+  attr_accessor :_binding
+
+  def locals
+    ExceptionManager::Methods::Locals.run(_binding)
+  end
+
+  def subject
+    ExceptionManager::Methods::Subject.run(_binding)
+  end
+
+  def subject_instance_variables
+    ExceptionManager::Methods::SubjectInstanceVariables.run(_binding)
+  end
+
+  def subject_class_variables
+    ExceptionManager::Methods::SubjectClassVariables.run(_binding)
+  end
+
+  def summary
+    {
+      locals: locals,
+      subject: subject,
+      subject_instance_variables: subject_instance_variables,
+      subject_class_variables: subject_class_variables
+    }
+  end
+end
+
+Exception.send(:include, ExceptionManager::ExceptionPatch)

data/lib/exception_manager/version.rb

@@ -0,0 +1,8 @@
+module ExceptionManager
+  module Version
+    MAJOR = 1
+    MINOR = 0
+    PATCH = 0
+    STRING = [MAJOR, MINOR, PATCH].join('.')
+  end
+end

data/lib/exception_manager.rb

@@ -0,0 +1,15 @@
+require 'exception_manager/version'
+
+module ExceptionManager
+  require 'exception_manager/config'
+  extend ExceptionManager::Config
+
+  module Methods
+    autoload :Locals, 'exception_manager/methods/locals'
+    autoload :Subject, 'exception_manager/methods/subject'
+    autoload :SubjectInstanceVariables, 'exception_manager/methods/subject_instance_variables'
+    autoload :SubjectClassVariables, 'exception_manager/methods/subject_class_variables'
+  end
+end
+
+require 'exception_manager/patch'

data/spec/exception_manager/config_spec.rb

@@ -0,0 +1,56 @@
+require 'spec_helper'
+
+describe ExceptionManager::Config, reset_config: true do
+  subject(:manager) { ExceptionManager }
+
+  let(:exception) do
+    begin
+      Letter.new('message', 'from@example.com').deliver_to('to@example.com')
+    rescue => e
+      e
+    end
+  end
+
+  describe '.enable!/.disable!' do
+    context 'when exception manager is enabled' do
+      before { manager.enable! }
+      it { is_expected.to be_enabled }
+
+      it 'can be disabled' do
+        manager.disable!
+        expect(manager).to be_disabled
+      end
+
+      it 'adds local bindings to exceptions' do
+        expect(exception._binding).to_not be_nil
+      end
+    end
+
+    context 'when exception manager is disabled' do
+      before { manager.disable! }
+      it { is_expected.to be_disabled }
+
+      it 'can be enabled' do
+        manager.enable!
+        expect(manager).to be_enabled
+      end
+
+      it 'does not add local bindings to exceptions' do
+        expect(exception._binding).to be_nil
+      end
+    end
+  end
+
+  describe '.add_filters' do
+    before do
+      manager.add_filter do |e|
+        !e.is_a?(CannotDeliverMessageError)
+      end
+    end
+
+    it 'adds filters for tracepoint' do
+      expect(exception).to be_a(CannotDeliverMessageError)
+      expect(exception._binding).to be_nil
+    end
+  end
+end

data/spec/exception_manager/methods/locals_spec.rb

@@ -0,0 +1,12 @@
+require 'spec_helper'
+
+describe ExceptionManager::Methods::Locals do
+  let(:command) { described_class }
+  let(:exception_binding) { a = 1; binding }
+
+  describe '.run' do
+    let(:expected) { { a: 1 } }
+    subject(:result) { command.run(exception_binding) }
+    it { is_expected.to eq(expected) }
+  end
+end

data/spec/exception_manager/methods/subject_class_variables_spec.rb

@@ -0,0 +1,23 @@
+require 'spec_helper'
+
+describe ExceptionManager::Methods::SubjectClassVariables do
+  let(:command) { described_class }
+
+  let(:klass) do
+    Class.new do
+      self.class_variable_set(:@@a, 1)
+
+      def local_binding
+        binding
+      end
+    end
+  end
+
+  let(:exception_binding) { klass.new.local_binding }
+
+  describe '.run' do
+    subject { command.run(exception_binding) }
+    let(:expected) { { :@@a => 1 } }
+    it { is_expected.to eq(expected) }
+  end
+end

data/spec/exception_manager/methods/subject_instance_variables_spec.rb

@@ -0,0 +1,22 @@
+require 'spec_helper'
+
+describe ExceptionManager::Methods::SubjectInstanceVariables do
+  let(:command) { described_class }
+
+  let(:klass) do
+    Class.new do
+      def local_binding
+        @a = 1
+        binding
+      end
+    end
+  end
+
+  let(:exception_binding) { klass.new.local_binding }
+
+  describe '.run' do
+    subject(:result) { command.run(exception_binding) }
+    let(:expected) { { :@a => 1 } }
+    it { is_expected.to eq(expected) }
+  end
+end

data/spec/exception_manager/methods/subject_spec.rb

@@ -0,0 +1,22 @@
+require 'spec_helper'
+
+describe ExceptionManager::Methods::Subject do
+  let(:command) { described_class }
+
+  let(:klass) do
+    Class.new do
+      def self.local_binding
+        binding
+      end
+    end
+  end
+
+  let(:exception_binding) do
+    klass.local_binding
+  end
+
+  describe '.run' do
+    subject(:result) { command.run(exception_binding) }
+    it { is_expected.to eq(klass) }
+  end
+end

data/spec/exception_manager/patch_spec.rb

@@ -0,0 +1,81 @@
+require 'spec_helper'
+
+describe ExceptionManager do
+  subject(:error) do
+    begin
+      Letter.new('message', 'from@example.com').deliver_to('to@example.com')
+    rescue => e
+      e
+    end
+  end
+
+  describe 'Kernel.raise' do
+    it 'still raises exception' do
+      expect { raise 'foo' }.to raise_error
+    end
+  end
+
+  describe 'Exception#locals' do
+    let(:expected) do
+      {
+        exception_message: "'to@example.com' does not want to receive emails from you",
+        recipient: 'to@example.com'
+      }
+    end
+
+    it 'returns Hash of local variables available when #raise happened' do
+      expect(error.locals).to eq(expected)
+    end
+  end
+
+  describe 'Exception#subject' do
+    it 'returns context of place when subject was raised' do
+      expect(error.subject).to be_a(Letter)
+    end
+  end
+
+  describe 'Exception#subject_instance_variables' do
+    let(:expected) do
+      {
+        :@message => 'message',
+        :@sender => 'from@example.com'
+      }
+    end
+
+    it 'returns instance variables of #subject when #raise happened' do
+      expect(error.subject_instance_variables).to eq(expected)
+    end
+  end
+
+  describe 'Exception#subject_class_variables' do
+    let(:expected) do
+      {
+        :@@class_variable => 'class variable'
+      }
+    end
+
+    it 'returns class variables of #subject when #raise happened' do
+      expect(error.subject_class_variables).to eq(expected)
+    end
+  end
+
+  describe 'Exception#summary' do
+    let(:expected) do
+      {
+        locals: instance_of(Hash),
+        subject: instance_of(Letter),
+        subject_instance_variables: instance_of(Hash),
+        subject_class_variables: instance_of(Hash)
+      }
+    end
+
+    it 'returns all available information combined into single Hash' do
+      expect(error.summary).to be_a(Hash)
+
+      expect(error.summary[:locals]).to be_a(Hash)
+      expect(error.summary[:subject]).to be_a(Letter)
+      expect(error.summary[:subject_instance_variables]).to be_a(Hash)
+      expect(error.summary[:subject_class_variables]).to be_a(Hash)
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,23 @@
+ROOT = Pathname.new(File.expand_path('../..', __FILE__))
+$: << ROOT
+require 'exception_manager'
+require 'pry'
+require 'rspec/its'
+
+Dir[ROOT.join('spec/support/**/*.rb')].each { |f| require f }
+
+RSpec.configure do |config|
+  config.expect_with :rspec do |expectations|
+    expectations.include_chain_clauses_in_custom_matcher_descriptions = true
+  end
+
+  config.mock_with :rspec do |mocks|
+    mocks.verify_partial_doubles = true
+  end
+
+  config.before(:suite) do
+    ExceptionManager.enable!
+  end
+
+  config.order = :random
+end

data/spec/support/exception_examples/letter.rb

@@ -0,0 +1,22 @@
+# @example
+#  letter = Letter.new('message', 'sender@example.com')
+#  letter.deliver_to('recipient@example.com')
+#
+#  CannotDeliverMessageError: 'recipient@example.com' does not want to receive emails from you
+#
+CannotDeliverMessageError = Class.new(StandardError)
+
+class Letter
+  attr_reader :message, :sender
+  @@class_variable = 'class variable'
+
+  def initialize(message, sender)
+    @message = message
+    @sender = sender
+  end
+
+  def deliver_to(recipient)
+    exception_message = "'#{recipient}' does not want to receive emails from you"
+    raise CannotDeliverMessageError, exception_message
+  end
+end

data/spec/support/helpers/reset_config_helper.rb

@@ -0,0 +1,15 @@
+module ResetConfigHelper
+  def self.included(base)
+    base.instance_eval do
+      around(:each) do |example|
+        example.run
+        ExceptionManager.reset_filters!
+        ExceptionManager.enable!
+      end
+    end
+  end
+end
+
+RSpec.configure do |config|
+  config.include ResetConfigHelper
+end

metadata

@@ -0,0 +1,133 @@
+--- !ruby/object:Gem::Specification
+name: exception_manager
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Ilya Bylich
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-04-14 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.7'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 3.2.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 3.2.0
+- !ruby/object:Gem::Dependency
+  name: rspec-its
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.2.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.2.0
+description: Gem for inspecting local and class/instance variables when raising exceptions
+email:
+- ibylich@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .rspec
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- exception_manager.gemspec
+- lib/exception_manager.rb
+- lib/exception_manager/config.rb
+- lib/exception_manager/methods/locals.rb
+- lib/exception_manager/methods/subject.rb
+- lib/exception_manager/methods/subject_class_variables.rb
+- lib/exception_manager/methods/subject_instance_variables.rb
+- lib/exception_manager/patch.rb
+- lib/exception_manager/version.rb
+- spec/exception_manager/config_spec.rb
+- spec/exception_manager/methods/locals_spec.rb
+- spec/exception_manager/methods/subject_class_variables_spec.rb
+- spec/exception_manager/methods/subject_instance_variables_spec.rb
+- spec/exception_manager/methods/subject_spec.rb
+- spec/exception_manager/patch_spec.rb
+- spec/spec_helper.rb
+- spec/support/exception_examples/letter.rb
+- spec/support/helpers/reset_config_helper.rb
+homepage: ''
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.3
+signing_key: 
+specification_version: 4
+summary: Tool for managing exceptions
+test_files:
+- spec/exception_manager/config_spec.rb
+- spec/exception_manager/methods/locals_spec.rb
+- spec/exception_manager/methods/subject_class_variables_spec.rb
+- spec/exception_manager/methods/subject_instance_variables_spec.rb
+- spec/exception_manager/methods/subject_spec.rb
+- spec/exception_manager/patch_spec.rb
+- spec/spec_helper.rb
+- spec/support/exception_examples/letter.rb
+- spec/support/helpers/reset_config_helper.rb