appsignal 4.5.17 → 4.6.0

data/lib/appsignal/event_formatter.rb

@@ -12,16 +12,33 @@ module Appsignal
   # argument if you need to use helper methods.
   class EventFormatter
     class << self
-      # @api private
+      # @!visibility private
       def formatters
         @formatters ||= {}
       end
 
-      # @api private
+      # @!visibility private
       def formatter_classes
         @formatter_classes ||= {}
       end
 
+      # Registers an event formatter for a specific event name.
+      #
+      # @param name [String, Symbol] The name of the event to register the formatter for.
+      # @param formatter [Class] The formatter class that implements the `format(payload)` method.
+      # @return [void]
+      #
+      # @example Register a custom formatter
+      #   class CustomFormatter < Appsignal::EventFormatter
+      #     def format(payload)
+      #       ["Custom event", payload[:body]]
+      #     end
+      #   end
+      #
+      #   Appsignal::EventFormatter.register("my.event", CustomFormatter)
+      #
+      # @see #unregister
+      # @see #registered?
       def register(name, formatter = nil)
         if registered?(name, formatter)
           logger.warn(
@@ -34,6 +51,17 @@ module Appsignal
         initialize_formatter name, formatter
       end
 
+      # Unregisters an event formatter for a specific event name.
+      #
+      # @param name [String, Symbol] The name of the event to unregister the formatter for.
+      # @param formatter [Class] The formatter class to unregister. Defaults to `self`.
+      # @return [void]
+      #
+      # @example Unregister a custom formatter
+      #   Appsignal::EventFormatter.unregister("my.event", CustomFormatter)
+      #
+      # @see #register
+      # @see #registered?
       def unregister(name, formatter = self)
         return unless formatter_classes[name] == formatter
 
@@ -41,6 +69,14 @@ module Appsignal
         formatters.delete(name)
       end
 
+      # Checks if an event formatter is registered for a specific event name.
+      #
+      # @param name [String, Symbol] The name of the event to check.
+      # @param klass [Class, nil] The specific formatter class to check for. Optional.
+      # @return [Boolean] true if a formatter is registered, false otherwise.
+      #
+      # @see #register
+      # @see #unregister
       def registered?(name, klass = nil)
         if klass
           formatter_classes[name] == klass
@@ -49,7 +85,7 @@ module Appsignal
         end
       end
 
-      # @api private
+      # @!visibility private
       def format(name, payload)
         formatter = formatters[name]
         formatter&.format(payload)
@@ -76,8 +112,10 @@ module Appsignal
       end
     end
 
+    # @return [Integer]
     # @api public
     DEFAULT = 0
+    # @return [Integer]
     # @api public
     SQL_BODY_FORMAT = 1
   end

data/lib/appsignal/extension.rb

@@ -18,7 +18,7 @@ rescue LoadError => error
 end
 
 module Appsignal
-  # @api private
+  # @!visibility private
   class Extension
     class << self
       def agent_config

data/lib/appsignal/garbage_collection.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Appsignal
-  # @api private
+  # @!visibility private
   module GarbageCollection
     # Return the GC profiler wrapper.
     #

data/lib/appsignal/helpers/instrumentation.rb

@@ -89,7 +89,7 @@ module Appsignal
       #   end
       #
       # @since 3.11.0
-      # @param namespace [String/Symbol] The namespace to set on the new
+      # @param namespace [String, Symbol] The namespace to set on the new
       #   transaction.
       #   Defaults to the 'web' namespace.
       #   This will not update the active transaction's namespace if
@@ -102,15 +102,18 @@ module Appsignal
       #   within the block with {#set_action}.
       #   This will not update the active transaction's action if
       #   {.monitor} is called when another transaction is already active.
-      # @yield The block to monitor.
+      # @yield [] The block to monitor.
+      # @yieldreturn [Object] The return value of the block
       # @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.
+      # @return [Object, nil] The value of the given block is returned.
+      #   Returns `nil` if there already is a transaction active and no block
+      #   was given.
       #
       # @see https://docs.appsignal.com/ruby/instrumentation/background-jobs.html
       #   Monitor guide
       def monitor(action:, namespace: nil)
-        return yield unless active?
+        return yield unless Appsignal.active?
 
         has_parent_transaction = Appsignal::Transaction.current?
         if has_parent_transaction
@@ -152,6 +155,25 @@ module Appsignal
       # Acts the same way as {.monitor}. See that method for more
       # documentation.
       #
+      # @param namespace [String, Symbol] The namespace to set on the new
+      #   transaction.
+      #   Defaults to the 'web' namespace.
+      #   This will not update the active transaction's namespace if
+      #   {.monitor} is called when another transaction is already active.
+      # @param action [String, Symbol, NilClass]
+      #   The action name for the transaction.
+      #   The action name is required to be set for the transaction to be
+      #   reported.
+      #   The argument can be set to `nil` or `:set_later` if the action is set
+      #   within the block with {#set_action}.
+      #   This will not update the active transaction's action if
+      #   {.monitor} is called when another transaction is already active.
+      # @yield [] The block to monitor.
+      # @yieldreturn [Object] The return value of the block
+      # @raise [Exception] Any exception that occurs within the given block is
+      #   re-raised by this method.
+      # @return [Object, nil] The value of the given block is returned.
+      #
       # @see monitor
       def monitor_and_stop(action:, namespace: nil, &block)
         Appsignal::Utils::StdoutAndLoggerMessage.warning \
@@ -205,10 +227,11 @@ module Appsignal
       # @see https://docs.appsignal.com/ruby/instrumentation/exception-handling.html
       #   Exception handling guide
       def send_error(error, &block)
-        return unless active?
+        return unless Appsignal.active?
 
         unless error.is_a?(Exception)
-          internal_logger.error "Appsignal.send_error: Cannot send error. " \
+          Appsignal.internal_logger.error "Appsignal.send_error: " \
+            "Cannot send error. " \
             "The given value is not an exception: #{error.inspect}"
           return
         end
@@ -271,11 +294,12 @@ module Appsignal
       #   Exception handling guide
       def set_error(exception)
         unless exception.is_a?(Exception)
-          internal_logger.error "Appsignal.set_error: Cannot set error. " \
+          Appsignal.internal_logger.error "Appsignal.set_error: " \
+            "Cannot set error. " \
             "The given value is not an exception: #{exception.inspect}"
           return
         end
-        return if !active? || !Appsignal::Transaction.current?
+        return if !Appsignal.active? || !Appsignal::Transaction.current?
 
         transaction = Appsignal::Transaction.current
         transaction.set_error(exception)
@@ -334,11 +358,12 @@ module Appsignal
       #   Exception handling guide
       def report_error(exception, &block)
         unless exception.is_a?(Exception)
-          internal_logger.error "Appsignal.report_error: Cannot add error. " \
+          Appsignal.internal_logger.error "Appsignal.report_error: " \
+            "Cannot add error. " \
             "The given value is not an exception: #{exception.inspect}"
           return
         end
-        return unless active?
+        return unless Appsignal.active?
 
         has_parent_transaction = Appsignal::Transaction.current?
         transaction =
@@ -376,7 +401,7 @@ module Appsignal
       # @param action [String]
       # @return [void]
       def set_action(action)
-        return if !active? ||
+        return if !Appsignal.active? ||
           !Appsignal::Transaction.current? ||
           action.nil?
 
@@ -418,7 +443,7 @@ module Appsignal
       # @see https://docs.appsignal.com/guides/namespaces.html
       #   Grouping with namespaces guide
       def set_namespace(namespace)
-        return if !active? ||
+        return if !Appsignal.active? ||
           !Appsignal::Transaction.current? ||
           namespace.nil?
 
@@ -459,13 +484,14 @@ module Appsignal
       #   # The custom data is: [1, 2, 3]
       #
       # @since 4.0.0
-      # @param data [Hash/Array] Custom data to add to the transaction.
+      # @param data [Hash<Object, Object>, Array<Object>] Custom data to add to
+      #   the transaction.
       # @return [void]
       #
       # @see https://docs.appsignal.com/guides/custom-data/sample-data.html
       #   Sample data guide
       def add_custom_data(data)
-        return unless active?
+        return unless Appsignal.active?
         return unless Appsignal::Transaction.current?
 
         transaction = Appsignal::Transaction.current
@@ -499,7 +525,8 @@ module Appsignal
       #   end
       #
       # @since 4.0.0
-      # @param tags [Hash] Collection of tags to add to the transaction.
+      # @param tags [Hash<Object, Object>] 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"
@@ -509,7 +536,7 @@ module Appsignal
       # @see https://docs.appsignal.com/ruby/instrumentation/tagging.html
       #   Tagging guide
       def add_tags(tags = {})
-        return unless active?
+        return unless Appsignal.active?
         return unless Appsignal::Transaction.current?
 
         transaction = Appsignal::Transaction.current
@@ -525,25 +552,41 @@ module Appsignal
       # should not be necessary to call this method unless you want to report
       # different parameters.
       #
+      # This method accepts both Hash and Array parameter types:
+      # - Hash parameters will be merged when called multiple times
+      # - Array parameters will be concatenated when called multiple times
+      # - Mixing Hash and Array types will use the latest type (and log a warning)
+      #
       # To filter parameters, see our parameter filtering guide.
       #
       # When both the `params` argument and a block is given to this method,
       # the block is leading and the argument will _not_ be used.
       #
-      # @example Add parameters
+      # @example Add Hash parameters
       #   Appsignal.add_params("param1" => "value1")
       #   # The parameters include: { "param1" => "value1" }
       #
-      # @example Calling `add_params` multiple times will merge the values
+      # @example Add Array parameters
+      #   Appsignal.add_params(["item1", "item2"])
+      #   # The parameters include: ["item1", "item2"]
+      #
+      # @example Calling `add_params` multiple times with Hashes merges values
       #   Appsignal.add_params("param1" => "value1")
       #   Appsignal.add_params("param2" => "value2")
       #   # The parameters include:
       #   # { "param1" => "value1", "param2" => "value2" }
       #
+      # @example Calling `add_params` multiple times with Arrays concatenates values
+      #   Appsignal.add_params(["item1"])
+      #   Appsignal.add_params(["item2"])
+      #   # The parameters include: ["item1", "item2"]
+      #
       # @since 4.0.0
-      # @param params [Hash] The parameters to add to the transaction.
+      # @param params [Hash<String, Object>, Array<Object>] 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.
+      # @yieldreturn [Hash<String, Object>, Array<Object>]
       # @return [void]
       #
       # @see https://docs.appsignal.com/guides/custom-data/sample-data.html
@@ -551,7 +594,7 @@ module Appsignal
       # @see https://docs.appsignal.com/guides/filter-data/filter-parameters.html
       #   Parameter filtering guide
       def add_params(params = nil, &block)
-        return unless active?
+        return unless Appsignal.active?
         return unless Appsignal::Transaction.current?
 
         transaction = Appsignal::Transaction.current
@@ -576,7 +619,7 @@ module Appsignal
       # @see Transaction#set_empty_params!
       # @see Transaction#set_params_if_nil
       def set_empty_params!
-        return unless active?
+        return unless Appsignal.active?
         return unless Appsignal::Transaction.current?
 
         transaction = Appsignal::Transaction.current
@@ -606,9 +649,10 @@ module Appsignal
       #   # { "session" => "data", "other" => "value" }
       #
       # @since 4.0.0
-      # @param session_data [Hash] The session data to add to the transaction.
+      # @param session_data [Hash<String, Object>] 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.
+      # @yieldreturn [Hash<String, Object>]
       # @return [void]
       #
       # @see https://docs.appsignal.com/guides/custom-data/sample-data.html
@@ -616,7 +660,7 @@ module Appsignal
       # @see https://docs.appsignal.com/guides/filter-data/filter-session-data.html
       #   Session data filtering guide
       def add_session_data(session_data = nil, &block)
-        return unless active?
+        return unless Appsignal.active?
         return unless Appsignal::Transaction.current?
 
         transaction = Appsignal::Transaction.current
@@ -647,9 +691,10 @@ module Appsignal
       #   # { "PATH_INFO" => "/some-path", "HTTP_USER_AGENT" => "Firefox" }
       #
       # @since 4.0.0
-      # @param headers [Hash] The request headers to add to the transaction.
+      # @param headers [Hash<String, Object>] 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.
+      # @yieldreturn [Hash<String, Object>]
       # @return [void]
       #
       # @see https://docs.appsignal.com/guides/custom-data/sample-data.html
@@ -657,7 +702,7 @@ module Appsignal
       # @see https://docs.appsignal.com/guides/filter-data/filter-headers.html
       #   Request headers filtering guide
       def add_headers(headers = nil, &block)
-        return unless active?
+        return unless Appsignal.active?
         return unless Appsignal::Transaction.current?
 
         transaction = Appsignal::Transaction.current
@@ -668,7 +713,7 @@ module Appsignal
       # Add breadcrumbs to the transaction.
       #
       # Breadcrumbs can be used to trace what path a user has taken
-      # before encounterin an error.
+      # before encountering an error.
       #
       # Only the last 20 added breadcrumbs will be saved.
       #
@@ -697,15 +742,15 @@ module Appsignal
       #   e.g. "UI", "Network", "Navigation", "Console".
       # @param action [String] name of breadcrumb
       #   e.g "The user clicked a button", "HTTP 500 from http://blablabla.com"
-      # @option message [String]  optional message in string format
-      # @option metadata [Hash<String,String>]  key/value metadata in <string, string> format
-      # @option time [Time] time of breadcrumb, should respond to `.to_i` defaults to `Time.now.utc`
+      # @param message [String] optional message in string format
+      # @param metadata [Hash<String, String>] key/value metadata in <string, string> format
+      # @param time [Time] time of breadcrumb, should respond to `.to_i` defaults to `Time.now.utc`
       # @return [void]
       #
       # @see https://docs.appsignal.com/ruby/instrumentation/breadcrumbs.html
       #   Breadcrumb reference
       def add_breadcrumb(category, action, message = "", metadata = {}, time = Time.now.utc)
-        return unless active?
+        return unless Appsignal.active?
         return unless Appsignal::Transaction.current?
 
         transaction = Appsignal::Transaction.current
@@ -741,7 +786,7 @@ module Appsignal
       #   instrumented. Accepted values are {EventFormatter::DEFAULT} and
       #   {EventFormatter::SQL_BODY_FORMAT}, but we recommend you use
       #   {.instrument_sql} instead of {EventFormatter::SQL_BODY_FORMAT}.
-      # @yield yields the given block of code instrumented in an AppSignal
+      # @yield [] yields the given block of code instrumented in an AppSignal
       #   event.
       # @return [Object] Returns the block's return value.
       #
@@ -782,7 +827,7 @@ module Appsignal
       #   naming guide listed under "See also".
       # @param title [String, nil] Human readable name of the event.
       # @param body [String, nil] SQL query that's being executed.
-      # @yield yields the given block of code instrumented in an AppSignal
+      # @yield [] yields the given block of code instrumented in an AppSignal
       #   event.
       # @return [Object] Returns the block's return value.
       #
@@ -824,14 +869,16 @@ module Appsignal
       #   # Only the "my_event.my_group" instrumentation event is reported.
       #
       # @since 3.10.0
-      # @yield block of code that shouldn't be instrumented.
-      # @return [Object] Returns the return value of the block.
+      # @yield [] block of code that shouldn't be instrumented.
+      # @yieldreturn [Object] The return value of the block
+      # @return [Object, nil] Returns the return value of the block.
+      #   Return nil if the block returns nil or no block is given.
       #
       # @see https://docs.appsignal.com/ruby/instrumentation/ignore-instrumentation.html
       #   Ignore instrumentation guide
       def ignore_instrumentation_events
         Appsignal::Transaction.current&.pause!
-        yield
+        yield if block_given?
       ensure
         Appsignal::Transaction.current&.resume!
       end

data/lib/appsignal/helpers/metrics.rb

@@ -8,9 +8,10 @@ module Appsignal
       # @since 2.6.0
       # @param name [String, Symbol] The name of the metric.
       # @param value [Integer, Float] The value of the metric.
-      # @param tags [Hash] The tags for the metric. The Hash keys can be either
-      #   a String or a Symbol. The tag values can be a String, Symbol,
-      #   Integer, Float, TrueClass or FalseClass.
+      # @param tags [Hash<String, Object>] The tags for the metric. The Hash
+      #   keys can be either a String or a Symbol. The tag values can be a
+      #   String, Symbol, Integer, Float, TrueClass or FalseClass.
+      # @return [void]
       #
       # @see https://docs.appsignal.com/metrics/custom.html
       #   Metrics documentation
@@ -30,9 +31,10 @@ module Appsignal
       # @since 2.6.0
       # @param name [String, Symbol] The name of the metric.
       # @param value [Integer, Float] The value of the metric.
-      # @param tags [Hash] The tags for the metric. The Hash keys can be either
-      #   a String or a Symbol. The tag values can be a String, Symbol,
-      #   Integer, Float, TrueClass or FalseClass.
+      # @param tags [Hash<String, Object>] The tags for the metric. The Hash
+      #   keys can be either a String or a Symbol. The tag values can be a
+      #   String, Symbol, Integer, Float, TrueClass or FalseClass.
+      # @return [void]
       #
       # @see https://docs.appsignal.com/metrics/custom.html
       #   Metrics documentation
@@ -52,9 +54,10 @@ module Appsignal
       # @since 2.6.0
       # @param name [String, Symbol] The name of the metric.
       # @param value [Integer, Float] The value of the metric.
-      # @param tags [Hash] The tags for the metric. The Hash keys can be either
-      #   a String or a Symbol. The tag values can be a String, Symbol,
-      #   Integer, Float, TrueClass or FalseClass.
+      # @param tags [Hash<String, Object>] The tags for the metric. The Hash
+      #   keys can be either a String or a Symbol. The tag values can be a
+      #   String, Symbol, Integer, Float, TrueClass or FalseClass.
+      # @return [void]
       #
       # @see https://docs.appsignal.com/metrics/custom.html
       #   Metrics documentation

data/lib/appsignal/hooks/action_cable.rb

@@ -2,7 +2,7 @@
 
 module Appsignal
   class Hooks
-    # @api private
+    # @!visibility private
     class ActionCableHook < Appsignal::Hooks::Hook
       register :action_cable
 

data/lib/appsignal/hooks/action_mailer.rb

@@ -2,6 +2,7 @@
 
 module Appsignal
   class Hooks
+    # @!visibility private
     class ActionMailerHook < Appsignal::Hooks::Hook
       register :action_mailer
 

data/lib/appsignal/hooks/active_job.rb

@@ -2,7 +2,7 @@
 
 module Appsignal
   class Hooks
-    # @api private
+    # @!visibility private
     class ActiveJobHook < Appsignal::Hooks::Hook
       register :active_job
 

data/lib/appsignal/hooks/active_support_notifications.rb

@@ -2,7 +2,7 @@
 
 module Appsignal
   class Hooks
-    # @api private
+    # @!visibility private
     class ActiveSupportNotificationsHook < Appsignal::Hooks::Hook
       register :active_support_notifications
 

data/lib/appsignal/hooks/at_exit.rb

@@ -2,7 +2,7 @@
 
 module Appsignal
   class Hooks
-    # @api private
+    # @!visibility private
     class AtExit < Appsignal::Hooks::Hook
       register :at_exit
 

data/lib/appsignal/hooks/celluloid.rb

@@ -2,7 +2,7 @@
 
 module Appsignal
   class Hooks
-    # @api private
+    # @!visibility private
     class CelluloidHook < Appsignal::Hooks::Hook
       register :celluloid
 

data/lib/appsignal/hooks/data_mapper.rb

@@ -2,7 +2,7 @@
 
 module Appsignal
   class Hooks
-    # @api private
+    # @!visibility private
     class DataMapperHook < Appsignal::Hooks::Hook
       register :data_mapper
 

data/lib/appsignal/hooks/delayed_job.rb

@@ -2,7 +2,7 @@
 
 module Appsignal
   class Hooks
-    # @api private
+    # @!visibility private
     class DelayedJobHook < Appsignal::Hooks::Hook
       register :delayed_job
 

data/lib/appsignal/hooks/dry_monitor.rb

@@ -2,7 +2,7 @@
 
 module Appsignal
   class Hooks
-    # @api private
+    # @!visibility private
     class DryMonitorHook < Appsignal::Hooks::Hook
       register :dry_monitor
 

data/lib/appsignal/hooks/excon.rb

@@ -2,7 +2,7 @@
 
 module Appsignal
   class Hooks
-    # @api private
+    # @!visibility private
     class ExconHook < Appsignal::Hooks::Hook
       register :excon
 

data/lib/appsignal/hooks/gvl.rb

@@ -2,7 +2,7 @@
 
 module Appsignal
   class Hooks
-    # @api private
+    # @!visibility private
     class GvlHook < Appsignal::Hooks::Hook
       register :gvl
 

data/lib/appsignal/hooks/http.rb

@@ -2,7 +2,7 @@
 
 module Appsignal
   class Hooks
-    # @api private
+    # @!visibility private
     class HttpHook < Appsignal::Hooks::Hook
       register :http_rb
 

data/lib/appsignal/hooks/mongo_ruby_driver.rb

@@ -2,7 +2,7 @@
 
 module Appsignal
   class Hooks
-    # @api private
+    # @!visibility private
     class MongoRubyDriverHook < Appsignal::Hooks::Hook
       register :mongo_ruby_driver
 

data/lib/appsignal/hooks/mri.rb

@@ -2,7 +2,7 @@
 
 module Appsignal
   class Hooks
-    # @api private
+    # @!visibility private
     class MriHook < Appsignal::Hooks::Hook
       register :mri
 

data/lib/appsignal/hooks/net_http.rb

@@ -4,7 +4,7 @@ require "net/http"
 
 module Appsignal
   class Hooks
-    # @api private
+    # @!visibility private
     class NetHttpHook < Appsignal::Hooks::Hook
       register :net_http
 

data/lib/appsignal/hooks/ownership.rb

@@ -2,7 +2,7 @@
 
 module Appsignal
   class Hooks
-    # @api private
+    # @!visibility private
     class OwnershipHook < Appsignal::Hooks::Hook
       register :ownership
 

data/lib/appsignal/hooks/passenger.rb

@@ -2,7 +2,7 @@
 
 module Appsignal
   class Hooks
-    # @api private
+    # @!visibility private
     class PassengerHook < Appsignal::Hooks::Hook
       register :passenger
 

data/lib/appsignal/hooks/puma.rb

@@ -2,7 +2,7 @@
 
 module Appsignal
   class Hooks
-    # @api private
+    # @!visibility private
     class PumaHook < Appsignal::Hooks::Hook
       register :puma
 

data/lib/appsignal/hooks/que.rb

@@ -2,7 +2,7 @@
 
 module Appsignal
   class Hooks
-    # @api private
+    # @!visibility private
     class QueHook < Appsignal::Hooks::Hook
       register :que
 

data/lib/appsignal/hooks/rake.rb

@@ -2,7 +2,7 @@
 
 module Appsignal
   class Hooks
-    # @api private
+    # @!visibility private
     class RakeHook < Appsignal::Hooks::Hook
       register :rake