escalate 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: ca403c35fe8123ebf15d068d392789e5de418f71
-  data.tar.gz: df6eb4d755258ce4e6d3617ca88075266e591acc
+SHA256:
+  metadata.gz: 367073142399930c67886a1890af1e684d767a11c62d3719fd95ecd392a4c47d
+  data.tar.gz: 368728d4e4db7d3e466571c563902e096093310685ffffc64c1906b05d95338e
 SHA512:
-  metadata.gz: aae531b8f6fc1f8bb4e52a2cbf1ff613fd74f19298ca18aca77936f6e44b741c9ce42b02817bcfb755379d95c6e577342b1a17af0a387e66a00348baf96a3703
-  data.tar.gz: 2d4c26aad91e60c1c2b192b66d6f332db6a858b7f06588788f5b166d41912a8daa27cac39d166ac3cea7e770417037062add542bf36f4429a8c0cc8f0ad74a7b
+  metadata.gz: 59605b0ed9a30982a6e6dc92d37c20578b4b52c643361a8b6e7ac2876579ade371c0b528f156de8da92502f7002d66f515c467f8fe5e4a5038580d506f174d08
+  data.tar.gz: 0a24440c7988110d5cacc07bd6ec262074de501938c4076e29bea9607ee38d4d6c19f424086f81fd09ef9266e65f65a9f39b6f9ca36018fcbe9f9688041d820e

data/CHANGELOG.md

@@ -4,10 +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.2.0] - 2021-03-02
+### 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.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    escalate (0.1.0)
+    escalate (0.2.0)
       activesupport
 
 GEM
@@ -49,6 +49,7 @@ GEM
       thread_safe (~> 0.1)
 
 PLATFORMS
+  ruby
   x86_64-darwin-19
 
 DEPENDENCIES

data/README.md

@@ -58,8 +58,44 @@ 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
+```
+
+#### Callback Uniqueness
+Each callback may be named with the `name:` keyword argument.
+If a callback with the same name has been registered before, it will be overwritten with the new one.
+```
+Escalate.on_escalate(name: 'abc gem') do |exception, location_message, **context|
+  # send exception, location_message, **context to the error reporting service here
+end
+```
+If not given, the `name:` defaults to the `.source_location` property of the passed-in block.
+
+#### 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/lib/escalate.rb

@@ -9,37 +9,46 @@ require_relative "escalate/mixin"
 module Escalate
   class Error < StandardError; end
 
+  LOG_FIRST_INSTANCE_VARIABLE = :@_escalate_log_first
+
+  @on_escalate_callbacks = {}
+
   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)
+    def escalate(exception, location_message, logger, **context)
       ensure_failsafe("Exception rescued while escalating #{exception.inspect}") do
-        error_message = <<~EOS
-          [Escalate] #{message} (#{context.inspect})
+        if on_escalate_callbacks.none? || on_escalate_callbacks.values.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
+          EOS
 
-        if logger_allows_added_context?(logger)
-          logger.error(error_message, **context)
-        else
-          logger.error(error_message)
+          if context_string
+            logger.error(error_message)
+          else
+            logger.error(error_message, **context)
+          end
         end
 
-        on_escalate_blocks.each do |block|
+        on_escalate_callbacks.values.each do |block|
           ensure_failsafe("Exception rescued while escalating #{exception.inspect} to #{block.inspect}") do
-            block.call(exception, message, **context)
+            block.call(exception, location_message, **context)
           end
         end
       end
@@ -63,8 +72,8 @@ module Escalate
 
         attr_accessor :escalate_logger_block
 
-        def escalate(exception, message, **context)
-          Escalate.escalate(exception, message, escalate_logger, **context)
+        def escalate(exception, location_message, **context)
+          Escalate.escalate(exception, location_message, escalate_logger, **context)
         end
 
         private
@@ -79,10 +88,21 @@ module Escalate
       end
     end
 
-    # Registers an escalation callback to be executed when `escalate`
-    # is invoked.
-    def on_escalate(&block)
-      on_escalate_blocks.add(block)
+    # Registers an escalation callback to be executed when `escalate` is invoked.
+    #
+    # @param [boolean] log_first: true
+    #   whether escalate should log first before escalating, or leave the logging to the escalate block
+    # @param [string | Array] name:
+    #   unique name for this callback block
+    #   any previously-registered block with the same name will be discarded
+    #   if not provided, name defaults to `block.source_location`
+    def on_escalate(log_first: true, name: nil, &block)
+      block.instance_variable_set(LOG_FIRST_INSTANCE_VARIABLE, log_first)
+      on_escalate_callbacks[name || block.source_location] = block
+    end
+
+    def clear_on_escalate_callbacks
+      on_escalate_callbacks.clear
     end
 
     private
@@ -97,9 +117,5 @@ module Escalate
       defined?(ContextualLogger::LoggerMixin) &&
         logger.is_a?(ContextualLogger::LoggerMixin)
     end
-
-    def on_escalate_blocks
-      @on_escalate_blocks ||= Set.new
-    end
   end
 end

data/lib/escalate/version.rb

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

metadata

@@ -1,15 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: escalate
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Invoca Development
 - Octothorp
-autorequire:
+autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-02-03 00:00:00.000000000 Z
+date: 2021-03-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -56,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
@@ -71,9 +71,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project:
-rubygems_version: 2.6.13
-signing_key:
+rubygems_version: 3.1.2
+signing_key: 
 specification_version: 4
 summary: A simple and lightweight gem to escalate rescued exceptions.
 test_files: []