Document Appsignal.set_empty_params! helper method

.changesets/add-set_empty_params--helper-method.md

@@ -0,0 +1,41 @@
+---
+bump: patch
+type: add
+---
+
+Add `Appsignal.set_empty_params!` helper method. This helper method can be used to unset parameters on a transaction and to prevent the Appsignal instrumentation from adding parameters to a transaction.
+
+Example usage:
+
+```ruby
+class PaymentsController < ApplicationController
+  def create
+    Appsignal.set_empty_params!
+
+    # Do things with sensitive parameters
+  end
+end
+```
+
+When `Appsignal.add_params` is called afterward, the "empty parameters" state is cleared and any AppSignal instrumentation (if called afterward) will also add parameters again.
+
+```ruby
+# Example: Unset parameters when set
+Appsignal.add_params("abc" => "def")
+# Parameters: { "abc" => "def" }
+Appsignal.set_empty_params!
+# Parameters: {}
+
+# Example: When AppSignal instrumentation sets parameters:
+Appsignal.set_empty_params!
+# Parameters: {}
+# Pseudo example code:
+Appsignal::Instrumentation::SomeLibrary.new.add_params("xyz" => "...")
+# Parameters: {}
+
+# Example: Set parameters after them being unset previously
+Appsignal.set_empty_params!
+# Parameters: {}
+Appsignal.add_params("abc" => "def")
+# Parameters: { "abc" => "def" }
+```

lib/appsignal.rb

@@ -222,7 +222,7 @@ def stop(called_by = nil)
     #   # Or for the environment given as an argument
     #   Appsignal.configure(:production)
     #
-    # @param env [String, Symbol] The environment to load.
+    # @param env_param [String, Symbol] The environment to load.
     # @param root_path [String] The path to look the `config/appsignal.yml` config file in.
     #   Defaults to the current working directory.
     # @yield [Config] Gives the {Config} instance to the block.

lib/appsignal/helpers/instrumentation.rb

@@ -556,11 +556,20 @@ def add_params(params = nil, &block)
 
       # Mark the parameters sample data to be set as an empty value.
       #
-      # @api private
-      # @since 4.0.0
+      # Use this helper to unset request parameters / background job arguments
+      # and not report any for this transaction.
+      #
+      # If parameters would normally be added by AppSignal instrumentations of
+      # libraries, these parameters will not be added to the Transaction.
+      #
+      # Calling {#add_params} after this helper will add new parameters to the
+      # transaction.
+      #
+      # @since 4.2.0
       # @return [void]
       #
-      # @see Helpers::Instrumentation#set_empty_params!
+      # @see Transaction#set_empty_params!
+      # @see Transaction#set_params_if_nil
       def set_empty_params!
         return unless active?
         return unless Appsignal::Transaction.current?