appsignal 4.5.17 → 4.6.0

data/lib/appsignal/config.rb

@@ -8,12 +8,12 @@ require "tmpdir"
 
 module Appsignal
   class Config
-    # @api private
+    # @!visibility private
     def self.loader_defaults
       @loader_defaults ||= []
     end
 
-    # @api private
+    # @!visibility private
     def self.add_loader_defaults(name, env: nil, root_path: nil, **options)
       if Appsignal.config
         Appsignal.internal_logger.warn(
@@ -31,7 +31,7 @@ module Appsignal
     end
 
     # Determine which env AppSignal should initialize with.
-    # @api private
+    # @!visibility private
     def self.determine_env(initial_env = nil)
       [
         initial_env,
@@ -54,7 +54,7 @@ module Appsignal
     end
 
     # Determine which root path AppSignal should initialize with.
-    # @api private
+    # @!visibility private
     def self.determine_root_path
       app_path_env_var = ENV.fetch("APPSIGNAL_APP_PATH", nil)
       return app_path_env_var if app_path_env_var
@@ -67,7 +67,7 @@ module Appsignal
       Dir.pwd
     end
 
-    # @api private
+    # @!visibility private
     class Context
       DSL_FILENAME = "config/appsignal.rb"
 
@@ -87,7 +87,7 @@ module Appsignal
       end
     end
 
-    # @api private
+    # @!visibility private
     DEFAULT_CONFIG = {
       :activejob_report_errors => "all",
       :ca_file_path => File.expand_path(File.join("../../../resources/cacert.pem"), __FILE__),
@@ -133,12 +133,12 @@ module Appsignal
       :sidekiq_report_errors => "all"
     }.freeze
 
-    # @api private
+    # @!visibility private
     DEFAULT_LOG_LEVEL = ::Logger::INFO
     # Map from the `log_level` config option to Ruby's Logger level value.
     #
     # The trace level doesn't exist in the Ruby logger so it's mapped to debug.
-    # @api private
+    # @!visibility private
     LOG_LEVEL_MAP = {
       "error" => ::Logger::ERROR,
       "warn" => ::Logger::WARN,
@@ -148,7 +148,7 @@ module Appsignal
       "trace" => ::Logger::DEBUG
     }.freeze
 
-    # @api private
+    # @!visibility private
     STRING_OPTIONS = {
       :activejob_report_errors => "APPSIGNAL_ACTIVEJOB_REPORT_ERRORS",
       :name => "APPSIGNAL_APP_NAME",
@@ -171,7 +171,7 @@ module Appsignal
       :revision => "APP_REVISION"
     }.freeze
 
-    # @api private
+    # @!visibility private
     BOOLEAN_OPTIONS = {
       :active => "APPSIGNAL_ACTIVE",
       :enable_allocation_tracking => "APPSIGNAL_ENABLE_ALLOCATION_TRACKING",
@@ -198,7 +198,7 @@ module Appsignal
       :send_session_data => "APPSIGNAL_SEND_SESSION_DATA"
     }.freeze
 
-    # @api private
+    # @!visibility private
     ARRAY_OPTIONS = {
       :dns_servers => "APPSIGNAL_DNS_SERVERS",
       :filter_metadata => "APPSIGNAL_FILTER_METADATA",
@@ -211,12 +211,12 @@ module Appsignal
       :request_headers => "APPSIGNAL_REQUEST_HEADERS"
     }.freeze
 
-    # @api private
+    # @!visibility private
     FLOAT_OPTIONS = {
       :cpu_count => "APPSIGNAL_CPU_COUNT"
     }.freeze
 
-    # @api private
+    # @!visibility private
     attr_reader :root_path, :env, :config_hash
 
     # List of config option sources. If a config option was set by a source,
@@ -226,18 +226,20 @@ module Appsignal
     # Their values cannot be changed after the config is initialized.
     #
     # Used by the diagnose report to list which value was read from which source.
-    # @api private
+    # @!visibility private
     attr_reader :system_config, :loaders_config, :initial_config, :file_config,
       :env_config, :override_config, :dsl_config
 
-    # Initialize a new configuration object for AppSignal.
+    # Initialize a new AppSignal configuration object.
     #
-    # @param root_path [String] Root path of the app.
+    # @param root_path [String] Path to the root of the application.
     # @param env [String] The environment to load when AppSignal is started. It
     #   will look for an environment with this name in the `config/appsignal.yml`
     #   config file.
-    #
-    # @api private
+    # @param load_yaml_file [Boolean] Whether to load configuration from
+    #   the YAML config file. Defaults to true.
+    # @return [Config] The initialized configuration object.
+    # @!visibility private
     # @see https://docs.appsignal.com/ruby/configuration/
     #   Configuration documentation
     # @see https://docs.appsignal.com/ruby/configuration/load-order.html
@@ -268,7 +270,7 @@ module Appsignal
       load_config
     end
 
-    # @api private
+    # @!visibility private
     def load_config
       # Set defaults
       # Deep duplicate each frozen default value
@@ -327,8 +329,8 @@ module Appsignal
       @env_config[:env] = env_loaded_from_env if env_loaded_from_env
     end
 
-    # @api private
     # @return [String] System's tmp directory.
+    # @!visibility private
     def self.system_tmp_dir
       if Gem.win_platform?
         Dir.tmpdir
@@ -337,7 +339,11 @@ module Appsignal
       end
     end
 
-    # @api private
+    # Fetch a configuration value by key.
+    #
+    # @param key [Symbol, String] The configuration option key to fetch.
+    # @return [Object] The configuration value.
+    # @!visibility private
     def [](key)
       config_hash[key]
     end
@@ -347,12 +353,15 @@ module Appsignal
     # This method does not update the config in the extension and agent. It
     # should not be used to update the config after AppSignal has started.
     #
-    # @api private
+    # @param key [Symbol, String] The configuration option key to set.
+    # @param value [Object] The configuration value to set.
+    # @return [void]
+    # @!visibility private
     def []=(key, value)
       config_hash[key] = value
     end
 
-    # @api private
+    # @!visibility private
     def log_level
       option = config_hash[:log_level]
       level =
@@ -363,7 +372,7 @@ module Appsignal
       level.nil? ? Appsignal::Config::DEFAULT_LOG_LEVEL : level
     end
 
-    # @api private
+    # @!visibility private
     def log_file_path
       return @log_file_path if defined? @log_file_path
 
@@ -390,19 +399,28 @@ module Appsignal
       @log_file_path
     end
 
+    # Check if the configuration is valid.
+    #
+    # @return [Boolean] True if the configuration is valid, false otherwise.
     def valid?
       @valid
     end
 
+    # Check if AppSignal is active for the current environment.
+    #
+    # @return [Boolean] True if active for the current environment.
     def active_for_env?
       config_hash[:active]
     end
 
+    # Check if AppSignal is active.
+    #
+    # @return [Boolean] True if valid and active for the current environment.
     def active?
       valid? && active_for_env?
     end
 
-    # @api private
+    # @!visibility private
     def write_to_environment # rubocop:disable Metrics/AbcSize
       ENV["_APPSIGNAL_ACTIVE"]                       = active?.to_s
       ENV["_APPSIGNAL_AGENT_PATH"]                   = File.expand_path("../../ext", __dir__).to_s
@@ -444,21 +462,21 @@ module Appsignal
       ENV["_APP_REVISION"] = config_hash[:revision].to_s
     end
 
-    # @api private
+    # @!visibility private
     def merge_dsl_options(options)
       @dsl_config.merge!(options)
       merge(options)
     end
 
     # Apply any overrides for invalid settings.
-    # @api private
+    # @!visibility private
     def apply_overrides
       @override_config = determine_overrides
       merge(override_config)
     end
 
     # @return [void]
-    # @api private
+    # @!visibility private
     def validate
       # Strip path from endpoint so we're backwards compatible with
       # earlier versions of the gem.
@@ -483,8 +501,8 @@ module Appsignal
     # Deep freeze the config object so it cannot be modified during the runtime
     # of the Ruby app.
     #
-    # @api private
     # @return [void]
+    # @!visibility private
     # @since 4.0.0
     def freeze
       super
@@ -520,6 +538,41 @@ module Appsignal
         hash[:active] = true unless env_push_api_key.strip.empty?
 
         hash[:enable_at_exit_hook] = "always" if Appsignal::Extension.running_in_container?
+
+        # Set revision from REVISION file if present in project root
+        # This helps with Capistrano and Hatchbox.io deployments
+        revision_from_file = detect_revision_from_file
+        hash[:revision] = revision_from_file if revision_from_file
+      end
+    end
+
+    def detect_revision_from_file
+      return unless root_path
+
+      revision_file_path = File.join(root_path, "REVISION")
+      unless File.exist?(revision_file_path)
+        logger.debug "No REVISION file found at: #{revision_file_path}"
+        return
+      end
+
+      unless File.readable?(revision_file_path)
+        logger.debug "REVISION file is not readable at: #{revision_file_path}"
+        return
+      end
+
+      begin
+        revision_content = File.read(revision_file_path).strip
+        if revision_content.empty?
+          logger.debug "REVISION file found but is empty at: #{revision_file_path}"
+          nil
+        else
+          logger.debug "REVISION file found and read successfully at: #{revision_file_path}"
+          revision_content
+        end
+      rescue SystemCallError => e
+        logger.debug "Error occurred while reading REVISION file at " \
+          "#{revision_file_path}: #{e.class}: #{e.message}\n#{e.backtrace}"
+        nil
       end
     end
 
@@ -613,19 +666,43 @@ module Appsignal
       end
     end
 
-    # @api private
+    # Configuration DSL for use in configuration blocks.
+    #
+    # This class provides a Domain Specific Language for configuring AppSignal
+    # within the `Appsignal.configure` block. It provides getter and setter
+    # methods for all configuration options.
+    #
+    # @example Using the configuration DSL
+    #   Appsignal.configure do |config|
+    #     config.name = "My App"
+    #     config.active = true
+    #     config.push_api_key = "your-api-key"
+    #     config.ignore_actions = ["StatusController#health"]
+    #   end
+    #
+    # @see AppSignal Ruby gem configuration
+    #   https://docs.appsignal.com/ruby/configuration.html
     class ConfigDSL
+      # @!visibility private
+      # @return [Hash] Hash containing the DSL option values
       attr_reader :dsl_options
 
+      # @!visibility private
       def initialize(config)
         @config = config
         @dsl_options = {}
       end
 
+      # Returns the application's root path.
+      #
+      # @return [String] The root path of the application
       def app_path
         @config.root_path
       end
 
+      # Returns the current environment name.
+      #
+      # @return [String] The environment name (e.g., "production", "development")
       def env
         @config.env
       end
@@ -639,10 +716,58 @@ module Appsignal
         env == given_env.to_s
       end
 
+      # Activates AppSignal if the current environment matches any of the given environments.
+      #
+      # @param envs [Array<String, Symbol>] List of environment names to activate for
+      # @return [Boolean] true if AppSignal was activated, false otherwise
+      #
+      # @example Activate for production and staging
+      #   config.activate_if_environment(:production, :staging)
       def activate_if_environment(*envs)
         self.active = envs.map(&:to_s).include?(env)
       end
 
+      # @!group String Configuration Options
+
+      # @!attribute [rw] activejob_report_errors
+      #   @return [String] Error reporting mode for ActiveJob ("all", "discard" or "none")
+      # @!attribute [rw] name
+      #   @return [String] The application name
+      # @!attribute [rw] bind_address
+      #   @return [String] The host to the agent binds to for its HTTP server
+      # @!attribute [rw] ca_file_path
+      #   @return [String] Path to the CA certificate file
+      # @!attribute [rw] hostname
+      #   @return [String] Override for the detected hostname
+      # @!attribute [rw] host_role
+      #   @return [String] Role of the host for grouping in metrics
+      # @!attribute [rw] http_proxy
+      #   @return [String] HTTP proxy URL
+      # @!attribute [rw] log
+      #   @return [String] Log destination ("file" or "stdout")
+      # @!attribute [rw] log_level
+      #   @return [String] AppSignal internal logger
+      #     log level ("error", "warn", "info", "debug", "trace")
+      # @!attribute [rw] log_path
+      #   @return [String] Path to the log directory
+      # @!attribute [rw] logging_endpoint
+      #   @return [String] Endpoint for log transmission
+      # @!attribute [rw] endpoint
+      #   @return [String] Push API endpoint URL
+      # @!attribute [rw] push_api_key
+      #   @return [String] AppSignal Push API key
+      # @!attribute [rw] sidekiq_report_errors
+      #   @return [String] Error reporting mode for Sidekiq ("all", "discard" or "none")
+      # @!attribute [rw] statsd_port
+      #   @return [String] Port for StatsD metrics
+      # @!attribute [rw] nginx_port
+      #   @return [String] Port for Nginx metrics collection
+      # @!attribute [rw] working_directory_path
+      #   @return [String] Override for the agent working directory
+      # @!attribute [rw] revision
+      #   @return [String] Application revision identifier
+
+      # @!endgroup
       Appsignal::Config::STRING_OPTIONS.each_key do |option|
         define_method(option) do
           fetch_option(option)
@@ -653,6 +778,54 @@ module Appsignal
         end
       end
 
+      # @!group Boolean Configuration Options
+
+      # @!attribute [rw] active
+      #   @return [Boolean] Activate AppSignal for the loaded environment
+      # @!attribute [rw] enable_allocation_tracking
+      #   @return [Boolean] Configure whether allocation tracking is enabled
+      # @!attribute [rw] enable_at_exit_reporter
+      #   @return [Boolean] Configure whether the at_exit reporter is enabled
+      # @!attribute [rw] enable_host_metrics
+      #   @return [Boolean] Configure whether host metrics collection is enabled
+      # @!attribute [rw] enable_minutely_probes
+      #   @return [Boolean] Configure whether minutely probes are enabled
+      # @!attribute [rw] enable_statsd
+      #   @return [Boolean] Configure whether the StatsD metrics endpoint on the agent is enabled
+      # @!attribute [rw] enable_nginx_metrics
+      #   @return [Boolean] Configure whether the agent's NGINX metrics endpoint is enabled
+      # @!attribute [rw] enable_gvl_global_timer
+      #   @return [Boolean] Configure whether the GVL global timer instrumentationis enabled
+      # @!attribute [rw] enable_gvl_waiting_threads
+      #   @return [Boolean] Configure whether GVL waiting threads instrumentation is enabled
+      # @!attribute [rw] enable_rails_error_reporter
+      #   @return [Boolean] Configure whether Rails error reporter integration is enabled
+      # @!attribute [rw] enable_rake_performance_instrumentation
+      #   @return [Boolean] Configure whether Rake performance instrumentation is enabled
+      # @!attribute [rw] files_world_accessible
+      #   @return [Boolean] Configure whether files created by AppSignal should be world accessible
+      # @!attribute [rw] instrument_http_rb
+      #   @return [Boolean] Configure whether to instrument requests made with the http.rb gem
+      # @!attribute [rw] instrument_net_http
+      #   @return [Boolean] Configure whether to instrument requests made with Net::HTTP
+      # @!attribute [rw] instrument_ownership
+      #   @return [Boolean] Configure whether to instrument the Ownership gem
+      # @!attribute [rw] instrument_redis
+      #   @return [Boolean] Configure whether to instrument Redis queries
+      # @!attribute [rw] instrument_sequel
+      #   @return [Boolean] Configure whether to instrument Sequel queries
+      # @!attribute [rw] ownership_set_namespace
+      #   @return [Boolean] Configure whether the Ownership gem instrumentation should set namespace
+      # @!attribute [rw] running_in_container
+      #   @return [Boolean] Configure whether the application is running in a container
+      # @!attribute [rw] send_environment_metadata
+      #   @return [Boolean] Configure whether to send environment metadata
+      # @!attribute [rw] send_params
+      #   @return [Boolean] Configure whether to send request parameters
+      # @!attribute [rw] send_session_data
+      #   @return [Boolean] Configure whether to send request session data
+
+      # @!endgroup
       Appsignal::Config::BOOLEAN_OPTIONS.each_key do |option|
         define_method(option) do
           fetch_option(option)
@@ -663,6 +836,28 @@ module Appsignal
         end
       end
 
+      # @!group Array Configuration Options
+
+      # @!attribute [rw] dns_servers
+      #   @return [Array<String>] Custom DNS servers to use
+      # @!attribute [rw] filter_metadata
+      #   @return [Array<String>] Metadata keys to filter from trace data
+      # @!attribute [rw] filter_parameters
+      #   @return [Array<String>] Keys of parameter to filter
+      # @!attribute [rw] filter_session_data
+      #   @return [Array<String>] Request session data keys to filter
+      # @!attribute [rw] ignore_actions
+      #   @return [Array<String>] Ignore traces by action names
+      # @!attribute [rw] ignore_errors
+      #   @return [Array<String>] List of errors to not report
+      # @!attribute [rw] ignore_logs
+      #   @return [Array<String>] Ignore log messages by substrings
+      # @!attribute [rw] ignore_namespaces
+      #   @return [Array<String>] Ignore traces by namespaces
+      # @!attribute [rw] request_headers
+      #   @return [Array<String>] HTTP request headers to include in error reports
+
+      # @!endgroup
       Appsignal::Config::ARRAY_OPTIONS.each_key do |option|
         define_method(option) do
           fetch_option(option)
@@ -673,6 +868,12 @@ module Appsignal
         end
       end
 
+      # @!group Float Configuration Options
+
+      # @!attribute [rw] cpu_count
+      #   @return [Float] CPU count override for metrics collection
+
+      # @!endgroup
       Appsignal::Config::FLOAT_OPTIONS.each_key do |option|
         define_method(option) do
           fetch_option(option)

data/lib/appsignal/custom_marker.rb

@@ -15,7 +15,7 @@ module Appsignal
     # @param icon [String] icon to use for the marker, like an emoji.
     # @param message [String] name of the user that is creating the
     #   marker.
-    # @param created_at [Time/String] A Ruby time object or a valid ISO8601
+    # @param created_at [Time, String] A Ruby time object or a valid ISO8601
     #   timestamp.
     # @return [Boolean]
     def self.report(
@@ -32,12 +32,12 @@ module Appsignal
       ).transmit
     end
 
-    # @api private
+    # @!visibility private
     def initialize(marker_data)
       @marker_data = marker_data
     end
 
-    # @api private
+    # @!visibility private
     def transmit
       unless Appsignal.config
         Appsignal.internal_logger.warn(

data/lib/appsignal/environment.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Appsignal
-  # @api private
+  # @!visibility private
   class Environment
     ERROR_ON_YIELD = :APPSIGNAL_ERROR_ON_YIELD
 
@@ -119,6 +119,8 @@ module Appsignal
     #
     # It will ask Bundler to report name and version information from the gems
     # that are present in the app bundle.
+    #
+    # @return [void]
     def self.report_supported_gems
       return unless defined?(Bundler) # Do nothing if Bundler is not present
 
@@ -139,6 +141,10 @@ module Appsignal
         "#{e.class}: #{e}"
     end
 
+    # Report a Ruby feature is enabled
+    #
+    # @param feature [String] Name of the feature to report as enabled.
+    # @return [void]
     def self.report_enabled(feature)
       Appsignal::Environment.report("ruby_#{feature}_enabled") { true }
     rescue => e

data/lib/appsignal/event_formatter/action_view/render_formatter.rb

@@ -2,7 +2,7 @@
 
 module Appsignal
   class EventFormatter
-    # @api private
+    # @!visibility private
     module ActionView
       class RenderFormatter
         BLANK = ""

data/lib/appsignal/event_formatter/active_record/instantiation_formatter.rb

@@ -2,7 +2,7 @@
 
 module Appsignal
   class EventFormatter
-    # @api private
+    # @!visibility private
     module ActiveRecord
       class InstantiationFormatter
         def format(payload)

data/lib/appsignal/event_formatter/active_record/sql_formatter.rb

@@ -2,7 +2,7 @@
 
 module Appsignal
   class EventFormatter
-    # @api private
+    # @!visibility private
     module ActiveRecord
       class SqlFormatter
         def format(payload)

data/lib/appsignal/event_formatter/elastic_search/search_formatter.rb

@@ -2,7 +2,7 @@
 
 module Appsignal
   class EventFormatter
-    # @api private
+    # @!visibility private
     module ElasticSearch
       class SearchFormatter
         def format(payload)

data/lib/appsignal/event_formatter/faraday/request_formatter.rb

@@ -2,7 +2,7 @@
 
 module Appsignal
   class EventFormatter
-    # @api private
+    # @!visibility private
     module Faraday
       class RequestFormatter
         def format(payload)

data/lib/appsignal/event_formatter/mongo_ruby_driver/query_formatter.rb

@@ -2,7 +2,7 @@
 
 module Appsignal
   class EventFormatter
-    # @api private
+    # @!visibility private
     module MongoRubyDriver
       class QueryFormatter
         ALLOWED = {

data/lib/appsignal/event_formatter/rom/sql_formatter.rb

@@ -2,7 +2,7 @@
 
 module Appsignal
   class EventFormatter
-    # @api private
+    # @!visibility private
     module Rom
       class SqlFormatter
         def format(payload)

data/lib/appsignal/event_formatter/sequel/sql_formatter.rb

@@ -2,7 +2,7 @@
 
 module Appsignal
   class EventFormatter
-    # @api private
+    # @!visibility private
     module Sequel
       # Compatibility with the sequel-rails gem.
       # The sequel-rails gem adds its own ActiveSupport::Notifications events

data/lib/appsignal/event_formatter/view_component/render_formatter.rb

@@ -2,7 +2,7 @@
 
 module Appsignal
   class EventFormatter
-    # @api private
+    # @!visibility private
     module ViewComponent
       class RenderFormatter
         BLANK = ""