appsignal 3.9.2-java → 3.10.0-java

data/lib/appsignal/rack/abstract_middleware.rb

@@ -3,16 +3,24 @@
 require "rack"
 
 module Appsignal
-  # @api private
   module Rack
+    # Base instrumentation middleware.
+    #
+    # Do not use this middleware directly. Instead use
+    # {InstrumentationMiddleware}.
+    #
+    # @api private
     class AbstractMiddleware
+      DEFAULT_ERROR_REPORTING = :default
+
       def initialize(app, options = {})
         Appsignal.internal_logger.debug "Initializing #{self.class}"
         @app = app
         @options = options
         @request_class = options.fetch(:request_class, ::Rack::Request)
         @params_method = options.fetch(:params_method, :params)
-        @instrument_span_name = options.fetch(:instrument_span_name, "process.abstract")
+        @instrument_event_name = options.fetch(:instrument_event_name, nil)
+        @report_errors = options.fetch(:report_errors, DEFAULT_ERROR_REPORTING)
       end
 
       def call(env)
@@ -32,15 +40,31 @@ module Appsignal
               )
             end
 
-          add_transaction_metadata_before(transaction, request)
-          if wrapped_instrumentation
-            instrument_wrapped_request(request, transaction)
-          else
+          unless wrapped_instrumentation
             # Set transaction on the request environment so other nested
             # middleware can detect if there is parent instrumentation
             # middleware active.
             env[Appsignal::Rack::APPSIGNAL_TRANSACTION] = transaction
-            instrument_request(request, transaction)
+          end
+
+          begin
+            add_transaction_metadata_before(transaction, request)
+            # Report errors if the :report_errors option is set to true or when
+            # there is no parent instrumentation that can rescue and report the error.
+            if @report_errors || !wrapped_instrumentation
+              instrument_app_call_with_exception_handling(
+                request.env,
+                transaction,
+                wrapped_instrumentation
+              )
+            else
+              instrument_app_call(request.env, transaction)
+            end
+          ensure
+            add_transaction_metadata_after(transaction, request)
+
+            # Complete transaction because this is the top instrumentation middleware.
+            Appsignal::Transaction.complete_current! unless wrapped_instrumentation
           end
         else
           @app.call(env)
@@ -53,38 +77,55 @@ module Appsignal
       # don't report any exceptions here, the top instrumentation middleware
       # will be the one reporting the exception.
       #
-      # Either another {GenericInstrumentation} or {EventHandler} is higher in
-      # the stack and will report the exception and complete the transaction.
+      # Either another {AbstractMiddleware} or {EventHandler} is higher in the
+      # stack and will report the exception and complete the transaction.
       #
-      # @see {#instrument_request}
-      def instrument_wrapped_request(request, transaction)
-        instrument_app_call(request.env)
-      ensure
-        add_transaction_metadata_after(transaction, request)
+      # @see {#instrument_app_call_with_exception_handling}
+      def instrument_app_call(env, transaction)
+        if @instrument_event_name
+          Appsignal.instrument(@instrument_event_name) do
+            call_app(env, transaction)
+          end
+        else
+          call_app(env, transaction)
+        end
+      end
+
+      def call_app(env, transaction)
+        status, headers, obody = @app.call(env)
+        body =
+          if obody.is_a? Appsignal::Rack::BodyWrapper
+            obody
+          else
+            # Instrument response body and closing of the response body
+            Appsignal::Rack::BodyWrapper.wrap(obody, transaction)
+          end
+        [status, headers, body]
       end
 
       # Instrument the request fully. This is used by the top instrumentation
       # middleware in the middleware stack. Unlike
-      # {#instrument_wrapped_request} this will report any exceptions being
+      # {#instrument_app_call} this will report any exceptions being
       # raised.
       #
-      # @see {#instrument_wrapped_request}
-      def instrument_request(request, transaction)
-        instrument_app_call(request.env)
+      # @see {#instrument_app_call}
+      def instrument_app_call_with_exception_handling(env, transaction, wrapped_instrumentation)
+        instrument_app_call(env, transaction)
       rescue Exception => error # rubocop:disable Lint/RescueException
-        transaction.set_error(error)
+        report_errors =
+          if @report_errors == DEFAULT_ERROR_REPORTING
+            # If there's no parent transaction, report the error
+            !wrapped_instrumentation
+          elsif @report_errors.respond_to?(:call)
+            # If the @report_errors option is callable, call it with the
+            # request environment so it can determine if the error needs to be
+            # reported.
+            @report_errors.call(env)
+          else
+            @report_errors
+          end
+        transaction.set_error(error) if report_errors
         raise error
-      ensure
-        add_transaction_metadata_after(transaction, request)
-
-        # Complete transaction because this is the top instrumentation middleware.
-        Appsignal::Transaction.complete_current!
-      end
-
-      def instrument_app_call(env)
-        Appsignal.instrument(@instrument_span_name) do
-          @app.call(env)
-        end
       end
 
       # Add metadata to the transaction based on the request environment.
@@ -98,11 +139,14 @@ module Appsignal
       # Call `super` to also include the default set metadata.
       def add_transaction_metadata_after(transaction, request)
         default_action =
-          request.env["appsignal.route"] || request.env["appsignal.action"]
+          appsignal_route_env_value(request) || appsignal_action_env_value(request)
         transaction.set_action_if_nil(default_action)
         transaction.set_metadata("path", request.path)
-        transaction.set_metadata("method", request.request_method)
-        transaction.set_params_if_nil(params_for(request))
+
+        request_method = request_method_for(request)
+        transaction.set_metadata("method", request_method) if request_method
+
+        transaction.set_params_if_nil { params_for(request) }
         transaction.set_http_or_background_queue_start
       end
 
@@ -118,9 +162,36 @@ module Appsignal
         nil
       end
 
+      def request_method_for(request)
+        request.request_method
+      rescue => error
+        Appsignal.internal_logger.error("Unable to report HTTP request method: '#{error}'")
+        nil
+      end
+
       def request_for(env)
         @request_class.new(env)
       end
+
+      def appsignal_route_env_value(request)
+        request.env["appsignal.route"].tap do |value|
+          next unless value
+
+          Appsignal::Utils::StdoutAndLoggerMessage.warning \
+            "Setting the action name with the request env 'appsignal.route' is deprecated. " \
+              "Please use `Appsignal.set_action` instead. "
+        end
+      end
+
+      def appsignal_action_env_value(request)
+        request.env["appsignal.action"].tap do |value|
+          next unless value
+
+          Appsignal::Utils::StdoutAndLoggerMessage.warning \
+            "Setting the action name with the request env 'appsignal.action' is deprecated. " \
+              "Please use `Appsignal.set_action` instead. "
+        end
+      end
     end
   end
 end

data/lib/appsignal/rack/body_wrapper.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module Appsignal
+  module Rack
+    # @api private
+    class BodyWrapper
+      def self.wrap(original_body, appsignal_transaction)
+        # The logic of how Rack treats a response body differs based on which methods
+        # the body responds to. This means that to support the Rack 3.x spec in full
+        # we need to return a wrapper which matches the API of the wrapped body as closely
+        # as possible. Pick the wrapper from the most specific to the least specific.
+        # See https://github.com/rack/rack/blob/main/SPEC.rdoc#the-body-
+        #
+        # What is important is that our Body wrapper responds to the same methods Rack
+        # (or a webserver) would be checking and calling, and passes through that functionality
+        # to the original body.
+        #
+        # This comment https://github.com/rails/rails/pull/49627#issuecomment-1769802573
+        # is of particular interest to understand why this has to be somewhat complicated.
+        if original_body.respond_to?(:to_path)
+          PathableBodyWrapper.new(original_body, appsignal_transaction)
+        elsif original_body.respond_to?(:to_ary)
+          ArrayableBodyWrapper.new(original_body, appsignal_transaction)
+        elsif !original_body.respond_to?(:each) && original_body.respond_to?(:call)
+          # This body only supports #call, so we must be running a Rack 3 application
+          # It is possible that a body exposes both `each` and `call` in the hopes of
+          # being backwards-compatible with both Rack 3.x and Rack 2.x, however
+          # this is not going to work since the SPEC says that if both are available,
+          # `each` should be used and `call` should be ignored.
+          # So for that case we can drop to our default EnumerableBodyWrapper
+          CallableBodyWrapper.new(original_body, appsignal_transaction)
+        else
+          EnumerableBodyWrapper.new(original_body, appsignal_transaction)
+        end
+      end
+
+      def initialize(body, appsignal_transaction)
+        @body_already_closed = false
+        @body = body
+        @transaction = appsignal_transaction
+      end
+
+      # This must be present in all Rack bodies and will be called by the serving adapter
+      def close
+        # The @body_already_closed check is needed so that if `to_ary`
+        # of the body has already closed itself (as prescribed) we do not
+        # attempt to close it twice
+        if !@body_already_closed && @body.respond_to?(:close)
+          Appsignal.instrument("close_response_body.rack") { @body.close }
+        end
+        @body_already_closed = true
+      rescue Exception => error # rubocop:disable Lint/RescueException
+        @transaction.set_error(error)
+        raise error
+      end
+    end
+
+    # The standard Rack body wrapper which exposes "each" for iterating
+    # over the response body. This is supported across all 3 major Rack
+    # versions.
+    #
+    # @api private
+    class EnumerableBodyWrapper < BodyWrapper
+      def each(&blk)
+        # This is a workaround for the Rails bug when there was a bit too much
+        # eagerness in implementing to_ary, see:
+        # https://github.com/rails/rails/pull/44953
+        # https://github.com/rails/rails/pull/47092
+        # https://github.com/rails/rails/pull/49627
+        # https://github.com/rails/rails/issues/49588
+        # While the Rack SPEC does not mandate `each` to be callable
+        # in a blockless way it is still a good idea to have it in place.
+        return enum_for(:each) unless block_given?
+
+        Appsignal.instrument("process_response_body.rack", "Process Rack response body (#each)") do
+          @body.each(&blk)
+        end
+      rescue Exception => error # rubocop:disable Lint/RescueException
+        @transaction.set_error(error)
+        raise error
+      end
+    end
+
+    # The callable response bodies are a new Rack 3.x feature, and would not work
+    # with older Rack versions. They must not respond to `each` because
+    # "If it responds to each, you must call each and not call". This is why
+    # it inherits from BodyWrapper directly and not from EnumerableBodyWrapper
+    #
+    # @api private
+    class CallableBodyWrapper < BodyWrapper
+      def call(stream)
+        # `stream` will be closed by the app we are calling, no need for us
+        # to close it ourselves
+        Appsignal.instrument("process_response_body.rack", "Process Rack response body (#call)") do
+          @body.call(stream)
+        end
+      rescue Exception => error # rubocop:disable Lint/RescueException
+        @transaction.set_error(error)
+        raise error
+      end
+    end
+
+    # "to_ary" takes precedence over "each" and allows the response body
+    # to be read eagerly. If the body supports that method, it takes precedence
+    # over "each":
+    # "Middleware may call to_ary directly on the Body and return a new Body in its place"
+    # One could "fold" both the to_ary API and the each() API into one Body object, but
+    # to_ary must also call "close" after it executes - and in the Rails implementation
+    # this pecularity was not handled properly.
+    #
+    # @api private
+    class ArrayableBodyWrapper < EnumerableBodyWrapper
+      def to_ary
+        @body_already_closed = true
+        Appsignal.instrument(
+          "process_response_body.rack",
+          "Process Rack response body (#to_ary)"
+        ) do
+          @body.to_ary
+        end
+      rescue Exception => error # rubocop:disable Lint/RescueException
+        @transaction.set_error(error)
+        raise error
+      end
+    end
+
+    # Having "to_path" on a body allows Rack to serve out a static file, or to
+    # pass that file to the downstream webserver for sending using X-Sendfile
+    class PathableBodyWrapper < EnumerableBodyWrapper
+      def to_path
+        Appsignal.instrument(
+          "process_response_body.rack",
+          "Process Rack response body (#to_path)"
+        ) do
+          @body.to_path
+        end
+      rescue Exception => error # rubocop:disable Lint/RescueException
+        @transaction.set_error(error)
+        raise error
+      end
+    end
+  end
+end

data/lib/appsignal/rack/event_handler.rb

@@ -4,8 +4,10 @@ module Appsignal
   module Rack
     APPSIGNAL_TRANSACTION = "appsignal.transaction"
     APPSIGNAL_EVENT_HANDLER_ID = "appsignal.event_handler_id"
+    APPSIGNAL_EVENT_HANDLER_HAS_ERROR = "appsignal.event_handler.error"
     RACK_AFTER_REPLY = "rack.after_reply"
 
+    # @api private
     class EventHandler
       include ::Rack::Events::Abstract
 
@@ -70,6 +72,7 @@ module Appsignal
           transaction = request.env[APPSIGNAL_TRANSACTION]
           return unless transaction
 
+          request.env[APPSIGNAL_EVENT_HANDLER_HAS_ERROR] = true
           transaction.set_error(error)
         end
       end
@@ -83,12 +86,18 @@ module Appsignal
         self.class.safe_execution("Appsignal::Rack::EventHandler#on_finish") do
           transaction.finish_event("process_request.rack", "", "")
           transaction.set_http_or_background_queue_start
-          if response
-            transaction.set_tags(:response_status => response.status)
+          response_status =
+            if response
+              response.status
+            elsif request.env[APPSIGNAL_EVENT_HANDLER_HAS_ERROR] == true
+              500
+            end
+          if response_status
+            transaction.set_tags(:response_status => response_status)
             Appsignal.increment_counter(
               :response_status,
               1,
-              :status => response.status,
+              :status => response_status,
               :namespace => format_namespace(transaction.namespace)
             )
           end

data/lib/appsignal/rack/generic_instrumentation.rb

@@ -1,13 +1,11 @@
 # frozen_string_literal: true
 
-require "rack"
-
 module Appsignal
-  # @api private
   module Rack
+    # @api private
     class GenericInstrumentation < AbstractMiddleware
       def initialize(app, options = {})
-        options[:instrument_span_name] ||= "process_action.generic"
+        options[:instrument_event_name] ||= "process_action.generic"
         super
       end
 
@@ -16,5 +14,8 @@ module Appsignal
         transaction.set_action_if_nil("unknown")
       end
     end
+
+    # @api private
+    class GenericInstrumentationAlias < GenericInstrumentation; end
   end
 end

data/lib/appsignal/rack/grape_middleware.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Appsignal
+  module Rack
+    # @api private
+    class GrapeMiddleware < Appsignal::Rack::AbstractMiddleware
+      def initialize(app, options = {})
+        options[:instrument_event_name] = "process_request.grape"
+        options[:report_errors] = lambda { |env| !env["grape.skip_appsignal_error"] }
+        super
+      end
+
+      private
+
+      def add_transaction_metadata_after(transaction, request)
+        endpoint = request.env["api.endpoint"]
+        unless endpoint&.options
+          super
+          return
+        end
+
+        options = endpoint.options
+        request_method = options[:method].first.to_s.upcase
+        klass = options[:for]
+        namespace = endpoint.namespace
+        namespace = "" if namespace == "/"
+
+        path = options[:path].first.to_s
+        path = "/#{path}" if path[0] != "/"
+        path = "#{namespace}#{path}"
+
+        transaction.set_action_if_nil("#{request_method}::#{klass}##{path}")
+
+        super
+
+        transaction.set_metadata("path", path)
+      end
+    end
+  end
+end

data/lib/appsignal/rack/hanami_middleware.rb

@@ -5,25 +5,15 @@ module Appsignal
     # @api private
     class HanamiMiddleware < AbstractMiddleware
       def initialize(app, options = {})
-        options[:request_class] ||= ::Hanami::Action::Request
         options[:params_method] ||= :params
-        options[:instrument_span_name] ||= "process_action.hanami"
+        options[:instrument_event_name] ||= "process_action.hanami"
         super
       end
 
       private
 
       def params_for(request)
-        super&.to_h
-      end
-
-      def request_for(env)
-        params = ::Hanami::Action.params_class.new(env)
-        @request_class.new(
-          :env => env,
-          :params => params,
-          :sessions_enabled => true
-        )
+        ::Hanami::Action.params_class.new(request.env).to_h
       end
     end
   end

data/lib/appsignal/rack/instrumentation_middleware.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Appsignal
+  module Rack
+    # Rack instrumentation middleware.
+    #
+    # This Ruby gem automatically instruments several Rack based libraries,
+    # like Rails and Sinatra. This middleware does not need to be added
+    # manually to these frameworks.
+    #
+    # This instrumentation middleware will wrap an app and report how long the
+    # request and response took, report errors that occurred in the app, and
+    # report metadata about the request method and path.
+    #
+    # The action name for the endpoint is not set by default, which is required
+    # for performance monitoring. Set the action name in each endpoint using
+    # the {Appsignal::Helpers::Instrumentation#set_action} helper.
+    #
+    # If multiple of these middlewares, or
+    # {AbstractMiddleware} subclasses are present in an app, only the top
+    # middleware will report errors from apps and other middleware.
+    #
+    # This middleware is best used in combination with the {EventHandler}.
+    #
+    # @example
+    #   # config.ru
+    #   require "appsignal"
+    #   # Configure and start AppSignal
+    #
+    #   # Add the EventHandler first
+    #   use ::Rack::Events, [Appsignal::Rack::EventHandler.new]
+    #   # Add the instrumentation middleware second
+    #   use Appsignal::Rack::InstrumentationMiddleware
+    #
+    #   # Other middleware
+    #
+    #   # Start app
+    #
+    # @example Customize instrumentation event category
+    #   use Appsignal::Rack::InstrumentationMiddleware,
+    #     :instrument_event_name => "custom.goup"
+    #
+    # @example Disable error reporting for this middleware
+    #   use Appsignal::Rack::InstrumentationMiddleware, :report_errors => false
+    #
+    # @example Always report errors, even when wrapped by other instrumentation middleware
+    #   use Appsignal::Rack::InstrumentationMiddleware, :report_errors => true
+    #
+    # @example Disable error reporting for this middleware based on the request env
+    #   use Appsignal::Rack::InstrumentationMiddleware,
+    #     :report_errors => lambda { |env| env["some_key"] == "some value" }
+    #
+    # @see https://docs.appsignal.com/ruby/integrations/rack.html
+    # @api public
+    class InstrumentationMiddleware < AbstractMiddleware
+      def initialize(app, options = {})
+        options[:instrument_event_name] ||= "process_request_middleware.rack"
+        super
+      end
+    end
+  end
+end

data/lib/appsignal/rack/rails_instrumentation.rb

@@ -1,70 +1,27 @@
 # frozen_string_literal: true
 
-require "rack"
-
 module Appsignal
-  # @api private
   module Rack
-    class RailsInstrumentation
+    # @api private
+    class RailsInstrumentation < Appsignal::Rack::AbstractMiddleware
       def initialize(app, options = {})
-        Appsignal.internal_logger.debug "Initializing Appsignal::Rack::RailsInstrumentation"
-        @app = app
-        @options = options
-      end
-
-      def call(env)
-        if Appsignal.active?
-          call_with_appsignal_monitoring(env)
-        else
-          @app.call(env)
-        end
-      end
-
-      def call_with_appsignal_monitoring(env)
-        request = ActionDispatch::Request.new(env)
-        transaction = env.fetch(
-          Appsignal::Rack::APPSIGNAL_TRANSACTION,
-          Appsignal::Transaction::NilTransaction.new
-        )
-
-        begin
-          @app.call(env)
-        rescue Exception => error # rubocop:disable Lint/RescueException
-          transaction.set_error(error)
-          raise error
-        ensure
-          controller = env["action_controller.instance"]
-          if controller
-            transaction.set_action_if_nil("#{controller.class}##{controller.action_name}")
-          end
-          transaction.set_params_if_nil(fetch_params(request))
-          request_id = fetch_request_id(env)
-          transaction.set_tags(:request_id => request_id) if request_id
-          transaction.set_metadata("path", request.path)
-          request_method = fetch_request_method(request)
-          transaction.set_metadata("method", request_method) if request_method
-        end
+        options[:request_class] ||= ActionDispatch::Request
+        options[:params_method] ||= :filtered_parameters
+        options[:instrument_event_name] = nil
+        options[:report_errors] = true
+        super
       end
 
-      def fetch_request_id(env)
-        env["action_dispatch.request_id"]
-      end
+      private
 
-      def fetch_params(request)
-        return unless request.respond_to?(:filtered_parameters)
+      def add_transaction_metadata_after(transaction, request)
+        controller = request.env["action_controller.instance"]
+        transaction.set_action_if_nil("#{controller.class}##{controller.action_name}") if controller
 
-        request.filtered_parameters
-      rescue => error
-        # Getting params from the request has been know to fail.
-        Appsignal.internal_logger.debug "Exception while getting Rails params: #{error}"
-        nil
-      end
+        request_id = request.env["action_dispatch.request_id"]
+        transaction.set_tags(:request_id => request_id) if request_id
 
-      def fetch_request_method(request)
-        request.request_method
-      rescue => error
-        Appsignal.internal_logger.error("Unable to report HTTP request method: '#{error}'")
-        nil
+        super
       end
     end
   end

data/lib/appsignal/rack/sinatra_instrumentation.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require "rack"
-
 module Appsignal
   module Rack
     # Stub old middleware. Prevents Sinatra middleware being loaded twice.
@@ -34,7 +32,7 @@ module Appsignal
       def initialize(app, options = {})
         options[:request_class] ||= Sinatra::Request
         options[:params_method] ||= :params
-        options[:instrument_span_name] ||= "process_action.sinatra"
+        options[:instrument_event_name] ||= "process_action.sinatra"
         super
         @raise_errors_on = raise_errors?(app)
       end