Deprecate monitor_and_stop helper (#1401)

Deprecate this helper. It causes confusion in use, so let's recommend
using the new `enable_at_exit_hook` config option instead.

Closes #1387

Author: tombruijn

.changesets/deprecate-monitor_and_stop-helper.md

@@ -0,0 +1,8 @@
+---
+bump: patch
+type: deprecate
+---
+
+Deprecate the `Appsignal.monitor_and_stop` helper.
+
+We instead recommend using the `Appsignal.monitor` helper and configuring the `enable_at_exit_hook` config option to `always`.

lib/appsignal/helpers/instrumentation.rb

@@ -154,6 +154,11 @@ def monitor(action:, namespace: nil)
       #
       # @see monitor
       def monitor_and_stop(action:, namespace: nil, &block)
+        Appsignal::Utils::StdoutAndLoggerMessage.warning \
+          "The `Appsignal.monitor_and_stop` helper is deprecated. " \
+            "Use the `Appsignal.monitor` along with our `enable_at_exit_hook` " \
+            "option instead."
+
         monitor(:namespace => namespace, :action => action, &block)
       ensure
         Appsignal.stop("monitor_and_stop")

spec/lib/appsignal_spec.rb

@@ -1170,19 +1170,30 @@ def on_start
     describe ".monitor_and_stop" do
       it "calls Appsignal.stop after the block" do
         allow(Appsignal).to receive(:stop)
-        Appsignal.monitor_and_stop(:namespace => "custom", :action => "My Action")
+        err_stream = std_stream
+        logs =
+          capture_logs do
+            capture_std_streams(std_stream, err_stream) do
+              Appsignal.monitor_and_stop(:namespace => "custom", :action => "My Action")
+            end
+          end
 
         transaction = last_transaction
         expect(transaction).to have_namespace("custom")
         expect(transaction).to have_action("My Action")
         expect(transaction).to be_completed
 
         expect(Appsignal).to have_received(:stop).with("monitor_and_stop")
+        message = "The `Appsignal.monitor_and_stop` helper is deprecated."
+        expect(logs).to contains_log(:warn, message)
+        expect(err_stream.read).to include("appsignal WARNING: #{message}")
       end
 
       it "passes the block to Appsignal.monitor" do
         expect do |blk|
-          Appsignal.monitor_and_stop(:action => "My action", &blk)
+          silence do
+            Appsignal.monitor_and_stop(:action => "My action", &blk)
+          end
         end.to yield_control
       end
     end