escalate 0.1.0.pre.1 → 0.2.0.pre.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: bb743da8ea57e11a7bfa80d653548239e0b760ab
-  data.tar.gz: 36555a0ba6f8bca3f821c5b0044739e26762cc23
+SHA256:
+  metadata.gz: 67b615521fd3e15a59bb8401486496175afa19be36a98c415d9eccf52dd0815f
+  data.tar.gz: 951d5afc0052cde73fca383e23dc38aa63e759fce7f4863b2093e9bf9b2463b4
 SHA512:
-  metadata.gz: 7c735aa3214359068d14e0fd981c64c62e14896d73965d467d5b28ebaa3d2bf300ae9037164d3a4a7e5a6b4a77439a8a5137dd5d3b7b51eda27cef0ec7a57a60
-  data.tar.gz: a3899dc985f47f6e87d609b5fdf85443b9278ca100b40e5e41e4be641c8aa6116850dc80a4426f779c34e741b5b0893c9032e3c2b59974a9b802da0bcc8629bd
+  metadata.gz: 7979594ec79d527e123efb08114d602ab11446d8e822a9a716b582150d7e0f4b97840443974270177d861d874fbf4544f7e14eb8bd5e98e66acc86d49b51e19a
+  data.tar.gz: 2ab19d1367350559290fb9603e7af73934fcf1085121bf5a1cebe03059d450d19e53f76dc9947d92fac8a06f2a08fc0bb6ed12d0135a1e09617c87c6835dc158

data/CHANGELOG.md

@@ -4,6 +4,17 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [0.1.0] - Unreleased
+## [0.2.0] - Unreleased
+### Added
+- Added support for `on_escalate(log_first: false)`. The `escalate` gem will log first before
+  escalating if either of these is true: there are no `on_escalate` blocks registered, or
+  there are some and at least one of them passed `log_first: false`.
 
+## [0.1.0] - 2021-02-03
+### Added
+- Added `Escalate.mixin` interface for mixing in `Escalate` with your module for easy escalation of rescued exceptions
+- Added `escalate` method for escalating rescued exceptions with default behavior of logging to `STDERR`
+- Added `Escalate.on_escalate` for registering escalation callbacks like `Honeybadger` or `Sentry`
+
+[0.2.0]: https://github.com/Invoca/escalate/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/Invoca/escalate/releases/tag/v0.1.0

data/Gemfile

@@ -5,6 +5,8 @@ source "https://rubygems.org"
 # Specify your gem's dependencies in escalate.gemspec
 gemspec
 
+gem "contextual_logger"
+
 gem "pry"
 gem "pry-byebug"
 

data/Gemfile.lock

@@ -1,9 +1,8 @@
 PATH
   remote: .
   specs:
-    escalate (0.1.0.pre.1)
+    escalate (0.2.0.pre.3)
       activesupport
-      contextual_logger
 
 GEM
   remote: https://rubygems.org/
@@ -50,9 +49,11 @@ GEM
       thread_safe (~> 0.1)
 
 PLATFORMS
+  ruby
   x86_64-darwin-19
 
 DEPENDENCIES
+  contextual_logger
   escalate!
   pry
   pry-byebug

data/README.md

@@ -1,6 +1,10 @@
 # Escalate
 
-A simple and lightweight gem to help with escalating errors
+A simple and lightweight gem to escalate rescued exceptions. This implementation
+is an abstract interface that can be used on it's own, or attached to more concrete
+implementations like Honeybadger, Airbrake, or Sentry in order to not just log
+exceptions in an easy to parse way, but also escalate the appropriate information
+to third party systems.
 
 ## Installation
 
@@ -30,7 +34,7 @@ module SomeGem
 end
 ```
 
-This will expose the `Escalate#ex_escalate` method within your gem to be used instead
+This will expose the `Escalate#escalate` method within your gem to be used instead
 of using `logger.error`.
 
 ```ruby
@@ -54,8 +58,34 @@ end
 When `SomeGem.escalate` above is triggered, it will use the logger returned by `SomeGem.logger` or
 default to a `STDERR` logger and do the following:
 
-1. Log an error containing the exception and any additional information about the current environment that is specified
-2. Trigger any `escalation_callbacks` configured on the `Escalate` gem
+1. [optional] Log an error containing the exception, location_message, and context hash
+2. Trigger any `on_escalate_callbacks` configured on the `Escalate` gem
+
+Step (1) is optional. It will happen if either of these is true:
+ - by default if no `on_escalate_callbacks` have been registered; or
+ - if any of the `on_escalate_callbacks` was registered with `on_escalate(log_first: true)`.
+
+### Registering an Escalate Callback
+
+If you are using an error reporting service, you can register an `on_escalate` callback to escalate exceptions.
+You have the option to handle logging yourself, or to let `escalate` log first, before calling your callback.
+
+#### Leave the Logging to the Escalate Gem
+Here is an example that uses the default `log_first: true` so that logging is handled by the `Escalate` gem first:
+```
+Escalate.on_escalate do |exception, location_message, **context|
+  # send exception, location_message, **context to the error reporting service here
+end
+```
+
+#### Handle the Logging in the `on_escalate` Callback
+Here is an example that handles logging itself with `log_first: false`:
+```
+Escalate.on_escalate(log_first: false) do |exception, location_message, **context|
+  # log here first
+  # send exception, location_message, **context to the error reporting service here
+end
+```
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/escalate.gemspec

@@ -8,8 +8,8 @@ Gem::Specification.new do |spec|
   spec.authors       = ["Invoca Development", "Octothorp"]
   spec.email         = ["development@invoca.com", "octothorp@invoca.com"]
 
-  spec.summary       = "Simple gem for abstracting log escalations"
-  spec.description   = "Simple gem for abstracting log escalations"
+  spec.summary       = "A simple and lightweight gem to escalate rescued exceptions."
+  spec.description   = "A simple and lightweight gem to escalate rescued exceptions."
   spec.homepage      = "https://github.com/invoca/escalate"
   spec.required_ruby_version = Gem::Requirement.new(">= 2.4.0")
 
@@ -28,5 +28,4 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   spec.add_dependency "activesupport"
-  spec.add_dependency "contextual_logger"
 end

data/lib/escalate.rb

@@ -2,7 +2,6 @@
 
 require "active_support"
 require "active_support/core_ext"
-require "contextual_logger"
 
 require_relative "escalate/version"
 require_relative "escalate/mixin"
@@ -10,43 +9,53 @@ require_relative "escalate/mixin"
 module Escalate
   class Error < StandardError; end
 
+  LOG_FIRST_INSTANCE_VARIABLE = :@_escalate_log_first
+
+  @on_escalate_callbacks = Set.new
+
   class << self
+    attr_reader :on_escalate_callbacks
+
     # Logs and escalated an exception
     #
     # @param [Exception] exception
-    #   The exception that was raised and needs to be escalated
+    #   The exception that was rescued and needs to be escalated
     #
-    # @param [String] message
-    #   An additional message about what was happening at the time of the exception
+    # @param [String] location_message
+    #   An additional message giving an indication of where in the code this exception was rescued
     #
     # @param [Logger] logger
     #   The logger object to use when logging the exception
     #
     # @param [Hash] context
     #   Any additional context to be tied to the escalation
-    def escalate(exception, message, logger, **context)
-      error_message = <<~EOS
-        [Escalate] #{message} (#{context.inspect})
-          #{exception.class.name}: #{exception.message}
-          #{exception.backtrace.join("\n")}
-      EOS
-
-      if logger.is_a?(ContextualLogger::LoggerMixin)
-        logger.error(error_message, **context)
-      else
-        logger.error(error_message)
-      end
+    def escalate(exception, location_message, logger, **context)
+      ensure_failsafe("Exception rescued while escalating #{exception.inspect}") do
+        if on_escalate_callbacks.none? || on_escalate_callbacks.any? { |block| block.instance_variable_get(LOG_FIRST_INSTANCE_VARIABLE) }
+          logger_allows_added_context?(logger) or context_string = " (#{context.inspect})"
+          error_message = <<~EOS
+            [Escalate] #{location_message}#{context_string}
+            #{exception.class.name}: #{exception.message}
+            #{exception.backtrace.join("\n")}
+          EOS
+
+          if context_string
+            logger.error(error_message)
+          else
+            logger.error(error_message, **context)
+          end
+        end
 
-      on_escalate_blocks.each do |block|
-        block.call(exception, message, **context)
+        on_escalate_callbacks.each do |block|
+          ensure_failsafe("Exception rescued while escalating #{exception.inspect} to #{block.inspect}") do
+            block.call(exception, location_message, **context)
+          end
+        end
       end
-    rescue Exception => ex
-      STDERR.puts("[ExEscalator] Exception rescued while escalating #{exception.inspect}:" \
-                "#{ex.class.name}: #{ex.message}")
     end
 
     # Returns a module to be mixed into a class or module exposing
-    # the ex_escalate method to be used for escalating and logging
+    # the escalate method to be used for escalating and logging
     # exceptions.
     #
     # @param [Proc] logger_block
@@ -57,22 +66,53 @@ module Escalate
 
       Module.new do
         def self.included(base)
-          base.extend Escalate::Mixin
+          base.extend self
           base.escalate_logger_block = Thread.current[:escalate_logger_block] || -> { base.try(:logger) }
         end
+
+        attr_accessor :escalate_logger_block
+
+        def escalate(exception, location_message, **context)
+          Escalate.escalate(exception, location_message, escalate_logger, **context)
+        end
+
+        private
+
+        def escalate_logger
+          escalate_logger_block&.call || default_escalate_logger
+        end
+
+        def default_escalate_logger
+          @default_escalate_logger ||= Logger.new(STDERR)
+        end
       end
     end
 
-    # Registers an escalation callback to be executed when `ex_escalate`
+    # Registers an escalation callback to be executed when `escalate`
     # is invoked.
-    def on_escalate(&block)
-      on_escalate_blocks.add(block)
+    #
+    # @param [boolean] log_first: true
+    #   whether escalate should log first before escalating, or leave the logging to the escalate block
+    def on_escalate(log_first: true, &block)
+      block.instance_variable_set(LOG_FIRST_INSTANCE_VARIABLE, log_first)
+      on_escalate_callbacks.add(block)
+    end
+
+    def clear_on_escalate_callbacks
+      on_escalate_callbacks.clear
     end
 
     private
 
-    def on_escalate_blocks
-      @on_escalate_blocks ||= Set.new
+    def ensure_failsafe(message)
+      yield
+    rescue Exception => ex
+      STDERR.puts("[Escalator] #{message}: #{ex.class.name}: #{ex.message}")
+    end
+
+    def logger_allows_added_context?(logger)
+      defined?(ContextualLogger::LoggerMixin) &&
+        logger.is_a?(ContextualLogger::LoggerMixin)
     end
   end
 end

data/lib/escalate/mixin.rb

@@ -4,24 +4,8 @@ module Escalate
   module Mixin
     class << self
       def included(base)
-        raise 'instead of `include ExEscalator::Mixin`, you should `include ExEscalator.mixin`'
+        raise 'instead of `include Escalate::Mixin`, you should `include Escalate.mixin`'
       end
     end
-
-    attr_accessor :escalate_logger_block
-
-    def ex_escalate(exception, message, **context)
-      Escalate.escalate(exception, message, escalate_logger, **context)
-    end
-
-    private
-
-    def escalate_logger
-      escalate_logger_block.try(:call) || default_escalate_logger
-    end
-
-    def default_escalate_logger
-      @default_escalate_logger ||= Logger.new(STDERR)
-    end
   end
 end

data/lib/escalate/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Escalate
-  VERSION = "0.1.0.pre.1"
+  VERSION = "0.2.0.pre.3"
 end

metadata

@@ -1,15 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: escalate
 version: !ruby/object:Gem::Version
-  version: 0.1.0.pre.1
+  version: 0.2.0.pre.3
 platform: ruby
 authors:
 - Invoca Development
 - Octothorp
-autorequire:
+autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-02-01 00:00:00.000000000 Z
+date: 2021-03-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -25,21 +25,7 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-- !ruby/object:Gem::Dependency
-  name: contextual_logger
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-description: Simple gem for abstracting log escalations
+description: A simple and lightweight gem to escalate rescued exceptions.
 email:
 - development@invoca.com
 - octothorp@invoca.com
@@ -70,7 +56,7 @@ metadata:
   allowed_push_host: https://rubygems.org
   homepage_uri: https://github.com/invoca/escalate
   changelog_uri: https://github.com/invoca/escalate/blob/main/CHANGELOG.md
-post_install_message:
+post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -85,9 +71,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: 1.3.1
 requirements: []
-rubyforge_project:
-rubygems_version: 2.6.13
-signing_key:
+rubygems_version: 3.1.2
+signing_key: 
 specification_version: 4
-summary: Simple gem for abstracting log escalations
+summary: A simple and lightweight gem to escalate rescued exceptions.
 test_files: []