Add ignore_instrumentation_events helper (#1176)

Rename the `without_instrumentation` helper to `ignore_instrumentation_events` to help explain what it does: only ignore instrumentation events created with the `instrument` helper. Deprecate the `without_instrumentation` helper.
appsignal · Jul 11, 2024 · 7cc3c0e · 7cc3c0e
1 parent 6d313ae
commit 7cc3c0e
Show file tree

Hide file tree

Showing 3 changed files with 63 additions and 7 deletions.
diff --git a/.changesets/deprecate--appsignal-without_instrumentation--helper-.md b/.changesets/deprecate--appsignal-without_instrumentation--helper-.md
@@ -0,0 +1,6 @@
+---
+bump: patch
+type: deprecate
+---
+
+Deprecate the `Appsignal.without_instrumentation` helper. Use the `Appsignal.ignore_instrumentation_events` helper instead.
diff --git a/lib/appsignal/helpers/instrumentation.rb b/lib/appsignal/helpers/instrumentation.rb
@@ -870,22 +870,48 @@ def instrument_sql(name, title = nil, body = nil, &block)
         )
       end
 
-      # Convenience method for skipping instrumentations around a block of code.
+      # Convenience method for ignoring instrumentation events in a block of
+      # code.
+      #
+      # - This helper ignores events, like those created
+      #   `Appsignal.instrument`, within this block.
+      #   This includes custom instrumentation and events recorded by AppSignal
+      #   integrations for requests, database queries, view rendering, etc.
+      # - The time spent in the block is still reported on the transaction.
+      # - Errors and metrics are reported from within this block.
       #
       # @example
-      #   Appsignal.without_instrumentation do
+      #   Appsignal.instrument "my_event.my_group" do
       #     # Complex code here
       #   end
+      #   Appsignal.ignore_instrumentation_events do
+      #     Appsignal.instrument "my_ignored_event.my_ignored_group" do
+      #       # Complex code here
+      #     end
+      #   end
+      #
+      #   # Only the "my_event.my_group" instrumentation event is reported.
       #
       # @yield block of code that shouldn't be instrumented.
       # @return [Object] Returns the return value of the block.
-      # @since 0.8.7
-      def without_instrumentation
+      # @since 3.10.0
+      # @see https://docs.appsignal.com/ruby/instrumentation/ignore-instrumentation.html
+      #   Ignore instrumentation guide
+      def ignore_instrumentation_events
         Appsignal::Transaction.current&.pause!
         yield
       ensure
         Appsignal::Transaction.current&.resume!
       end
+
+      # @deprecated Use {.ignore_instrumentation_events} instead.
+      # @since 0.8.7
+      def without_instrumentation(&block)
+        stdout_and_logger_warning \
+          "The `Appsignal.without_instrumentation` helper is deprecated. " \
+            "Please use `Appsignal.ignore_instrumentation_events` instead."
+        ignore_instrumentation_events(&block)
+      end
     end
   end
 end
diff --git a/spec/lib/appsignal_spec.rb b/spec/lib/appsignal_spec.rb
@@ -1349,7 +1349,7 @@
       end
     end
 
-    describe ".without_instrumentation" do
+    describe ".ignore_instrumentation_events" do
       around { |example| keep_transactions { example.run } }
       let(:transaction) { http_request_transaction }
 
@@ -1361,20 +1361,44 @@
           expect(transaction).to receive(:resume!).and_call_original
 
           Appsignal.instrument("register.this.event") { :do_nothing }
-          Appsignal.without_instrumentation do
+          Appsignal.ignore_instrumentation_events do
             Appsignal.instrument("dont.register.this.event") { :do_nothing }
           end
 
           expect(transaction).to include_event("name" => "register.this.event")
           expect(transaction).to_not include_event("name" => "dont.register.this.event")
         end
+
+        it "has a without_instrumentation alias that prints a deprecation warning" do
+          Appsignal.instrument("register.this.event") { :do_nothing }
+          err_stream = std_stream
+          logs =
+            capture_logs do
+              capture_std_streams(std_stream, err_stream) do
+                Appsignal.without_instrumentation do
+                  Appsignal.instrument("dont.register.this.event") { :do_nothing }
+                end
+              end
+            end
+
+          expect(transaction).to include_event("name" => "register.this.event")
+          expect(transaction).to_not include_event("name" => "dont.register.this.event")
+
+          expect(logs).to contains_log(
+            :warn,
+            "The `Appsignal.without_instrumentation` helper is deprecated."
+          )
+          expect(err_stream.read).to include(
+            "appsignal WARNING: The `Appsignal.without_instrumentation` helper is deprecated."
+          )
+        end
       end
 
       context "without current transaction" do
         let(:transaction) { nil }
 
         it "does not crash" do
-          Appsignal.without_instrumentation { :do_nothing }
+          Appsignal.ignore_instrumentation_events { :do_nothing }
         end
       end
     end