appsignal 4.5.17 → 4.7.0

data/lib/appsignal/logger.rb

@@ -13,6 +13,8 @@ module Appsignal
     # If called again, it will return the result of the first call.
     # This is useful for ensuring that a block is not executed multiple
     # times when it is broadcasted to multiple loggers.
+    #
+    # @!visibility private
     class BlockOnce
       def initialize(&block)
         @block = block
@@ -44,9 +46,13 @@ module Appsignal
       end
     end
 
+    # @!visibility private
     PLAINTEXT = 0
+    # @!visibility private
     LOGFMT = 1
+    # @!visibility private
     JSON = 2
+    # @!visibility private
     SEVERITY_MAP = {
       DEBUG => 2,
       INFO => 3,
@@ -55,14 +61,17 @@ module Appsignal
       FATAL => 7
     }.freeze
 
+    # Logging severity threshold
+    # @return [Integer]
     attr_reader :level
 
     # Create a new logger instance
     #
-    # @param group Name of the group for this logger.
-    # @param level Minimum log level to report. Log lines below this level will be ignored.
-    # @param format Format to use to parse log line attributes.
-    # @param attributes Default attributes for all log lines.
+    # @param group [String] Name of the group for this logger.
+    # @param level [Integer] Minimum log level to report. Log lines below this
+    #   level will be ignored.
+    # @param format [Integer] Format to use to parse log line attributes.
+    # @param attributes [Hash<String, String>] Default attributes for all log lines.
     # @return [void]
     def initialize(group, level: INFO, format: PLAINTEXT, attributes: {})
       raise TypeError, "group must be a string" unless group.is_a? String
@@ -77,9 +86,9 @@ module Appsignal
       @loggers = []
     end
 
-    # When a formatter is set on the logger (e.g. when wrapping the logger in
-    # `ActiveSupport::TaggedLogging`) we want to set that formatter on all the
-    # loggers that are being broadcasted to.
+    # Sets the formatter for this logger and all broadcasted loggers.
+    # @param formatter [Proc] The formatter to use for log messages.
+    # @return [Proc]
     def formatter=(formatter)
       super
       @loggers.each { |logger| logger.formatter = formatter }
@@ -87,7 +96,7 @@ module Appsignal
 
     # We support the various methods in the Ruby
     # logger class by supplying this method.
-    # @api private
+    # @!visibility private
     def add(severity, message = nil, group = nil, &block) # rubocop:disable Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
       # If we do not need to broadcast to any loggers and the severity is
       # below the log level, we can return early.
@@ -142,40 +151,40 @@ module Appsignal
     alias log add
 
     # Log a debug level message
-    # @param message Message to log
-    # @param attributes Attributes to tag the log with
+    # @param message [String] Message to log
+    # @param attributes [Hash<String, Object>] Attributes to tag the log with
     # @return [void]
     def debug(message = nil, attributes = {}, &block)
       add_with_attributes(DEBUG, message, @group, attributes, &block)
     end
 
     # Log an info level message
-    # @param message Message to log
-    # @param attributes Attributes to tag the log with
+    # @param message [String] Message to log
+    # @param attributes [Hash<String, Object>] Attributes to tag the log with
     # @return [void]
     def info(message = nil, attributes = {}, &block)
       add_with_attributes(INFO, message, @group, attributes, &block)
     end
 
     # Log a warn level message
-    # @param message Message to log
-    # @param attributes Attributes to tag the log with
+    # @param message [String] Message to log
+    # @param attributes [Hash<String, Object>] Attributes to tag the log with
     # @return [void]
     def warn(message = nil, attributes = {}, &block)
       add_with_attributes(WARN, message, @group, attributes, &block)
     end
 
     # Log an error level message
-    # @param message Message to log
-    # @param attributes Attributes to tag the log with
+    # @param message [String, Exception] Message to log
+    # @param attributes [Hash<String, Object>] Attributes to tag the log with
     # @return [void]
     def error(message = nil, attributes = {}, &block)
       add_with_attributes(ERROR, message, @group, attributes, &block)
     end
 
     # Log a fatal level message
-    # @param message Message to log
-    # @param attributes Attributes to tag the log with
+    # @param message [String, Exception] Message to log
+    # @param attributes [Hash<String, Object>] Attributes to tag the log with
     # @return [void]
     def fatal(message = nil, attributes = {}, &block)
       add_with_attributes(FATAL, message, @group, attributes, &block)
@@ -185,13 +194,15 @@ module Appsignal
     #
     # Returns the number of characters written.
     #
-    # @param message Message to log
+    # @param message [String] Message to log
     # @return [Integer]
     def <<(message)
       info(message)
       message.length
     end
 
+    # Temporarily silences the logger to a specified level while executing a block.
+    #
     # When using ActiveSupport::TaggedLogging without the broadcast feature,
     # the passed logger is required to respond to the `silence` method.
     #
@@ -199,6 +210,9 @@ module Appsignal
     #
     # - https://github.com/rails/rails/blob/e11ebc04cfbe41c06cdfb70ee5a9fdbbd98bb263/activesupport/lib/active_support/logger.rb#L60-L76
     # - https://github.com/rails/rails/blob/e11ebc04cfbe41c06cdfb70ee5a9fdbbd98bb263/activesupport/lib/active_support/logger_silence.rb
+    #
+    # @param severity [Integer] The minimum severity level to log during the block.
+    # @return [Object] The return value of the block.
     def silence(severity = ERROR, &block)
       previous_level = @level
       @level = severity
@@ -209,6 +223,9 @@ module Appsignal
       @silenced = false
     end
 
+    # Adds a logger to broadcast log messages to.
+    # @param logger [Logger] The logger to add to the broadcast list.
+    # @return [Array<Logger>]
     def broadcast_to(logger)
       @loggers << logger
     end

data/lib/appsignal/marker.rb

@@ -20,7 +20,7 @@ module Appsignal
   # @see Appsignal::CLI::NotifyOfDeploy
   # @see https://docs.appsignal.com/appsignal/terminology.html#markers
   #   Terminology: Deploy marker
-  # @api private
+  # @!visibility private
   class Marker
     # Path used on the AppSignal Push API
     # https://push.appsignal.com/1/markers

data/lib/appsignal/probes/gvl.rb

@@ -2,21 +2,22 @@
 
 module Appsignal
   module Probes
+    # @!visibility private
     class GvlProbe
       include Helpers
 
-      # @api private
+      # @!visibility private
       def self.dependencies_present?
         defined?(::GVLTools) && gvltools_0_2_or_newer? && ruby_3_2_or_newer? &&
           !Appsignal::System.jruby?
       end
 
-      # @api private
+      # @!visibility private
       def self.gvltools_0_2_or_newer?
         Gem::Version.new(::GVLTools::VERSION) >= Gem::Version.new("0.2.0")
       end
 
-      # @api private
+      # @!visibility private
       def self.ruby_3_2_or_newer?
         Gem::Version.new(RUBY_VERSION) >= Gem::Version.new("3.2.0")
       end

data/lib/appsignal/probes/helpers.rb

@@ -2,7 +2,7 @@
 
 module Appsignal
   module Probes
-    # @api private
+    # @!visibility private
     module Helpers
       private
 

data/lib/appsignal/probes/mri.rb

@@ -2,11 +2,11 @@
 
 module Appsignal
   module Probes
-    # @api private
+    # @!visibility private
     class MriProbe
       include Helpers
 
-      # @api private
+      # @!visibility private
       def self.dependencies_present?
         defined?(::RubyVM) && ::RubyVM.respond_to?(:stat)
       end
@@ -17,7 +17,7 @@ module Appsignal
         @gc_profiler = gc_profiler
       end
 
-      # @api private
+      # @!visibility private
       def call
         stat = RubyVM.stat
 

data/lib/appsignal/probes/sidekiq.rb

@@ -2,7 +2,7 @@
 
 module Appsignal
   module Probes
-    # @api private
+    # @!visibility private
     class SidekiqProbe
       include Helpers
 
@@ -38,14 +38,15 @@ module Appsignal
         end
       end
 
-      # @api private
+      # @!visibility private
       attr_reader :config
 
+      # @!visibility private
       def self.sidekiq7_and_greater?
         Gem::Version.new(::Sidekiq::VERSION) >= Gem::Version.new("7.0.0")
       end
 
-      # @api private
+      # @!visibility private
       def self.dependencies_present?
         return true if sidekiq7_and_greater?
         return false unless defined?(::Redis::VERSION) # Sidekiq <= 6

data/lib/appsignal/probes.rb

@@ -2,10 +2,11 @@
 
 module Appsignal
   module Probes
-    # @api private
+    # @return [Integer]
+    # @!visibility private
     ITERATION_IN_SECONDS = 60
 
-    # @api private
+    # @!visibility private
     class ProbeCollection
       def initialize
         @probes = {}
@@ -23,13 +24,12 @@ module Appsignal
       end
 
       # Fetch a probe using its name.
-      # @param key [Symbol/String] The name of the probe to fetch.
+      # @param key [Symbol, String] The name of the probe to fetch.
       # @return [Object] Returns the registered probe.
       def [](key)
         probes[key]
       end
 
-      # @api private
       def internal_register(name, probe)
         if probes.key?(name)
           logger.debug "A probe with the name `#{name}` is already " \
@@ -38,12 +38,10 @@ module Appsignal
         probes[name] = probe
       end
 
-      # @api private
       def unregister(name)
         probes.delete(name)
       end
 
-      # @api private
       def each(&block)
         probes.each(&block)
       end
@@ -58,14 +56,14 @@ module Appsignal
     end
 
     class << self
-      # @api private
+      # @!visibility private
       def mutex
         @mutex ||= Thread::Mutex.new
       end
 
       # @see ProbeCollection
       # @return [ProbeCollection] Returns list of probes.
-      # @api private
+      # @!visibility private
       def probes
         @probes ||= ProbeCollection.new
       end
@@ -129,7 +127,7 @@ module Appsignal
       #   # "started" # Printed on Appsignal::Probes.start
       #   # "called" # Repeated every minute
       #
-      # @param name [Symbol/String] Name of the probe. Can be used with
+      # @param name [Symbol, String] Name of the probe. Can be used with
       #   {ProbeCollection#[]}. This name will be used in errors in the log and
       #   allows overwriting of probes by registering new ones with the same
       #   name.
@@ -153,7 +151,7 @@ module Appsignal
       #   # Then unregister a probe if needed
       #   Appsignal::Probes.unregister :my_probe
       #
-      # @param name [Symbol/String] Name of the probe used to {register} the
+      # @param name [Symbol, String] Name of the probe used to {register} the
       #   probe.
       # @return [void]
       def unregister(name)
@@ -162,6 +160,7 @@ module Appsignal
         uninitialize_probe(name)
       end
 
+      # @return [void]
       # @api private
       def start
         stop
@@ -184,8 +183,10 @@ module Appsignal
                 logger.debug("Gathering minutely metrics with '#{name}' probe")
                 probe.call
               rescue => ex
-                logger.error "Error in minutely probe '#{name}': #{ex}"
-                logger.debug ex.backtrace.join("\n")
+                logger.error(
+                  "Error in minutely probe '#{name}': #{ex.class}: #{ex.message}\n" \
+                    "#{ex.backtrace.join("\n")}"
+                )
               end
             end
             end_time = Time.now
@@ -212,13 +213,15 @@ module Appsignal
 
       # Stop the minutely probes mechanism. Stop the thread and clear all probe
       # instances.
+      #
+      # @return [void]
       def stop
         defined?(@thread) && @thread.kill
         @started = false
         probe_instances.clear
       end
 
-      # @api private
+      # @!visibility private
       def wait_time
         ITERATION_IN_SECONDS - Time.now.sec
       end
@@ -256,8 +259,10 @@ module Appsignal
         end
       rescue => error
         logger = Appsignal.internal_logger
-        logger.error "Error while initializing minutely probe '#{name}': #{error}"
-        logger.debug error.backtrace.join("\n")
+        logger.error(
+          "Error while initializing minutely probe '#{name}': #{error.class}: #{error.message}\n" \
+            "#{error.backtrace.join("\n")}"
+        )
       end
 
       def uninitialize_probe(name)

data/lib/appsignal/rack/event_handler.rb

@@ -2,10 +2,11 @@
 
 module Appsignal
   module Rack
-    # Instrumentation middleware using Rack's Events module.
+    # Instrumentation event handler for `Rack::Events`.
     #
-    # We recommend using this in combination with the
-    # {InstrumentationMiddleware}.
+    # Using this middleware directly with `Rack::Events` is deprecated.
+    # We recommend using {EventMiddleware} instead, which is compatible with
+    # streaming bodies, in combination with the {InstrumentationMiddleware}.
     #
     # This middleware will report the response status code as the
     # `response_status` tag on the sample. It will also report the response
@@ -38,10 +39,12 @@ module Appsignal
 
       # @api private
       attr_reader :id
+      attr_writer :using_appsignal_rack_events_middleware
 
       # @api private
       def initialize
         @id = SecureRandom.uuid
+        @using_appsignal_rack_events_middleware = false
       end
 
       # @api private
@@ -51,6 +54,8 @@ module Appsignal
 
       # @api private
       def on_start(request, _response)
+        emit_warning_once
+
         return unless Appsignal.active?
 
         event_handler = self
@@ -152,6 +157,19 @@ module Appsignal
           namespace
         end
       end
+
+      def emit_warning_once
+        return if @using_appsignal_rack_events_middleware
+
+        Appsignal.internal_logger.warn <<~MSG
+          Rack::Events is not compatible with streaming bodies. Using `Appsignal::Rack::EventHandler`#{" "}
+          with `Rack::Events` will break streaming responses in your application and is deprecated.#{" "}
+          To silence this warning, use `Appsignal::Rack::EventMiddleware` instead, which is compatible#{" "}
+          with streaming bodies.#{" "}
+          See https://docs.appsignal.com/ruby/integrations/rack.html for more information.
+        MSG
+        @using_appsignal_rack_events_middleware = true
+      end
     end
   end
 end

data/lib/appsignal/rack/event_middleware.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module Appsignal
+  module Rack
+    # Modified version of the {::Rack::Events} instrumentation
+    # middleware.
+    #
+    # We recommend using this instead of {::Rack::Events}, as it
+    # is compatible with streaming bodies.
+    #
+    # We do not recommend using this middleware directly, instead
+    # recommending the use of {EventMiddleware}, which is a
+    # convenience wrapper around this middleware that includes
+    # AppSignal's {EventHandler}.
+    #
+    # See the original implementation at:
+    # https://github.com/rack/rack/blob/8d3d7857fcd9e5df057a6c22458bab35b3a19c12/lib/rack/events.rb
+    class Events < ::Rack::Events
+      # A stub for {::Rack::Events::EventedBodyProxy}. It
+      # allows the same initialization arguments, but
+      # otherwise behaves identically to {::Rack::BodyProxy}.
+      #
+      # It does not implement `#each`, fixing an issue
+      # where the evented body proxy would break
+      # streaming responses by always responding to `#each`
+      # even if the proxied body did not implement it.
+      #
+      # Because it ignores the handlers passed to it and
+      # behaves like a normal body proxy, the `on_send`
+      # event on the handlers is never called.
+      class EventedBodyProxy < ::Rack::BodyProxy
+        def initialize(body, _request, _response, _handlers, &block)
+          super(body, &block)
+        end
+      end
+
+      # Notifies the AppSignal event handler that it's being
+      # used with the modified middleware, suppressing a
+      # deprecation warning.
+      def initialize(app, handlers = [])
+        super
+        handlers.each do |handler|
+          if handler.respond_to?(:using_appsignal_rack_events_middleware=)
+            handler.using_appsignal_rack_events_middleware = true
+          end
+        end
+      end
+
+      # The `call` method, exactly as implemented by {::Rack::Events},
+      # but redefined here so that it uses our {EventedBodyProxy}
+      # instead of the original {::Rack::Events::EventedBodyProxy}.
+      #
+      # This fixes streaming bodies, but it also means that the
+      # `on_send` event on the handlers is never called.
+      #
+      # See the original implementation at:
+      # https://github.com/rack/rack/blob/8d3d7857fcd9e5df057a6c22458bab35b3a19c12/lib/rack/events.rb#L111-L129
+      def call(env)
+        request = make_request env
+        on_start request, nil
+
+        begin
+          status, headers, body = @app.call request.env
+          response = make_response status, headers, body
+          on_commit request, response
+        rescue StandardError => e
+          on_error request, response, e
+          on_finish request, response
+          raise
+        end
+
+        body = EventedBodyProxy.new(body, request, response, @handlers) do
+          on_finish request, response
+        end
+        [response.status, response.headers, body]
+      end
+    end
+
+    # Instrumentation middleware using Rack's Events module.
+    #
+    # A convenience wrapper around our {Events} middleware,
+    # modified to be compatible with streaming bodies,
+    # that automatically includes AppSignal's {EventHandler}.
+    #
+    # We recommend using this in combination with the
+    # {InstrumentationMiddleware}.
+    #
+    # This middleware will report the response status code as the
+    # `response_status` tag on the sample. It will also report the response
+    # status as the `response_status` metric.
+    #
+    # This middleware will ensure the AppSignal transaction is always completed
+    # for every request.
+    #
+    # @example Add EventMiddleware to a Rack app
+    #   # Add this middleware as the first middleware of an app
+    #   use Appsignal::Rack::EventMiddleware
+    #
+    #   # Then add the InstrumentationMiddleware
+    #   use Appsignal::Rack::InstrumentationMiddleware
+    #
+    # @see https://docs.appsignal.com/ruby/integrations/rack.html
+    #   Rack integration documentation.
+    # @api public
+    class EventMiddleware < Events
+      def initialize(app)
+        super(app, [Appsignal::Rack::EventHandler.new])
+      end
+    end
+  end
+end

data/lib/appsignal/rack/instrumentation_middleware.rb

@@ -27,8 +27,8 @@ module Appsignal
     #   require "appsignal"
     #   # Configure and start AppSignal
     #
-    #   # Add the EventHandler first
-    #   use ::Rack::Events, [Appsignal::Rack::EventHandler.new]
+    #   # Add the EventMiddleware first
+    #   use Appsignal::Rack::EventMiddleware
     #   # Add the instrumentation middleware second
     #   use Appsignal::Rack::InstrumentationMiddleware
     #

data/lib/appsignal/rack.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Appsignal
-  # @api private
+  # @!visibility private
   module Rack
     APPSIGNAL_TRANSACTION = "appsignal.transaction"
     APPSIGNAL_EVENT_HANDLER_ID = "appsignal.event_handler_id"

data/lib/appsignal/sample_data.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Appsignal
-  # @api private
+  # @!visibility private
   class SampleData
     def initialize(key, accepted_type = nil)
       @key = key
@@ -21,7 +21,6 @@ module Appsignal
       end
     end
 
-    # @api private
     def set_empty_value!
       @empty = true
       @blocks.clear
@@ -36,12 +35,18 @@ module Appsignal
           else
             block_or_value
           end
+
         unless accepted_type?(new_value)
           log_unsupported_data_type(new_value)
           next
         end
 
-        value = merge_values(value, new_value)
+        # Before trying to merge values, convert them to Ruby classes
+        # This way we don't need to check if something is of a type often
+        value_new = convert_to_ruby_class(new_value)
+        value_original = convert_to_ruby_class(value)
+
+        value = merge_values(value_original, value_new)
         new_value
       end
 
@@ -52,7 +57,6 @@ module Appsignal
       @blocks.any?
     end
 
-    # @api private
     def empty?
       @empty
     end
@@ -81,15 +85,19 @@ module Appsignal
       end
     end
 
+    def mergable?(value_original, value_new)
+      value_new.instance_of?(value_original.class)
+    end
+
     def merge_values(value_original, value_new)
-      unless value_new.instance_of?(value_original.class)
-        unless value_original == UNSET_VALUE
-          Appsignal.internal_logger.warn(
-            "The sample data '#{@key}' changed type from " \
-              "'#{value_original.class}' to '#{value_new.class}'. " \
-              "These types can not be merged. Using new '#{value_new.class}' type."
-          )
-        end
+      return value_new if value_original == UNSET_VALUE
+
+      unless mergable?(value_original, value_new)
+        Appsignal.internal_logger.warn(
+          "The sample data '#{@key}' changed type from " \
+            "'#{value_original.class}' to '#{value_new.class}'. " \
+            "These types can not be merged. Using new '#{value_new.class}' type."
+        )
         return value_new
       end
 
@@ -103,6 +111,17 @@ module Appsignal
       end
     end
 
+    # Convert any subclasses of Hash to a Ruby Hash class, so we don't have to
+    # account for the original value being a value that's not a pure Hash or
+    # Array object.
+    def convert_to_ruby_class(value)
+      if value.is_a? Hash
+        value.to_h
+      else
+        value
+      end
+    end
+
     def log_unsupported_data_type(value)
       Appsignal.internal_logger.error(
         "Sample data '#{@key}': Unsupported data type '#{value.class}' received: #{value.inspect}"

data/lib/appsignal/span.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Appsignal
-  # @api private
+  # @!visibility private
   class Span
     def initialize(namespace = nil, ext = nil)
       @ext = ext || Appsignal::Extension::Span.root(namespace || "")