Deprecate the monitor_transaction helpers (#1188)

Now that we have a new Appsignal.monitor helper, deprecate the old helpers so that we can remove it in the next version of the Ruby gem.
appsignal · Jul 12, 2024 · 470d581 · 470d581
1 parent 119152d
commit 470d581
Show file tree

Hide file tree

Showing 3 changed files with 95 additions and 0 deletions.
diff --git a/.changesets/deprecate-appsignal-monitor_transaction-helper.md b/.changesets/deprecate-appsignal-monitor_transaction-helper.md
@@ -0,0 +1,6 @@
+---
+bump: patch
+type: deprecate
+---
+
+Deprecate the `Appsignal.monitor_transaction` and `Appsignal.monitor_single_transaction` helpers. See entry about the replacement helpers `Appsignal.monitor` and `Appsignal.monitor_and_stop`.
diff --git a/lib/appsignal/helpers/instrumentation.rb b/lib/appsignal/helpers/instrumentation.rb
@@ -213,6 +213,16 @@ def monitor_and_stop(action:, namespace: nil)
       # @return [Object] the value of the given block is returned.
       # @since 0.10.0
       def monitor_transaction(name, env = {}, &block)
+        stdout_and_logger_warning \
+          "The `Appsignal.monitor_transaction` helper is deprecated. " \
+            "Please use `Appsignal.monitor` and `Appsignal.instrument` instead. " \
+            "Read our instrumentation documentation: " \
+            "https://docs.appsignal.com/ruby/instrumentation/instrumentation.html"
+        _monitor_transaction(name, env, &block)
+      end
+
+      # @api private
+      def _monitor_transaction(name, env = {}, &block)
         # Always verify input, even when Appsignal is not active.
         # This makes it more likely invalid arguments get flagged in test/dev
         # environments.
@@ -258,6 +268,11 @@ def monitor_transaction(name, env = {}, &block)
       #
       # @see monitor_transaction
       def monitor_single_transaction(name, env = {}, &block)
+        stdout_and_logger_warning \
+          "The `Appsignal.monitor_single_transaction` helper is deprecated. " \
+            "Please use `Appsignal.monitor_and_stop` and `Appsignal.instrument` instead. " \
+            "Read our instrumentation documentation: " \
+            "https://docs.appsignal.com/ruby/instrumentation/instrumentation.html"
         monitor_transaction(name, env, &block)
       ensure
         stop("monitor_single_transaction")

diff --git a/spec/lib/appsignal_spec.rb b/spec/lib/appsignal_spec.rb
@@ -493,6 +493,43 @@
     end
 
     describe ".monitor_transaction" do
+      it "prints a deprecation warning" do
+        err_stream = std_stream
+        capture_std_streams(std_stream, err_stream) do
+          Appsignal.monitor_transaction(
+            "perform_job.something",
+            :class => "BackgroundJob",
+            :method => "perform"
+          ) do
+            :return_value
+          end
+        end
+
+        expect(err_stream.read).to include(
+          "appsignal WARNING: The `Appsignal.monitor_transaction` helper is deprecated."
+        )
+      end
+
+      it "logs a deprecation warning" do
+        logs =
+          capture_logs do
+            silence do
+              Appsignal.monitor_transaction(
+                "perform_job.something",
+                :class => "BackgroundJob",
+                :method => "perform"
+              ) do
+                :return_value
+              end
+            end
+          end
+
+        expect(logs).to contains_log(
+          :warn,
+          "The `Appsignal.monitor_transaction` helper is deprecated."
+        )
+      end
+
       context "with a successful call" do
         it "instruments and completes for a background job" do
           return_value = nil
@@ -582,6 +619,43 @@
     end
 
     describe ".monitor_single_transaction" do
+      it "prints a deprecation warning" do
+        err_stream = std_stream
+        capture_std_streams(std_stream, err_stream) do
+          Appsignal.monitor_single_transaction(
+            "perform_job.something",
+            :class => "BackgroundJob",
+            :method => "perform"
+          ) do
+            :return_value
+          end
+        end
+
+        expect(err_stream.read).to include(
+          "appsignal WARNING: The `Appsignal.monitor_single_transaction` helper is deprecated."
+        )
+      end
+
+      it "logs a deprecation warning" do
+        logs =
+          capture_logs do
+            silence do
+              Appsignal.monitor_single_transaction(
+                "perform_job.something",
+                :class => "BackgroundJob",
+                :method => "perform"
+              ) do
+                :return_value
+              end
+            end
+          end
+
+        expect(logs).to contains_log(
+          :warn,
+          "The `Appsignal.monitor_single_transaction` helper is deprecated."
+        )
+      end
+
       context "with a successful call" do
         it "calls monitor_transaction and Appsignal.stop" do
           expect(Appsignal).to receive(:stop)