Add before_complete transaction hook

Add a `before_complete` transaction hook, which is executed right
before a transaction is completed. Note that, for transactions
containing multiple errors, this hook is called once for each of
the duplicate transactions that is used to report each of the
errors. This allows the context to be customised for each error.

Author: unflxw

lib/appsignal/transaction.rb

@@ -48,7 +48,8 @@ def create(namespace)
       # @return [Array<Proc>]
       # Add a block, if given, to be executed after a transaction is created.
       # The block will be called with the transaction as an argument.
-      # Returns the array of blocks that will be executed.
+      # Returns the array of blocks that will be executed after a transaction
+      # is created.
       def after_create(&block)
         @after_create ||= Set.new
 
@@ -57,6 +58,26 @@ def after_create(&block)
         @after_create << block
       end
 
+      # @api private
+      # @return [Array<Proc>]
+      # Add a block, if given, to be executed before a transaction is completed.
+      # This happens after duplicating the transaction for each error that was
+      # reported in the transaction -- that is, when a transaction with
+      # several errors is completed, the block will be called once for each
+      # error, with the transaction (either the original one or a duplicate of it)
+      # that has each of the errors set.
+      # The block will be called with the transaction as the first argument,
+      # and the error reported by the transaction, if any, as the second argument.
+      # Returns the array of blocks that will be executed before a transaction is
+      # completed.
+      def before_complete(&block)
+        @before_complete ||= Set.new
+
+        return @before_complete if block.nil?
+
+        @before_complete << block
+      end
+
       # @api private
       def set_current_transaction(transaction)
         Thread.current[:appsignal_transaction] = transaction
@@ -208,6 +229,9 @@ def complete
         end
       end
       sample_data if should_sample
+
+      run_before_complete_hooks
+
       @ext.complete
     end
 
@@ -617,6 +641,12 @@ def run_after_create_hooks
       end
     end
 
+    def run_before_complete_hooks
+      self.class.before_complete.each do |block|
+        block.call(self, @error_set)
+      end
+    end
+
     def _set_error(error)
       backtrace = cleaned_backtrace(error.backtrace)
       @ext.set_error(

spec/lib/appsignal/transaction_spec.rb

@@ -2217,6 +2217,141 @@ def to_s
     end
   end
 
+  describe "#before_complete" do
+    it "stores the given hook when passed as a block" do
+      expect(Appsignal::Transaction.before_complete).to be_empty
+      Appsignal::Transaction.before_complete do |transaction, error|
+        transaction.set_action(error.message)
+      end
+
+      expect(Appsignal::Transaction.before_complete).to_not be_empty
+
+      transaction = new_transaction
+      error = ExampleStandardError.new("hook_error")
+
+      expect(transaction).to_not have_action("hook_error")
+      Appsignal::Transaction.before_complete.first.call(transaction, error)
+      expect(transaction).to have_action("hook_error")
+    end
+
+    it "stores the given hook when using <<" do
+      expect(Appsignal::Transaction.before_complete).to be_empty
+      proc = proc do |transaction, error|
+        transaction.set_action(error.message)
+      end
+
+      Appsignal::Transaction.before_complete << proc
+
+      expect(Appsignal::Transaction.before_complete).to eq(Set.new([proc]))
+    end
+
+    it "only stores a hook once when added several times" do
+      expect(Appsignal::Transaction.before_complete).to be_empty
+      proc = proc do |transaction|
+        transaction.set_action("hook_action")
+      end
+
+      Appsignal::Transaction.before_complete(&proc)
+      Appsignal::Transaction.before_complete << proc
+
+      expect(Appsignal::Transaction.before_complete).to eq(Set.new([proc]))
+    end
+
+    context "when the transaction has an error" do
+      it "calls the given hook with the error when a transaction is completed" do
+        block = proc do |transaction, error|
+          transaction.set_action(error.message)
+        end
+
+        Appsignal::Transaction.before_complete(&block)
+
+        transaction = new_transaction
+        error = ExampleStandardError.new("hook_error")
+        transaction.set_error(error)
+
+        expect(block).to(
+          receive(:call)
+            .with(transaction, error)
+            .and_call_original
+        )
+
+        transaction.complete
+
+        expect(transaction).to have_action("hook_error")
+      end
+    end
+
+    context "when the transaction has several errors" do
+      it "calls the given hook for each of the duplicate error transactions" do
+        block = proc do |transaction, error|
+          transaction.set_action(error.message)
+        end
+
+        Appsignal::Transaction.before_complete(&block)
+
+        transaction = new_transaction
+        first_error = ExampleStandardError.new("hook_error_first")
+        transaction.set_error(first_error)
+
+        second_error = ExampleStandardError.new("hook_error_second")
+        transaction.set_error(second_error)
+
+        transaction.complete
+
+        expect(created_transactions.length).to eq(2)
+
+        expect(created_transactions.find { |t| t == transaction }).to(
+          have_action("hook_error_first")
+        )
+        expect(created_transactions.find { |t| t != transaction }).to(
+          have_action("hook_error_second")
+        )
+      end
+    end
+
+    context "when the transaction does not have an error" do
+      it "calls the given hook with nil when a transaction is completed" do
+        block = proc do |transaction|
+          transaction.set_action("hook_action")
+        end
+
+        Appsignal::Transaction.before_complete(&block)
+
+        transaction = new_transaction
+
+        expect(block).to(
+          receive(:call)
+            .with(transaction, nil)
+            .and_call_original
+        )
+
+        transaction.complete
+
+        expect(transaction).to have_action("hook_action")
+      end
+    end
+
+    it "calls all the hooks in order" do
+      Appsignal::Transaction.before_complete do |transaction, error|
+        transaction.set_namespace(error.message)
+        transaction.set_action("hook_action_1")
+      end
+
+      Appsignal::Transaction.before_complete do |transaction, error|
+        transaction.set_action(error.message)
+      end
+
+      transaction = new_transaction
+      error = ExampleStandardError.new("hook_error")
+      transaction.set_error(error)
+
+      transaction.complete
+
+      expect(transaction).to have_namespace("hook_error")
+      expect(transaction).to have_action("hook_error")
+    end
+  end
+
   describe "#start_event" do
     let(:transaction) { new_transaction }
 

spec/spec_helper.rb

@@ -101,6 +101,7 @@ def spec_system_tmp_dir
     Appsignal::Loaders.clear!
     Appsignal::CheckIn.clear!
     Appsignal::Transaction.after_create.clear
+    Appsignal::Transaction.before_complete.clear
 
     clear_current_transaction!
     stop_minutely_probes