appsignal 3.13.0-java → 4.0.0.beta.2-java

data/lib/appsignal/helpers/instrumentation.rb

@@ -3,8 +3,6 @@
 module Appsignal
   module Helpers
     module Instrumentation
-      include Appsignal::Utils::StdoutAndLoggerMessage
-
       # Monitor a block of code with AppSignal.
       #
       # This is a helper to create an AppSignal transaction, track any errors
@@ -69,8 +67,8 @@ module Appsignal
       #   ) do
       #     # Some code
       #
-      #     Appsignal.set_tags(:tag1 => "value1", :tag2 => "value2")
-      #     Appsignal.set_params(:param1 => "value1", :param2 => "value2")
+      #     Appsignal.add_tags(:tag1 => "value1", :tag2 => "value2")
+      #     Appsignal.add_params(:param1 => "value1", :param2 => "value2")
       #   end
       #
       # @example Call monitor within monitor will do nothing
@@ -117,7 +115,7 @@ module Appsignal
         if has_parent_transaction
           callers = caller
           Appsignal::Utils::StdoutAndLoggerMessage.warning \
-            "An active transaction around this 'Appsignal.monitor' call. " \
+            "A transaction is active around this 'Appsignal.monitor' call. " \
               "Calling `Appsignal.monitor` in another `Appsignal.monitor` block has no effect. " \
               "The namespace and action are not updated for the active transaction." \
               "Did you mean to use `Appsignal.instrument`? " \
@@ -160,173 +158,6 @@ module Appsignal
         Appsignal.stop("monitor_and_stop")
       end
 
-      # Creates an AppSignal transaction for the given block.
-      #
-      # If AppSignal is not {Appsignal.active?} it will still execute the
-      # block, but not create a transaction for it.
-      #
-      # A event is created for this transaction with the name given in the
-      # `name` argument. The event name must start with either `perform_job` or
-      # `process_action` to differentiate between the "web" and "background"
-      # namespace. Custom namespaces are not supported by this helper method.
-      #
-      # This helper method also captures any exception that occurs in the given
-      # block.
-      #
-      # @example
-      #   Appsignal.monitor_transaction("perform_job.nightly_update") do
-      #     # your code
-      #   end
-      #
-      # @example with an environment
-      #   Appsignal.monitor_transaction(
-      #     "perform_job.nightly_update",
-      #     :metadata => { "user_id" => 1 }
-      #   ) do
-      #     # your code
-      #   end
-      #
-      # @param name [String] main event name.
-      # @param env [Hash<Symbol, Object>]
-      # @option env [Hash<Symbol/String, Object>] :params Params for the
-      #   monitored request/job, see {Appsignal::Transaction#params=} for more
-      #   information.
-      # @option env [String] :controller name of the controller in which the
-      #   transaction was recorded.
-      # @option env [String] :class name of the Ruby class in which the
-      #   transaction was recorded. If `:controller` is also given,
-      #   `:controller` is used instead.
-      # @option env [String] :action name of the controller action in which the
-      #   transaction was recorded.
-      # @option env [String] :method name of the Ruby method in which the
-      #   transaction was recorded. If `:action` is also given, `:action`
-      #   is used instead.
-      # @option env [Integer] :queue_start the moment the request/job was
-      #   queued. Used to track how long requests/jobs were queued before being
-      #   executed.
-      # @option env [Hash<Symbol/String, String/Fixnum>] :metadata Additional
-      #   metadata for the transaction, see
-      #   {Appsignal::Transaction#set_metadata} for more information.
-      # @yield the block to monitor.
-      # @raise [Exception] any exception that occurs within the given block is
-      #   re-raised by this method.
-      # @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.
-        if name.start_with?("perform_job")
-          namespace = Appsignal::Transaction::BACKGROUND_JOB
-          request   = Appsignal::Transaction::InternalGenericRequest.new(env)
-        elsif name.start_with?("process_action")
-          namespace = Appsignal::Transaction::HTTP_REQUEST
-          request   = ::Rack::Request.new(env)
-        else
-          internal_logger.error "Unrecognized name '#{name}': names must " \
-            "start with either 'perform_job' (for jobs and tasks) or " \
-            "'process_action' (for HTTP requests)"
-          return yield
-        end
-
-        return yield unless active?
-
-        transaction = Appsignal::Transaction.create(
-          SecureRandom.uuid,
-          namespace,
-          request
-        )
-        begin
-          Appsignal.instrument(name, &block)
-        rescue Exception => error # rubocop:disable Lint/RescueException
-          transaction.set_error(error)
-          raise error
-        ensure
-          transaction.set_http_or_background_action(request.env)
-          queue_start = Appsignal::Rack::Utils.queue_start_from(request.env) ||
-            (env[:queue_start]&.to_i&.* 1_000)
-          transaction.set_queue_start(queue_start) if queue_start
-          Appsignal::Transaction.complete_current!
-        end
-      end
-
-      # Monitor a transaction, stop AppSignal and wait for this single
-      # transaction to be flushed.
-      #
-      # Useful for cases such as Rake tasks and Resque-like systems where a
-      # process is forked and immediately exits after the transaction finishes.
-      #
-      # @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")
-      end
-
-      # Listen for an error to occur and send it to AppSignal.
-      #
-      # Uses {.send_error} to directly send the error in a separate
-      # transaction. Does not add the error to the current transaction.
-      #
-      # Make sure that AppSignal is integrated in your application beforehand.
-      # AppSignal won't record errors unless {Appsignal.active?} is `true`.
-      #
-      # @example
-      #   # my_app.rb
-      #   # setup AppSignal beforehand
-      #
-      #   Appsignal.listen_for_error do
-      #     # my code
-      #     raise "foo"
-      #   end
-      #
-      # @see Transaction.set_tags
-      # @see Transaction.set_namespace
-      # @see .send_error
-      # @see https://docs.appsignal.com/ruby/instrumentation/integrating-appsignal.html
-      #   AppSignal integration guide
-      # @see https://docs.appsignal.com/ruby/instrumentation/exception-handling.html
-      #   Exception handling guide
-      #
-      # @deprecated Use `rescue => error` with {.report_error} instead.
-      # @param tags [Hash, nil]
-      # @param namespace [String] the namespace for this error.
-      # @yield yields the given block.
-      # @return [Object] returns the return value of the given block.
-      def listen_for_error(
-        tags = nil,
-        namespace = Appsignal::Transaction::HTTP_REQUEST
-      )
-        stdout_and_logger_warning \
-          "The `Appsignal.listen_for_error` helper is deprecated. " \
-            "Please use `rescue => error` and `Appsignal.report_error` instead. " \
-            "Read our exception handling documentation: " \
-            "https://docs.appsignal.com/ruby/instrumentation/exception-handling.html"
-        yield
-      rescue Exception => error # rubocop:disable Lint/RescueException
-        send_error(error) do |transaction|
-          transaction.set_tags(tags) if tags
-          transaction.set_namespace(namespace) if namespace
-        end
-        raise error
-      end
-      alias :listen_for_exception :listen_for_error
-
       # Send an error to AppSignal regardless of the context.
       #
       # Records and send the exception to AppSignal.
@@ -347,28 +178,15 @@ module Appsignal
       #     Appsignal.send_error(e)
       #   end
       #
-      # @example Send an exception with tags. Deprecated method.
-      #   begin
-      #     raise "oh no!"
-      #   rescue => e
-      #     Appsignal.send_error(e, :key => "value")
-      #   end
-      #
       # @example Add more metadata to transaction
-      #   Appsignal.send_error(e) do |transaction|
-      #     transaction.set_params(:search_query => params[:search_query])
-      #     transaction.set_action("my_action_name")
-      #     transaction.set_tags(:key => "value")
-      #     transaction.set_namespace("my_namespace")
+      #   Appsignal.send_error(e) do
+      #     Appsignal.set_namespace("my_namespace")
+      #     Appsignal.set_action("my_action_name")
+      #     Appsignal.add_params(:search_query => params[:search_query])
+      #     Appsignal.add_tags(:key => "value")
       #   end
       #
       # @param error [Exception] The error to send to AppSignal.
-      # @param tags [Hash{String, Symbol => String, Symbol, Integer}]
-      #   Additional tags to add to the error. See also {.tag_request}.
-      #   This parameter is deprecated. Use the block argument instead.
-      # @param namespace [String] The namespace in which the error occurred.
-      #   See also {.set_namespace}.
-      #   This parameter is deprecated. Use the block argument instead.
       # @yield [transaction] yields block to allow modification of the
       #   transaction before it's send.
       # @yieldparam transaction [Transaction] yields the AppSignal transaction
@@ -381,31 +199,7 @@ module Appsignal
       # @see https://docs.appsignal.com/ruby/instrumentation/tagging.html
       #   Tagging guide
       # @since 0.6.0
-      def send_error(
-        error,
-        tags = nil,
-        namespace = nil
-      )
-        if tags
-          call_location = caller(1..1).first
-          stdout_and_logger_warning \
-            "The tags argument for `Appsignal.send_error` is deprecated. " \
-              "Please use the block method to set tags instead.\n\n" \
-              "  Appsignal.send_error(error) do |transaction|\n" \
-              "    transaction.set_tags(#{tags})\n" \
-              "  end\n\n" \
-              "Appsignal.send_error called on location: #{call_location}"
-        end
-        if namespace
-          call_location = caller(1..1).first
-          stdout_and_logger_warning \
-            "The namespace argument for `Appsignal.send_error` is deprecated. " \
-              "Please use the block method to set the namespace instead.\n\n" \
-              "  Appsignal.send_error(error) do |transaction|\n" \
-              "    transaction.set_namespace(#{namespace.inspect})\n" \
-              "  end\n\n" \
-              "Appsignal.send_error called on location: #{call_location}"
-        end
+      def send_error(error, &block)
         return unless active?
 
         unless error.is_a?(Exception)
@@ -413,13 +207,13 @@ module Appsignal
             "The given value is not an exception: #{error.inspect}"
           return
         end
+
         transaction = Appsignal::Transaction.new(
           SecureRandom.uuid,
-          namespace || Appsignal::Transaction::HTTP_REQUEST
+          Appsignal::Transaction::HTTP_REQUEST
         )
-        transaction.set_tags(tags) if tags
-        transaction.set_error(error)
-        yield transaction if block_given?
+        transaction.set_error(error, &block)
+
         transaction.complete
       end
       alias :send_exception :send_error
@@ -452,21 +246,15 @@ module Appsignal
       #   end
       #
       # @example Add more metadata to transaction
-      #   Appsignal.set_error(e) do |transaction|
-      #     transaction.set_params(:search_query => params[:search_query])
-      #     transaction.set_action("my_action_name")
-      #     transaction.set_tags(:key => "value")
-      #     transaction.set_namespace("my_namespace")
+      #   Appsignal.set_error(e) do
+      #     Appsignal.set_namespace("my_namespace")
+      #     Appsignal.set_action("my_action_name")
+      #     Appsignal.add_params(:search_query => params[:search_query])
+      #     Appsignal.add_tags(:key => "value")
       #   end
       #
       # @param exception [Exception] The error to add to the current
       #   transaction.
-      # @param tags [Hash{String, Symbol => String, Symbol, Integer}]
-      #   Additional tags to add to the error. See also {.tag_request}.
-      #   This parameter is deprecated. Use the block argument instead.
-      # @param namespace [String] The namespace in which the error occurred.
-      #   See also {.set_namespace}.
-      #   This parameter is deprecated. Use the block argument instead.
       # @yield [transaction] yields block to allow modification of the
       #   transaction.
       # @yieldparam transaction [Transaction] yields the AppSignal transaction
@@ -478,27 +266,7 @@ module Appsignal
       # @see https://docs.appsignal.com/ruby/instrumentation/exception-handling.html
       #   Exception handling guide
       # @since 0.6.6
-      def set_error(exception, tags = nil, namespace = nil)
-        if tags
-          call_location = caller(1..1).first
-          stdout_and_logger_warning \
-            "The tags argument for `Appsignal.set_error` is deprecated. " \
-              "Please use the block method to set tags instead.\n\n" \
-              "  Appsignal.set_error(error) do |transaction|\n" \
-              "    transaction.set_tags(#{tags})\n" \
-              "  end\n\n" \
-              "Appsignal.set_error called on location: #{call_location}"
-        end
-        if namespace
-          call_location = caller(1..1).first
-          stdout_and_logger_warning \
-            "The namespace argument for `Appsignal.set_error` is deprecated. " \
-              "Please use the block method to set the namespace instead.\n\n" \
-              "  Appsignal.set_error(error) do |transaction|\n" \
-              "    transaction.set_namespace(#{namespace.inspect})\n" \
-              "  end\n\n" \
-              "Appsignal.set_error called on location: #{call_location}"
-        end
+      def set_error(exception)
         unless exception.is_a?(Exception)
           internal_logger.error "Appsignal.set_error: Cannot set error. " \
             "The given value is not an exception: #{exception.inspect}"
@@ -508,8 +276,6 @@ module Appsignal
 
         transaction = Appsignal::Transaction.current
         transaction.set_error(exception)
-        transaction.set_tags(tags) if tags
-        transaction.set_namespace(namespace) if namespace
         yield transaction if block_given?
       end
       alias :set_exception :set_error
@@ -536,11 +302,11 @@ module Appsignal
       #   end
       #
       # @example Add more metadata to transaction
-      #   Appsignal.report_error(error) do |transaction|
-      #     transaction.set_namespace("my_namespace")
-      #     transaction.set_action("my_action_name")
-      #     transaction.set_params(:search_query => params[:search_query])
-      #     transaction.set_tags(:key => "value")
+      #   Appsignal.report_error(error) do
+      #     Appsignal.set_namespace("my_namespace")
+      #     Appsignal.set_action("my_action_name")
+      #     Appsignal.add_params(:search_query => params[:search_query])
+      #     Appsignal.add_tags(:key => "value")
       #   end
       #
       # @param exception [Exception] The error to add to the current
@@ -554,9 +320,9 @@ module Appsignal
       # @see https://docs.appsignal.com/ruby/instrumentation/exception-handling.html
       #   Exception handling guide
       # @since 3.10.0
-      def report_error(exception)
+      def report_error(exception, &block)
         unless exception.is_a?(Exception)
-          internal_logger.error "Appsignal.report_error: Cannot set error. " \
+          internal_logger.error "Appsignal.report_error: Cannot add error. " \
             "The given value is not an exception: #{exception.inspect}"
           return
         end
@@ -573,12 +339,9 @@ module Appsignal
             )
           end
 
-        transaction.set_error(exception)
-        yield transaction if block_given?
-
-        return if has_parent_transaction
+        transaction.add_error(exception, &block)
 
-        transaction.complete
+        transaction.complete unless has_parent_transaction
       end
       alias :report_exception :report_error
 
@@ -652,36 +415,56 @@ module Appsignal
         Appsignal::Transaction.current.set_namespace(namespace)
       end
 
-      # Set custom data on the current transaction.
+      # Add custom data to the current transaction.
       #
       # Add extra information about the request or background that cannot be
       # expressed in tags, like nested data structures.
       #
-      # When this method is called multiple times, it will overwrite the
-      # previously set value.
+      # If the root data type changes between calls of this method, the last
+      # method call is stored.
       #
-      # @example
-      #   Appsignal.set_custom_data(:user => { :locale => "en" })
-      #   Appsignal.set_custom_data([
+      # @example Add Hash data
+      #   Appsignal.add_custom_data(:user => { :locale => "en" })
+      #
+      # @example Merges Hash data
+      #   Appsignal.add_custom_data(:abc => "def")
+      #   Appsignal.add_custom_data(:xyz => "...")
+      #   # The custom data is: { :abc => "def", :xyz => "..." }
+      #
+      # @example Add Array data
+      #   Appsignal.add_custom_data([
       #     "array with data",
+      #     "other value",
       #     :options => { :verbose => true }
       #   ])
       #
-      # @since 3.10.0
-      # @see Transaction#set_custom_data
+      # @example Merges Array data
+      #   Appsignal.add_custom_data([1, 2, 3])
+      #   Appsignal.add_custom_data([4, 5, 6])
+      #   # The custom data is: [1, 2, 3, 4, 5, 6]
+      #
+      # @example Mixing of root data types is not supported
+      #   Appsignal.add_custom_data(:abc => "def")
+      #   Appsignal.add_custom_data([1, 2, 3])
+      #   # The custom data is: [1, 2, 3]
+      #
+      # @since 4.0.0
+      # @param data [Hash/Array] Custom data to add to the transaction.
+      # @return [void]
+      #
+      # @see Transaction#add_custom_data
       # @see https://docs.appsignal.com/guides/custom-data/sample-data.html
       #   Sample data guide
-      # @param data [Hash/Array]
-      # @return [void]
-      def set_custom_data(data)
+      def add_custom_data(data)
         return unless active?
         return unless Appsignal::Transaction.current?
 
         transaction = Appsignal::Transaction.current
-        transaction.set_custom_data(data)
+        transaction.add_custom_data(data)
       end
+      alias :set_custom_data :add_custom_data
 
-      # Set tags on the current transaction.
+      # Add tags to the current transaction.
       #
       # Tags are extra bits of information that are added to transaction and
       # appear on sample details pages on AppSignal.com.
@@ -689,221 +472,183 @@ module Appsignal
       # When this method is called multiple times, it will merge the tags.
       #
       # @example
-      #   Appsignal.tag_request(:locale => "en", :user_id => 1)
-      #   Appsignal.tag_request("locale" => "en")
-      #   Appsignal.tag_request("user_id" => 1)
+      #   Appsignal.add_tags(:locale => "en", :user_id => 1)
+      #   Appsignal.add_tags("locale" => "en")
+      #   Appsignal.add_tags("user_id" => 1)
       #
       # @example Nested hashes are not supported
       #   # Bad
-      #   Appsignal.tag_request(:user => { :locale => "en" })
+      #   Appsignal.add_tags(:user => { :locale => "en" })
       #
       # @example in a Rails controller
       #   class SomeController < ApplicationController
-      #     before_action :set_appsignal_tags
+      #     before_action :add_appsignal_tags
       #
-      #     def set_appsignal_tags
-      #       Appsignal.tag_request(:locale => I18n.locale)
+      #     def add_appsignal_tags
+      #       Appsignal.add_tags(:locale => I18n.locale)
       #     end
       #   end
       #
-      # @param tags [Hash] Collection of tags.
+      # @since 4.0.0
+      # @param tags [Hash] Collection of tags to add to the transaction.
       # @option tags [String, Symbol, Integer] :any
       #   The name of the tag as a Symbol.
       # @option tags [String, Symbol, Integer] "any"
       #   The name of the tag as a String.
       # @return [void]
       #
-      # @see Transaction.set_tags
+      # @see Transaction#add_tags
       # @see https://docs.appsignal.com/ruby/instrumentation/tagging.html
       #   Tagging guide
-      def tag_request(tags = {})
+      def add_tags(tags = {})
         return unless active?
         return unless Appsignal::Transaction.current?
 
         transaction = Appsignal::Transaction.current
-        transaction.set_tags(tags)
+        transaction.add_tags(tags)
       end
-      alias :tag_job :tag_request
-      alias :set_tags :tag_request
+      alias :tag_request :add_tags
+      alias :tag_job :add_tags
+      alias :set_tags :add_tags
 
-      # Set parameters on the current transaction.
+      # Add parameters to the current transaction.
       #
-      # Parameters are automatically set by most of our integrations. It should
-      # not be necessary to call this method unless you want to report
+      # Parameters are automatically added by most of our integrations. It
+      # should not be necessary to call this method unless you want to report
       # different parameters.
       #
       # To filter parameters, see our parameter filtering guide.
       #
-      # When this method is called multiple times, it will overwrite the
-      # previously set value.
-      #
-      # When no parameters are set this way, the transaction will look for
-      # parameters in its request environment.
-      #
-      # A block can be given to this method to defer the fetching and parsing
-      # of the parameters until and only when the transaction is sampled.
-      #
       # When both the `params` argument and a block is given to this method,
-      # the `params` argument is leading and the block will _not_ be called.
+      # the block is leading and the argument will _not_ be used.
       #
-      # @example Set parameters
-      #   Appsignal.set_params("param1" => "value1")
-      #
-      # @example Calling `set_params` multiple times will only keep the last call
-      #   Appsignal.set_params("param1" => "value1")
-      #   Appsignal.set_params("param2" => "value2")
-      #   # The parameters are: { "param2" => "value2" }
-      #
-      # @example Calling `set_params` with a block
-      #   Appsignal.set_params do
-      #     # Some slow code to parse parameters
-      #     JSON.parse('{"param1": "value1"}')
-      #   end
-      #   # The parameters are: { "param1" => "value1" }
+      # @example Add parameters
+      #   Appsignal.add_params("param1" => "value1")
+      #   # The parameters include: { "param1" => "value1" }
       #
-      # @example Calling `set_params` with a parameter and a block
-      #   Appsignal.set_params("argument" => "argument value") do
-      #     # Some slow code to parse parameters
-      #     JSON.parse('{"param1": "value1"}')
-      #   end
-      #   # The parameters are: { "argument" => "argument value" }
+      # @example Calling `add_params` multiple times will merge the values
+      #   Appsignal.add_params("param1" => "value1")
+      #   Appsignal.add_params("param2" => "value2")
+      #   # The parameters include:
+      #   # { "param1" => "value1", "param2" => "value2" }
       #
-      # @since 3.10.0
-      # @param params [Hash] The parameters to set on the transaction.
+      # @since 4.0.0
+      # @param params [Hash] The parameters to add to the transaction.
       # @yield This block is called when the transaction is sampled. The block's
       #   return value will become the new parameters.
+      # @return [void]
+      #
       # @see https://docs.appsignal.com/guides/custom-data/sample-data.html
       #   Sample data guide
       # @see https://docs.appsignal.com/guides/filter-data/filter-parameters.html
       #   Parameter filtering guide
-      # @see Transaction#set_params
+      # @see Transaction#add_params
+      def add_params(params = nil, &block)
+        return unless active?
+        return unless Appsignal::Transaction.current?
+
+        transaction = Appsignal::Transaction.current
+        transaction.add_params(params, &block)
+      end
+      alias :set_params :add_params
+
+      # Mark the parameters sample data to be set as an empty value.
+      #
+      # @api private
+      # @since 4.0.0
       # @return [void]
-      def set_params(params = nil, &block)
+      # @see Helpers::Instrumentation#set_empty_params!
+      def set_empty_params!
         return unless active?
         return unless Appsignal::Transaction.current?
 
         transaction = Appsignal::Transaction.current
-        transaction.set_params(params, &block)
+        transaction.set_empty_params!
       end
 
-      # Set session data on the current transaction.
+      # Add session data to the current transaction.
       #
-      # Session data is automatically set by most of our integrations. It
+      # Session data is automatically added by most of our integrations. It
       # should not be necessary to call this method unless you want to report
       # different session data.
       #
       # To filter session data, see our session data filtering guide.
       #
-      # When this method is called multiple times, it will overwrite the
-      # previously set value.
-      #
-      # A block can be given to this method to defer the fetching and parsing
-      # of the session data until and only when the transaction is sampled.
-      #
       # When both the `session_data` argument and a block is given to this
-      # method, the `session_data` argument is leading and the block will _not_
-      # be called.
+      # method, the bock is leading and the argument will _not_ be used.
       #
-      # @example Set session data
-      #   Appsignal.set_session_data("data" => "value")
+      # @example Add session data
+      #   Appsignal.add_session_data("session" => "data")
+      #   # The session data will include:
+      #   # { "session" => "data" }
       #
-      # @example Calling `set_session_data` multiple times will only keep the last call
-      #   Appsignal.set_session_data("data1" => "value1")
-      #   Appsignal.set_session_data("data2" => "value2")
-      #   # The session data is: { "data2" => "value2" }
+      # @example Calling `add_session_data` multiple times merge the values
+      #   Appsignal.add_session_data("session" => "data")
+      #   Appsignal.add_session_data("other" => "value")
+      #   # The session data will include:
+      #   # { "session" => "data", "other" => "value" }
       #
-      # @example Calling `set_session_data` with a block
-      #   Appsignal.set_session_data do
-      #     # Some slow code to parse session data
-      #     JSON.parse('{"data": "value"}')
-      #   end
-      #   # The session data is: { "data" => "value" }
-      #
-      # @example Calling `set_session_data` with a session_data argument and a block
-      #   Appsignal.set_session_data("argument" => "argument value") do
-      #     # Some slow code to parse session data
-      #     JSON.parse('{"data": "value"}')
-      #   end
-      #   # The session data is: { "argument" => "argument value" }
-      #
-      # @since 3.11.0
-      # @param session_data [Hash] The session data to set on the transaction.
+      # @since 4.0.0
+      # @param session_data [Hash] The session data to add to the transaction.
       # @yield This block is called when the transaction is sampled. The block's
       #   return value will become the new session data.
+      # @return [void]
+      #
       # @see https://docs.appsignal.com/guides/custom-data/sample-data.html
       #   Sample data guide
       # @see https://docs.appsignal.com/guides/filter-data/filter-session-data.html
       #   Session data filtering guide
-      # @see Transaction#set_session_data
-      # @return [void]
-      def set_session_data(session_data = nil, &block)
+      # @see Transaction#add_session_data
+      def add_session_data(session_data = nil, &block)
         return unless active?
         return unless Appsignal::Transaction.current?
 
         transaction = Appsignal::Transaction.current
-        transaction.set_session_data(session_data, &block)
+        transaction.add_session_data(session_data, &block)
       end
+      alias :set_session_data :add_session_data
 
-      # Set request headers on the current transaction.
+      # Add request headers to the current transaction.
       #
-      # Request headers are automatically set by most of our integrations. It
-      # should not be necessary to call this method unless you want to report
-      # different request headers.
-      #
-      # To filter request headers, see our session data filtering guide.
+      # Request headers are automatically added by most of our integrations. It
+      # should not be necessary to call this method unless you want to also
+      # report different request headers.
       #
-      # When this method is called multiple times, it will overwrite the
-      # previously set value.
-      #
-      # A block can be given to this method to defer the fetching and parsing
-      # of the request headers until and only when the transaction is sampled.
+      # To filter request headers, see our request header filtering guide.
       #
       # When both the `request_headers` argument and a block is given to this
-      # method, the `request_headers` argument is leading and the block will
-      # _not_ be called.
+      # method, the block is leading and the argument will _not_ be used.
       #
-      # @example Set request headers
-      #   Appsignal.set_headers(
-      #     "PATH_INFO" => "/some-path",
-      #     "HTTP_USER_AGENT" => "Firefox"
-      #   )
-      #
-      # @example Calling `set_headers` multiple times will only keep the last call
-      #   Appsignal.set_headers("PATH_INFO" => "/some-path")
-      #   Appsignal.set_headers("HTTP_USER_AGENT" => "Firefox")
-      #   # The request headers are: { "HTTP_USER_AGENT" => "Firefox" }
-      #
-      # @example Calling `set_headers` with a block
-      #   Appsignal.set_headers do
-      #     # Some slow code to parse request headers
-      #     JSON.parse('{"PATH_INFO": "/some-path"}')
-      #   end
-      #   # The session data is: { "PATH_INFO" => "/some-path" }
+      # @example Add request headers
+      #   Appsignal.add_headers("PATH_INFO" => "/some-path")
+      #   # The request headers will include:
+      #   # { "PATH_INFO" => "/some-path" }
       #
-      # @example Calling `set_headers` with a headers argument and a block
-      #   Appsignal.set_headers("PATH_INFO" => "/some-path") do
-      #     # Some slow code to parse session data
-      #     JSON.parse('{"PATH_INFO": "/block-path"}')
-      #   end
-      #   # The session data is: { "PATH_INFO" => "/some-path" }
+      # @example Calling `add_headers` multiple times merge the values
+      #   Appsignal.add_headers("PATH_INFO" => "/some-path")
+      #   Appsignal.add_headers("HTTP_USER_AGENT" => "Firefox")
+      #   # The request headers will include:
+      #   # { "PATH_INFO" => "/some-path", "HTTP_USER_AGENT" => "Firefox" }
       #
-      # @since 3.11.0
-      # @param headers [Hash] The request headers to set on the transaction.
+      # @since 4.0.0
+      # @param headers [Hash] The request headers to add to the transaction.
       # @yield This block is called when the transaction is sampled. The block's
       #   return value will become the new request headers.
+      # @return [void]
+      #
       # @see https://docs.appsignal.com/guides/custom-data/sample-data.html
       #   Sample data guide
       # @see https://docs.appsignal.com/guides/filter-data/filter-headers.html
       #   Request headers filtering guide
-      # @see Transaction#set_headers
-      # @return [void]
-      def set_headers(headers = nil, &block)
+      # @see Transaction#add_headers
+      def add_headers(headers = nil, &block)
         return unless active?
         return unless Appsignal::Transaction.current?
 
         transaction = Appsignal::Transaction.current
-        transaction.set_headers(headers, &block)
+        transaction.add_headers(headers, &block)
       end
+      alias :set_headers :add_headers
 
       # Add breadcrumbs to the transaction.
       #
@@ -1076,15 +821,6 @@ module Appsignal
       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