escalate 0.2.0.pre.2 → 0.2.0.pre.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8e6dc6ba580b590c324c351001687805582d7a2d757cb7aebeaed1a6ee50d07b
-  data.tar.gz: '02439935ba7a19a8c68b5ff0adcad892d658b29a2f843311a79a798fa090fac2'
+  metadata.gz: 67b615521fd3e15a59bb8401486496175afa19be36a98c415d9eccf52dd0815f
+  data.tar.gz: 951d5afc0052cde73fca383e23dc38aa63e759fce7f4863b2093e9bf9b2463b4
 SHA512:
-  metadata.gz: 39d9cb26ed59b9eca7f0a234ed2ead5375ae2144128098b6cd74bbabe54cdd6281278baaf12cf186a4873c9bf50092f5440e4e10931da33f606bca344f76edd6
-  data.tar.gz: d9608ff9899f52a7a99a2e26937340b3909d4715e9f5dbd68bdb7474fbe2782c7419f277ef3ab3d21d931a4fa9ad656b877929796707003fb01b771e8910370f
+  metadata.gz: 7979594ec79d527e123efb08114d602ab11446d8e822a9a716b582150d7e0f4b97840443974270177d861d874fbf4544f7e14eb8bd5e98e66acc86d49b51e19a
+  data.tar.gz: 2ab19d1367350559290fb9603e7af73934fcf1085121bf5a1cebe03059d450d19e53f76dc9947d92fac8a06f2a08fc0bb6ed12d0135a1e09617c87c6835dc158

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    escalate (0.2.0.pre.2)
+    escalate (0.2.0.pre.3)
       activesupport
 
 GEM

data/README.md

@@ -58,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/lib/escalate.rb

@@ -11,7 +11,11 @@ module Escalate
 
   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
@@ -27,21 +31,22 @@ module Escalate
     #   Any additional context to be tied to the escalation
     def escalate(exception, location_message, logger, **context)
       ensure_failsafe("Exception rescued while escalating #{exception.inspect}") do
-        if on_escalate_blocks.none? || on_escalate_blocks.any? { |block| block.instance_variable_get(LOG_FIRST_INSTANCE_VARIABLE) }
+        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.inspect})
+            [Escalate] #{location_message}#{context_string}
             #{exception.class.name}: #{exception.message}
             #{exception.backtrace.join("\n")}
           EOS
 
-          if logger_allows_added_context?(logger)
-            logger.error(error_message, **context)
-          else
+          if context_string
             logger.error(error_message)
+          else
+            logger.error(error_message, **context)
           end
         end
 
-        on_escalate_blocks.each do |block|
+        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
@@ -90,11 +95,11 @@ module Escalate
     #   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_blocks.add(block)
+      on_escalate_callbacks.add(block)
     end
 
     def clear_on_escalate_callbacks
-      on_escalate_blocks.clear
+      on_escalate_callbacks.clear
     end
 
     private
@@ -109,9 +114,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.2.0.pre.2"
+  VERSION = "0.2.0.pre.3"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: escalate
 version: !ruby/object:Gem::Version
-  version: 0.2.0.pre.2
+  version: 0.2.0.pre.3
 platform: ruby
 authors:
 - Invoca Development
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-02-25 00:00:00.000000000 Z
+date: 2021-03-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport