appsignal 4.5.17 → 4.6.0

data/lib/appsignal/transaction.rb

@@ -4,20 +4,23 @@ require "json"
 
 module Appsignal
   class Transaction
+    # @return [String]
     HTTP_REQUEST   = "http_request"
+    # @return [String]
     BACKGROUND_JOB = "background_job"
-    # @api private
+    # @!visibility private
     ACTION_CABLE   = "action_cable"
-    # @api private
+    # @!visibility private
     BLANK          = ""
-    # @api private
+    # @!visibility private
     ALLOWED_TAG_KEY_TYPES = [Symbol, String].freeze
-    # @api private
+    # @!visibility private
     ALLOWED_TAG_VALUE_TYPES = [Symbol, String, Integer, TrueClass, FalseClass].freeze
-    # @api private
+    # @!visibility private
     BREADCRUMB_LIMIT = 20
-    # @api private
+    # @!visibility private
     ERROR_CAUSES_LIMIT = 10
+    # @!visibility private
     ERRORS_LIMIT = 10
 
     class << self
@@ -49,12 +52,13 @@ module Appsignal
         end
       end
 
-      # @api private
-      # @return [Array<Proc>]
       # Add a block, if given, to be executed after a transaction is created.
       # The block will be called with the transaction as an argument.
       # Returns the array of blocks that will be executed after a transaction
       # is created.
+      #
+      # @return [Array<Proc>]
+      # @!visibility private
       def after_create(&block)
         @after_create ||= Set.new
 
@@ -63,8 +67,6 @@ module Appsignal
         @after_create << block
       end
 
-      # @api private
-      # @return [Array<Proc>]
       # Add a block, if given, to be executed before a transaction is completed.
       # This happens after duplicating the transaction for each error that was
       # reported in the transaction -- that is, when a transaction with
@@ -75,6 +77,9 @@ module Appsignal
       # and the error reported by the transaction, if any, as the second argument.
       # Returns the array of blocks that will be executed before a transaction is
       # completed.
+      #
+      # @return [Array<Proc>]
+      # @!visibility private
       def before_complete(&block)
         @before_complete ||= Set.new
 
@@ -83,7 +88,7 @@ module Appsignal
         @before_complete << block
       end
 
-      # @api private
+      # @!visibility private
       def set_current_transaction(transaction)
         Thread.current[:appsignal_transaction] = transaction
       end
@@ -91,7 +96,7 @@ module Appsignal
       # Set the current for the duration of the given block.
       # It restores the original transaction (if any) when the block has executed.
       #
-      # @api private
+      # @!visibility private
       def with_transaction(transaction)
         original_transaction = current if current?
         set_current_transaction(transaction)
@@ -104,7 +109,7 @@ module Appsignal
       # active.
       #
       # @see .current?
-      # @return [Boolean]
+      # @return [Appsignal::Transaction, Appsignal::Transaction::NilTransaction]
       def current
         Thread.current[:appsignal_transaction] || NilTransaction.new
       end
@@ -120,6 +125,8 @@ module Appsignal
 
       # Complete the currently active transaction and unset it as the active
       # transaction.
+      #
+      # @return [void]
       def complete_current!
         current.complete
       rescue => e
@@ -131,28 +138,28 @@ module Appsignal
       end
 
       # Remove current transaction from current Thread.
-      # @api private
+      # @!visibility private
       def clear_current_transaction!
         Thread.current[:appsignal_transaction] = nil
       end
 
-      # @api private
+      # @!visibility private
       def last_errors
         @last_errors ||= []
       end
 
-      # @api private
+      # @!visibility private
       attr_writer :last_errors
     end
 
-    # @api private
+    # @!visibility private
     attr_reader :transaction_id, :action, :namespace
 
     # Use {.create} to create new transactions.
     #
     # @param namespace [String] Namespace of the to be created transaction.
     # @see create
-    # @api private
+    # @!visibility private
     def initialize(namespace, id: SecureRandom.uuid, ext: nil)
       @transaction_id = id
       @action = nil
@@ -181,22 +188,22 @@ module Appsignal
       run_after_create_hooks
     end
 
-    # @api private
+    # @!visibility private
     def duplicate?
       @is_duplicate
     end
 
-    # @api private
+    # @!visibility private
     def nil_transaction?
       false
     end
 
-    # @api private
+    # @!visibility private
     def completed?
       @completed
     end
 
-    # @api private
+    # @!visibility private
     def complete
       if discarded?
         Appsignal.internal_logger.debug "Skipping transaction '#{transaction_id}' " \
@@ -248,37 +255,37 @@ module Appsignal
       @ext.complete
     end
 
-    # @api private
+    # @!visibility private
     def pause!
       @paused = true
     end
 
-    # @api private
+    # @!visibility private
     def resume!
       @paused = false
     end
 
-    # @api private
+    # @!visibility private
     def paused?
       @paused == true
     end
 
-    # @api private
+    # @!visibility private
     def discard!
       @discarded = true
     end
 
-    # @api private
+    # @!visibility private
     def restore!
       @discarded = false
     end
 
-    # @api private
+    # @!visibility private
     def discarded?
       @discarded == true
     end
 
-    # @api private
+    # @!visibility private
     def store(key)
       @store[key]
     end
@@ -291,9 +298,11 @@ module Appsignal
     # block is leading and the argument will _not_ be used.
     #
     # @since 4.0.0
-    # @param given_params [Hash] The parameters to set on the transaction.
+    # @param given_params [Hash<String, Object>, Array<Object>] 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.
+    # @yieldreturn [Hash<String, Object>, Array<Object>]
     # @return [void]
     #
     # @see Helpers::Instrumentation#add_params
@@ -304,9 +313,9 @@ module Appsignal
     end
     alias :set_params :add_params
 
-    # @api private
     # @since 4.0.0
     # @return [void]
+    # @!visibility private
     #
     # @see Helpers::Instrumentation#set_empty_params!
     def set_empty_params!
@@ -315,12 +324,14 @@ module Appsignal
 
     # Add parameters to the transaction if not already set.
     #
-    # @api private
     # @since 4.0.0
-    # @param given_params [Hash] The parameters to set on the transaction if none are already set.
+    # @param given_params [Hash<String, Object>, Array<Object>] 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.
+    # @yieldreturn [Hash<String, Object>, Array<Object>]
     # @return [void]
+    # @!visibility private
     #
     # @see #add_params
     def add_params_if_nil(given_params = nil, &block)
@@ -333,7 +344,7 @@ module Appsignal
     # When this method is called multiple times, it will merge the tags.
     #
     # @since 4.0.0
-    # @param given_tags [Hash] Collection of tags.
+    # @param given_tags [Hash<String, Object>] Collection of tags.
     # @option given_tags [String, Symbol, Integer] :any
     #   The name of the tag as a Symbol.
     # @option given_tags [String, Symbol, Integer] "any"
@@ -356,9 +367,10 @@ module Appsignal
     # the block is leading and the argument will _not_ be used.
     #
     # @since 4.0.0
-    # @param given_session_data [Hash] A hash containing session data.
+    # @param given_session_data [Hash<String, Object>] 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.
+    # @yieldreturn [Hash<String, Object>]
     # @return [void]
     #
     # @see Helpers::Instrumentation#add_session_data
@@ -375,12 +387,13 @@ module Appsignal
     # the `given_session_data` argument is leading and the block will _not_ be
     # called.
     #
-    # @api private
     # @since 4.0.0
-    # @param given_session_data [Hash] A hash containing session data.
+    # @param given_session_data [Hash<String, Object>] 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.
+    # @yieldreturn [Hash<String, Object>]
     # @return [void]
+    # @!visibility private
     #
     # @see #add_session_data
     # @see https://docs.appsignal.com/guides/custom-data/sample-data.html
@@ -393,9 +406,10 @@ module Appsignal
     # Add headers to the transaction.
     #
     # @since 4.0.0
-    # @param given_headers [Hash] A hash containing headers.
+    # @param given_headers [Hash<String, Object>] A hash containing headers.
     # @yield This block is called when the transaction is sampled. The block's
     #   return value will become the new headers.
+    # @yieldreturn [Hash<String, Object>]
     # @return [void]
     #
     # @see Helpers::Instrumentation#add_headers
@@ -411,12 +425,13 @@ module Appsignal
     # When both the `given_headers` and a block is given to this method,
     # the block is leading and the argument will _not_ be used.
     #
-    # @api private
     # @since 4.0.0
-    # @param given_headers [Hash] A hash containing headers.
+    # @param given_headers [Hash<String, Object>] A hash containing headers.
     # @yield This block is called when the transaction is sampled. The block's
     #   return value will become the new headers.
+    # @yieldreturn [Hash<String, Object>]
     # @return [void]
+    # @!visibility private
     #
     # @see #add_headers
     # @see https://docs.appsignal.com/guides/custom-data/sample-data.html
@@ -429,7 +444,8 @@ module Appsignal
     # Add custom data to the transaction.
     #
     # @since 4.0.0
-    # @param data [Hash/Array]
+    # @param data [Hash<Object, Object>, Array<Object>] Custom data to add to
+    #   the transaction.
     # @return [void]
     #
     # @see Helpers::Instrumentation#add_custom_data
@@ -446,9 +462,9 @@ 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 Appsignal.add_breadcrumb
@@ -498,10 +514,10 @@ module Appsignal
     #   Appsignal.set_action_if_nil("bar")
     #   # Transaction action will be "foo"
     #
-    # @api private
     # @since 2.2.0
     # @param action [String]
     # @return [void]
+    # @!visibility private
     #
     # @see #set_action
     def set_action_if_nil(action)
@@ -552,7 +568,7 @@ module Appsignal
       Appsignal.internal_logger.warn("Queue start value #{start} is too big")
     end
 
-    # @api private
+    # @!visibility private
     def set_metadata(key, value)
       return unless key && value
       return if Appsignal.config[:filter_metadata].include?(key.to_s)
@@ -560,7 +576,7 @@ module Appsignal
       @ext.set_metadata(key, value)
     end
 
-    # @api private
+    # @!visibility private
     # @see Appsignal::Helpers::Instrumentation#report_error
     def add_error(error, &block)
       unless error.is_a?(Exception)
@@ -588,7 +604,7 @@ module Appsignal
     alias :set_error :add_error
     alias_method :add_exception, :add_error
 
-    # @api private
+    # @!visibility private
     # @see Helpers::Instrumentation#instrument
     def start_event
       return if paused?
@@ -596,7 +612,7 @@ module Appsignal
       @ext.start_event(0)
     end
 
-    # @api private
+    # @!visibility private
     # @see Helpers::Instrumentation#instrument
     def finish_event(name, title, body, body_format = Appsignal::EventFormatter::DEFAULT)
       return if paused?
@@ -610,7 +626,7 @@ module Appsignal
       )
     end
 
-    # @api private
+    # @!visibility private
     # @see Helpers::Instrumentation#instrument
     def record_event(name, title, body, duration, body_format = Appsignal::EventFormatter::DEFAULT)
       return if paused?
@@ -625,7 +641,7 @@ module Appsignal
       )
     end
 
-    # @api private
+    # @!visibility private
     # @see Helpers::Instrumentation#instrument
     def instrument(name, title = nil, body = nil, body_format = Appsignal::EventFormatter::DEFAULT)
       start_event
@@ -634,7 +650,7 @@ module Appsignal
       finish_event(name, title, body, body_format)
     end
 
-    # @api private
+    # @!visibility private
     def to_h
       JSON.parse(@ext.to_json)
     end
@@ -642,9 +658,11 @@ module Appsignal
 
     protected
 
+    # @!visibility private
     attr_writer :is_duplicate, :tags, :custom_data, :breadcrumbs, :params,
       :session_data, :headers
 
+    # @!visibility private
     def internal_set_error(error, &block)
       _set_error(error) if @error_blocks.empty?
 
@@ -914,6 +932,8 @@ module Appsignal
     # Stub that is returned by {Transaction.current} if there is no current
     # transaction, so that it's still safe to call methods on it if there is no
     # current transaction.
+    #
+    # @!visibility private
     class NilTransaction
       def method_missing(_method, *args, &block)
       end

data/lib/appsignal/transmitter.rb

@@ -7,7 +7,7 @@ require "rack/utils"
 require "json"
 
 module Appsignal
-  # @api private
+  # @!visibility private
   class Transmitter
     JSON_CONTENT_TYPE = "application/json; charset=UTF-8"
     NDJSON_CONTENT_TYPE = "application/x-ndjson; charset=UTF-8"

data/lib/appsignal/utils.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Appsignal
-  # @api private
+  # @!visibility private
   module Utils
   end
 end

data/lib/appsignal/version.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
 module Appsignal
-  VERSION = "4.5.17"
+  # @return [String]
+  VERSION = "4.6.0"
 end

data/lib/appsignal.rb

@@ -39,7 +39,7 @@ module Appsignal
     # Can be `nil` if extension has not been loaded yet. See
     # {.extension_loaded?} for a boolean return value.
     #
-    # @api private
+    # @!visibility private
     # @return [Boolean, nil]
     # @see Extension
     # @see extension_loaded?
@@ -57,7 +57,7 @@ module Appsignal
     #   {.start}) the contents of the "in memory logger" is written to the new
     #   logger.
     #
-    #   @api private
+    #   @!visibility private
     #   @return [Utils::IntegrationLogger or Utils::IntegrationMemoryLogger]
     #   @see start
     attr_writer :internal_logger
@@ -71,11 +71,11 @@ module Appsignal
     # If the value is `nil`, no error was encountered or AppSignal wasn't
     # started yet.
     #
-    # @return [NilClass/Exception]
+    # @return [nil, Exception]
     attr_reader :config_error
     alias config_error? config_error
 
-    # @api private
+    # @!visibility private
     def testing?
       false
     end
@@ -163,9 +163,12 @@ module Appsignal
 
     # PRIVATE METHOD. DO NOT USE.
     #
-    # @param env_param [String, NilClass] Used by diagnose CLI to pass through
-    #   the environment CLI option value.
-    # @api private
+    # @param env_param [String, nil] Used by diagnose CLI to pass through
+    #   the environment CLI option value. If nil, the environment will be
+    #   auto-detected.
+    # @param block [Proc] Optional block to configure the config object.
+    # @return [void]
+    # @!visibility private
     def _load_config!(env_param = nil, &block) # rubocop:disable Metrics/PerceivedComplexity, Metrics/CyclomaticComplexity
       # Ensure it's not an empty string if it's a value
       proper_env_param = env_param&.to_s&.strip
@@ -305,7 +308,8 @@ module Appsignal
     # @param env_param [String, Symbol] The environment to load.
     # @param root_path [String] The path to look the `config/appsignal.yml` config file in.
     #   Defaults to the current working directory.
-    # @yield [Config] Gives the {Config} instance to the block.
+    # @yield [config_dsl] Gives the configuration DSL instance to the block.
+    # @yieldparam config_dsl [Appsignal::Config::ConfigDSL] The configuration DSL object
     # @return [void]
     # @see config
     # @see Config
@@ -397,12 +401,12 @@ module Appsignal
       nil
     end
 
-    # @api private
+    # @!visibility private
     def get_server_state(key)
       Appsignal::Extension.get_server_state(key)
     end
 
-    # @api private
+    # @!visibility private
     def in_memory_logger
       @in_memory_logger ||=
         Appsignal::Utils::IntegrationMemoryLogger.new.tap do |l|
@@ -410,12 +414,12 @@ module Appsignal
         end
     end
 
-    # @api private
+    # @!visibility private
     def internal_logger
       @internal_logger ||= in_memory_logger
     end
 
-    # @api private
+    # @!visibility private
     def log_formatter(prefix = nil)
       pre = "#{prefix}: " if prefix
       proc do |severity, datetime, _progname, msg|
@@ -429,7 +433,7 @@ module Appsignal
     # Sets the log level and sets the logger. Uses a file-based logger or the
     # STDOUT-based logger. See the `:log` configuration option.
     #
-    # @api private
+    # @!visibility private
     # @return [void]
     def _start_logger
       if config && config[:log] == "file" && config.log_file_path
@@ -499,7 +503,7 @@ module Appsignal
       config&.active? && extension_loaded?
     end
 
-    # @api private
+    # @!visibility private
     def dsl_config_file_loaded?
       defined?(@dsl_config_file_loaded) ? true : false
     end
@@ -613,6 +617,10 @@ module Appsignal
       Appsignal::Environment.report_supported_gems
     end
   end
+
+  # @!visibility private
+  module Integrations
+  end
 end
 
 require "appsignal/internal_errors"

data/lib/puma/plugin/appsignal.rb

@@ -76,7 +76,7 @@ end
 #
 # Class to handle the logic of translating the Puma stats to AppSignal metrics.
 #
-# @api private
+# @!visibility private
 class AppsignalPumaPlugin
   def initialize
     @hostname = fetch_hostname