appsignal 3.9.3 → 3.11.0

data/lib/appsignal/transaction.rb

@@ -6,28 +6,80 @@ module Appsignal
   class Transaction
     HTTP_REQUEST   = "http_request"
     BACKGROUND_JOB = "background_job"
+    # @api private
     ACTION_CABLE   = "action_cable"
+    # @api private
     FRONTEND       = "frontend"
+    # @api private
     BLANK          = ""
+    # @api private
     ALLOWED_TAG_KEY_TYPES = [Symbol, String].freeze
-    ALLOWED_TAG_VALUE_TYPES = [Symbol, String, Integer].freeze
+    # @api private
+    ALLOWED_TAG_VALUE_TYPES = [Symbol, String, Integer, TrueClass, FalseClass].freeze
+    # @api private
     BREADCRUMB_LIMIT = 20
+    # @api private
     ERROR_CAUSES_LIMIT = 10
 
     class << self
-      def create(id, namespace, request, options = {})
+      # Create a new transaction and set it as the currently active
+      # transaction.
+      #
+      # @param id_or_namespace [String] Namespace of the to be created transaction.
+      # @return [Transaction]
+      def create(id_or_namespace, arg_namespace = nil, request = nil, options = {})
+        if id_or_namespace && arg_namespace
+          Appsignal::Utils::StdoutAndLoggerMessage.warning(
+            "Appsignal::Transaction.create: " \
+              "A new Transaction is created using the transaction ID argument. " \
+              "This argument is deprecated without replacement."
+          )
+        end
+        if arg_namespace
+          Appsignal::Utils::StdoutAndLoggerMessage.warning(
+            "Appsignal::Transaction.create: " \
+              "A Transaction is created using the namespace argument. " \
+              "Specify the namespace as the first argument to the 'create' " \
+              "method without the ID argument."
+          )
+        end
+        if request
+          Appsignal::Utils::StdoutAndLoggerMessage.warning(
+            "Appsignal::Transaction.create: " \
+              "A Transaction is created using the request argument. " \
+              "This argument is deprecated. Please use the `Appsignal.set_*` helpers instead."
+          )
+        end
         # Allow middleware to force a new transaction
-        Thread.current[:appsignal_transaction] = nil if options.include?(:force) && options[:force]
+        if options[:force]
+          Appsignal::Utils::StdoutAndLoggerMessage.warning(
+            "Appsignal::Transaction.create: " \
+              "A Transaction is created using the `:force => true` option argument. " \
+              "The options argument is deprecated without replacement."
+          )
+          Thread.current[:appsignal_transaction] = nil
+        end
+        if arg_namespace
+          id = id_or_namespace
+          namespace = arg_namespace
+        else
+          id = SecureRandom.uuid
+          namespace = id_or_namespace
+        end
 
         # Check if we already have a running transaction
         if Thread.current[:appsignal_transaction].nil?
           # If not, start a new transaction
           Thread.current[:appsignal_transaction] =
-            Appsignal::Transaction.new(id, namespace, request, options)
+            Appsignal::Transaction.new(
+              id,
+              namespace,
+              request,
+              options
+            )
         else
           # Otherwise, log the issue about trying to start another transaction
-          Appsignal.internal_logger.warn_once_then_debug(
-            :transaction_id,
+          Appsignal.internal_logger.warn(
             "Trying to start new transaction with id " \
               "'#{id}', but a transaction with id '#{current.transaction_id}' " \
               "is already running. Using transaction '#{current.transaction_id}'."
@@ -56,6 +108,8 @@ module Appsignal
         current && !current.nil_transaction?
       end
 
+      # Complete the currently active transaction and unset it as the active
+      # transaction.
       def complete_current!
         current.complete
       rescue => e
@@ -73,21 +127,32 @@ module Appsignal
       end
     end
 
+    # @api private
     attr_reader :ext, :transaction_id, :action, :namespace, :request, :paused, :tags, :options,
-      :discarded, :breadcrumbs
+      :breadcrumbs, :custom_data
 
-    def initialize(transaction_id, namespace, request, options = {})
+    # Use {.create} to create new transactions.
+    #
+    # @param transaction_id [String] ID of the to be created transaction.
+    # @param namespace [String] Namespace of the to be created transaction.
+    # @see create
+    # @api private
+    def initialize(transaction_id, namespace, request = nil, options = {})
       @transaction_id = transaction_id
       @action = nil
       @namespace = namespace
-      @request = request
+      @request = request || InternalGenericRequest.new({})
       @paused = false
       @discarded = false
       @tags = {}
+      @custom_data = nil
       @breadcrumbs = []
       @store = Hash.new({})
       @options = options
       @options[:params_method] ||= :params
+      @params = nil
+      @session_data = nil
+      @headers = nil
 
       @ext = Appsignal::Extension.start_transaction(
         @transaction_id,
@@ -106,42 +171,57 @@ module Appsignal
           "because it was manually discarded."
         return
       end
-      sample_data if @ext.finish(0)
+      _sample_data if @ext.finish(0)
       @ext.complete
     end
 
+    # @api private
     def pause!
       @paused = true
     end
 
+    # @api private
     def resume!
       @paused = false
     end
 
+    # @api private
     def paused?
       @paused == true
     end
 
+    # @api private
     def discard!
       @discarded = true
     end
 
+    # @api private
     def restore!
       @discarded = false
     end
 
+    # @api private
     def discarded?
       @discarded == true
     end
 
+    # @api private
     def store(key)
       @store[key]
     end
 
+    # @api private
     def params
-      return @params if defined?(@params)
+      parameters = @params || request_params
 
-      request_params
+      if parameters.respond_to? :call
+        parameters.call
+      else
+        parameters
+      end
+    rescue => e
+      Appsignal.internal_logger.error("Exception while fetching params: #{e.class}: #{e}")
+      nil
     end
 
     # Set parameters on the transaction.
@@ -152,9 +232,17 @@ module Appsignal
     # The parameters set using {#set_params} are leading over those extracted
     # from a request's environment.
     #
+    # When both the `given_params` and a block is given to this method, the
+    # `given_params` argument is leading and the block will _not_ be called.
+    #
+    # @since 3.9.1
     # @param given_params [Hash] The parameters to set on the transaction.
+    # @yield This block is called when the transaction is sampled. The block's
+    #   return value will become the new parameters.
     # @return [void]
-    def set_params(given_params)
+    # @see Helpers::Instrumentation#set_params
+    def set_params(given_params = nil, &block)
+      @params = block if block
       @params = given_params if given_params
     end
 
@@ -172,14 +260,22 @@ module Appsignal
     # When no parameters are set this way, the transaction will look for
     # parameters on the {#request} environment.
     #
+    # @since 3.9.1
     # @param given_params [Hash] The parameters to set on the transaction if none are already set.
+    # @yield This block is called when the transaction is sampled. The block's
+    #   return value will become the new parameters.
     # @return [void]
-    def set_params_if_nil(given_params)
-      set_params(given_params) unless @params
+    #
+    # @see #set_params
+    # @see Helpers::Instrumentation#set_params_if_nil
+    def set_params_if_nil(given_params = nil, &block)
+      set_params(given_params, &block) unless @params
     end
 
     # Set tags on the transaction.
     #
+    # When this method is called multiple times, it will merge the tags.
+    #
     # @param given_tags [Hash] Collection of tags.
     # @option given_tags [String, Symbol, Integer] :any
     #   The name of the tag as a Symbol.
@@ -187,13 +283,112 @@ module Appsignal
     #   The name of the tag as a String.
     # @return [void]
     #
-    # @see Appsignal.tag_request
+    # @see Helpers::Instrumentation#tag_request
     # @see https://docs.appsignal.com/ruby/instrumentation/tagging.html
     #   Tagging guide
     def set_tags(given_tags = {})
       @tags.merge!(given_tags)
     end
 
+    # Set session data on the transaction.
+    #
+    # When both the `given_session_data` and a block is given to this method,
+    # the `given_session_data` argument is leading and the block will _not_ be
+    # called.
+    #
+    # @param given_session_data [Hash] A hash containing session data.
+    # @yield This block is called when the transaction is sampled. The block's
+    #   return value will become the new session data.
+    # @return [void]
+    #
+    # @since 3.10.1
+    # @see Helpers::Instrumentation#set_session_data
+    # @see https://docs.appsignal.com/guides/custom-data/sample-data.html
+    #   Sample data guide
+    def set_session_data(given_session_data = nil, &block)
+      @session_data = block if block
+      @session_data = given_session_data if given_session_data
+    end
+
+    # Set session data on the transaction if not already set.
+    #
+    # When both the `given_session_data` and a block is given to this method,
+    # the `given_session_data` argument is leading and the block will _not_ be
+    # called.
+    #
+    # @param given_session_data [Hash] A hash containing session data.
+    # @yield This block is called when the transaction is sampled. The block's
+    #   return value will become the new session data.
+    # @return [void]
+    #
+    # @since 3.10.1
+    # @see #set_session_data
+    # @see https://docs.appsignal.com/guides/custom-data/sample-data.html
+    #   Sample data guide
+    def set_session_data_if_nil(given_session_data = nil, &block)
+      set_session_data(given_session_data, &block) unless @session_data
+    end
+
+    # Set headers on the transaction.
+    #
+    # When both the `given_headers` and a block is given to this method,
+    # the `given_headers` argument is leading and the block will _not_ be
+    # called.
+    #
+    # @param given_headers [Hash] A hash containing headers.
+    # @yield This block is called when the transaction is sampled. The block's
+    #   return value will become the new headers.
+    # @return [void]
+    #
+    # @since 3.10.1
+    # @see Helpers::Instrumentation#set_headers
+    # @see https://docs.appsignal.com/guides/custom-data/sample-data.html
+    #   Sample data guide
+    def set_headers(given_headers = nil, &block)
+      @headers = block if block
+      @headers = given_headers if given_headers
+    end
+
+    # Set headers on the transaction if not already set.
+    #
+    # When both the `given_headers` and a block is given to this method,
+    # the `given_headers` argument is leading and the block will _not_ be
+    # called.
+    #
+    # @param given_headers [Hash] A hash containing headers.
+    # @yield This block is called when the transaction is sampled. The block's
+    #   return value will become the new headers.
+    # @return [void]
+    #
+    # @since 3.10.1
+    # @see #set_headers
+    # @see https://docs.appsignal.com/guides/custom-data/sample-data.html
+    #   Sample data guide
+    def set_headers_if_nil(given_headers = nil, &block)
+      set_headers(given_headers, &block) unless @headers
+    end
+
+    # Set custom data on the transaction.
+    #
+    # When this method is called multiple times, it will overwrite the
+    # previously set value.
+    #
+    # @since 3.10.0
+    # @see Appsignal.set_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)
+      case data
+      when Array, Hash
+        @custom_data = data
+      else
+        Appsignal.internal_logger
+          .error("set_custom_data: Unsupported data type #{data.class} received.")
+      end
+    end
+
     # Add breadcrumbs to the transaction.
     #
     # @param category [String] category of breadcrumb
@@ -284,6 +479,8 @@ module Appsignal
       @ext.set_namespace(namespace)
     end
 
+    # @deprecated Use the {#set_action} helper.
+    # @api private
     def set_http_or_background_action(from = request.params)
       return unless from
 
@@ -296,8 +493,6 @@ module Appsignal
 
     # Set queue start time for transaction.
     #
-    # Most commononly called by {set_http_or_background_queue_start}.
-    #
     # @param start [Integer] Queue start time in milliseconds.
     # @raise [RangeError] When the queue start time value is too big, this
     #   method raises a RangeError.
@@ -327,14 +522,21 @@ module Appsignal
     # AppSignal as seconds.
     #
     # @see https://docs.appsignal.com/ruby/instrumentation/request-queue-time.html
+    # @deprecated Use {#set_queue_start} instead.
     # @return [void]
     def set_http_or_background_queue_start
+      Appsignal::Utils::StdoutAndLoggerMessage.warning \
+        "The Appsignal::Transaction#set_http_or_background_queue_start " \
+          "method has been deprecated. " \
+          "Please use the Appsignal::Transaction#set_queue_start method instead."
+
       start = http_queue_start || background_queue_start
       return unless start
 
       set_queue_start(start)
     end
 
+    # @api private
     def set_metadata(key, value)
       return unless key && value
       return if Appsignal.config[:filter_metadata].include?(key.to_s)
@@ -342,46 +544,29 @@ module Appsignal
       @ext.set_metadata(key, value)
     end
 
+    # @deprecated Use one of the set_tags, set_params, set_session_data,
+    #   set_params or set_custom_data helpers instead.
+    # @api private
     def set_sample_data(key, data)
-      return unless key && data
-
-      if !data.is_a?(Array) && !data.is_a?(Hash)
-        Appsignal.internal_logger.error(
-          "Invalid sample data for '#{key}'. Value is not an Array or Hash: '#{data.inspect}'"
-        )
-        return
-      end
-
-      @ext.set_sample_data(
-        key.to_s,
-        Appsignal::Utils::Data.generate(data)
+      Appsignal::Utils::StdoutAndLoggerMessage.warning(
+        "Appsignal::Transaction#set_sample_data is deprecated. " \
+          "Please use one of the instrumentation helpers: set_tags, " \
+          "set_params, set_session_data, set_params or set_custom_data."
       )
-    rescue RuntimeError => e
-      begin
-        inspected_data = data.inspect
-        Appsignal.internal_logger.error(
-          "Error generating data (#{e.class}: #{e.message}) for '#{inspected_data}'"
-        )
-      rescue => e
-        Appsignal.internal_logger.error(
-          "Error generating data (#{e.class}: #{e.message}). Can't inspect data."
-        )
-      end
+      _set_sample_data(key, data)
     end
 
+    # @deprecated No replacement.
+    # @api private
     def sample_data
-      {
-        :params => sanitized_params,
-        :environment => sanitized_environment,
-        :session_data => sanitized_session_data,
-        :metadata => sanitized_metadata,
-        :tags => sanitized_tags,
-        :breadcrumbs => breadcrumbs
-      }.each do |key, data|
-        set_sample_data(key, data)
-      end
+      Appsignal::Utils::StdoutAndLoggerMessage.warning(
+        "Appsignal::Transaction#sample_data is deprecated. " \
+          "Please remove any calls to this method."
+      )
+      _sample_data
     end
 
+    # @see Appsignal::Helpers::Instrumentation#set_error
     def set_error(error)
       unless error.is_a?(Exception)
         Appsignal.internal_logger.error "Appsignal::Transaction#set_error: Cannot set error. " \
@@ -428,19 +613,23 @@ module Appsignal
 
       causes_sample_data.last[:is_root_cause] = false if root_cause_missing
 
-      set_sample_data(
+      _set_sample_data(
         "error_causes",
         causes_sample_data
       )
     end
     alias_method :add_exception, :set_error
 
+    # @see Helpers::Instrumentation#instrument
+    # @api private
     def start_event
       return if paused?
 
       @ext.start_event(0)
     end
 
+    # @see Helpers::Instrumentation#instrument
+    # @api private
     def finish_event(name, title, body, body_format = Appsignal::EventFormatter::DEFAULT)
       return if paused?
 
@@ -453,6 +642,8 @@ module Appsignal
       )
     end
 
+    # @see Helpers::Instrumentation#instrument
+    # @api private
     def record_event(name, title, body, duration, body_format = Appsignal::EventFormatter::DEFAULT)
       return if paused?
 
@@ -466,6 +657,7 @@ module Appsignal
       )
     end
 
+    # @see Helpers::Instrumentation#instrument
     def instrument(name, title = nil, body = nil, body_format = Appsignal::EventFormatter::DEFAULT)
       start_event
       yield if block_given?
@@ -479,7 +671,8 @@ module Appsignal
     end
     alias_method :to_hash, :to_h
 
-    class GenericRequest
+    # @api private
+    class InternalGenericRequest
       attr_reader :env
 
       def initialize(env)
@@ -491,8 +684,64 @@ module Appsignal
       end
     end
 
+    # @deprecated Use the instrumentation helpers to set metadata on the
+    #   transaction, rather than rely on the GenericRequest automation. See the
+    #   {Helpers::Instrumentation} module for a list of helpers.
+    # @api private
+    class GenericRequest < InternalGenericRequest
+      def initialize(_env)
+        Appsignal::Utils::StdoutAndLoggerMessage.warning(
+          "The use of Appsignal::Transaction::GenericRequest is deprecated. " \
+            "Use the `Appsignal.set_*` helpers instead. " \
+            "https://docs.appsignal.com/guides/custom-data/sample-data.html"
+        )
+        super
+      end
+    end
+
     private
 
+    def _set_sample_data(key, data)
+      return unless key && data
+
+      if !data.is_a?(Array) && !data.is_a?(Hash)
+        Appsignal.internal_logger.error(
+          "Invalid sample data for '#{key}'. Value is not an Array or Hash: '#{data.inspect}'"
+        )
+        return
+      end
+
+      @ext.set_sample_data(
+        key.to_s,
+        Appsignal::Utils::Data.generate(data)
+      )
+    rescue RuntimeError => e
+      begin
+        inspected_data = data.inspect
+        Appsignal.internal_logger.error(
+          "Error generating data (#{e.class}: #{e.message}) for '#{inspected_data}'"
+        )
+      rescue => e
+        Appsignal.internal_logger.error(
+          "Error generating data (#{e.class}: #{e.message}). Can't inspect data."
+        )
+      end
+    end
+
+    def _sample_data
+      {
+        :params => sanitized_params,
+        :environment => sanitized_environment,
+        :session_data => sanitized_session_data,
+        :metadata => sanitized_metadata,
+        :tags => sanitized_tags,
+        :breadcrumbs => breadcrumbs,
+        :custom_data => custom_data
+      }.each do |key, data|
+        _set_sample_data(key, data)
+      end
+    end
+
     # Returns calculated background queue start time in milliseconds, based on
     # environment values.
     #
@@ -516,25 +765,7 @@ module Appsignal
     # @return [Integer] queue start in milliseconds.
     def http_queue_start
       env = environment
-      return unless env
-
-      env_var = env["HTTP_X_QUEUE_START"] || env["HTTP_X_REQUEST_START"]
-      return unless env_var
-
-      cleaned_value = env_var.tr("^0-9", "")
-      return if cleaned_value.empty?
-
-      value = cleaned_value.to_i
-      if value > 4_102_441_200_000
-        # Value is in microseconds. Transform to milliseconds.
-        value / 1_000
-      elsif value < 946_681_200_000
-        # Value is too low to be plausible
-        nil
-      else
-        # Value is in milliseconds
-        value
-      end
+      Appsignal::Rack::Utils.queue_start_from(env)
     end
 
     def sanitized_params
@@ -550,28 +781,25 @@ module Appsignal
       begin
         request.send options[:params_method]
       rescue => e
-        # Getting params from the request has been know to fail.
-        Appsignal.internal_logger.debug "Exception while getting params: #{e}"
+        Appsignal.internal_logger.warn "Exception while getting params: #{e}"
         nil
       end
     end
 
-    # Returns sanitized environment for a transaction.
-    #
-    # The environment of a transaction can contain a lot of information, not
-    # all of it useful for debugging.
-    #
-    # @return [nil] if no environment is present.
-    # @return [Hash<String, Object>]
-    def sanitized_environment
-      env = environment
-      return if env.empty?
-
-      {}.tap do |out|
-        Appsignal.config[:request_headers].each do |key|
-          out[key] = env[key] if env[key]
+    def session_data
+      if @session_data
+        if @session_data.respond_to? :call
+          @session_data.call
+        else
+          @session_data
         end
+      elsif request.respond_to?(:session)
+        request.session
       end
+    rescue => e
+      Appsignal.internal_logger.error \
+        "Exception while fetching session data: #{e.class}: #{e}"
+      nil
     end
 
     # Returns sanitized session data.
@@ -583,23 +811,21 @@ module Appsignal
     # @return [nil] if the {#request} session data is `nil`.
     # @return [Hash<String, Object>]
     def sanitized_session_data
-      return if !Appsignal.config[:send_session_data] ||
-        !request.respond_to?(:session)
-
-      session = request.session
-      return unless session
+      return unless Appsignal.config[:send_session_data]
 
       Appsignal::Utils::HashSanitizer.sanitize(
-        session.to_hash, Appsignal.config[:filter_session_data]
+        session_data&.to_hash, Appsignal.config[:filter_session_data]
       )
     end
 
-    # Returns sanitized metadata set by {#set_metadata} and from the
-    # {#environment}.
+    # Returns sanitized metadata set on the request environment.
     #
     # @return [Hash<String, Object>]
     def sanitized_metadata
-      metadata = environment[:metadata]
+      env = environment
+      return unless env
+
+      metadata = env[:metadata]
       return unless metadata
 
       metadata
@@ -607,17 +833,40 @@ module Appsignal
         .reject { |key, _value| Appsignal.config[:filter_metadata].include?(key) }
     end
 
-    # Returns the environment for a transaction.
+    def environment
+      if @headers
+        if @headers.respond_to? :call
+          @headers.call
+        else
+          @headers
+        end
+      elsif request.respond_to?(:env)
+        request.env
+      end
+    rescue => e
+      Appsignal.internal_logger.error \
+        "Exception while fetching headers: #{e.class}: #{e}"
+      nil
+    end
+
+    # Returns sanitized environment for a transaction.
     #
-    # Returns an empty Hash when the {#request} object doesn't listen to the
-    # `#env` method or the `#env` is nil.
+    # The environment of a transaction can contain a lot of information, not
+    # all of it useful for debugging.
     #
+    # @return [nil] if no environment is present.
     # @return [Hash<String, Object>]
-    def environment
-      return {} unless request.respond_to?(:env)
-      return {} unless request.env
+    def sanitized_environment
+      env = environment
+      return unless env
+      return unless env.respond_to?(:empty?)
+      return if env.empty?
 
-      request.env
+      {}.tap do |out|
+        Appsignal.config[:request_headers].each do |key|
+          out[key] = env[key] if env[key]
+        end
+      end
     end
 
     # Only keep tags if they meet the following criteria: