appsignal 4.5.6 → 4.5.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9c26526a57b19a4680e8d3b7293eb1f46c9e32b8bf4fc47e9ea9aa74c96a3b64
-  data.tar.gz: 91ef88fce1c7fdf231ce23bbe6047338b34100f4610bbadea6f8b6fcbb79cacf
+  metadata.gz: f023b8343540c92b7c106f7c9853d7ec08c64f0138fa1904be7b606aadf6691b
+  data.tar.gz: eb18c6e7c352ab0e5e44f739190df8a2c671212b97133311070633944597b63f
 SHA512:
-  metadata.gz: 18fbaec4092861cebc794fbeabdcb4ea189a5c38faabf99fe25cdd1b07d1d0d778de73c5d7f55977b8abfa69d2d77b924dcb4a6ec4a0c97beeab88770ea06115
-  data.tar.gz: 43d538d0d1cd4571704abed7116f40819569d78cfe54b00bf0b888f3e5ca6b4f46d40e4100c1a7953cb63e66c904fa6ab2f3f3297eeef4ee1b34face4af63c39
+  metadata.gz: 678d39b904447512f7222a7c3f82bd251d507e745d9b1402f7c3a3784fabd691f1a1538421ff4dd7fb158cdc74d02e925cbea10eff59581c2d661d3d1ad9c03a
+  data.tar.gz: 18efa45cf4d42fd8faacaf5cec5ec93e76d41773d83e9e077a6d4528aeb5019a05ce41b35b1e88e3449ccd8635ce27045c8cca49d46077327d6490e3e6dc31d4

data/CHANGELOG.md

@@ -1,5 +1,50 @@
 # AppSignal for Ruby gem Changelog
 
+## 4.5.8
+
+_Published on 2025-04-04._
+
+### Added
+
+- Add the `enable_at_exit_hook` option to configure if `Appsignal.stop` is called when the Ruby application exits. Calling `Appsignal.stop` will stop the application for a moment to flush all the data to our agent before shutting down.
+
+  This option has three possible values:
+
+  - `always`: Always call `Appsignal.stop` when the program exits. On (Docker) containers it's automatically set to this value.
+  - `never`: Never call `Appsignal.stop` when the program exits. The default value when the program doesn't run on a (Docker) container.
+  - `on_error`: Call `Appsignal.stop` when the program exits with an error.
+
+  (patch [d0a5875c](https://github.com/appsignal/appsignal-ruby/commit/d0a5875cef5101680f1cab4649d71440212f9ea8), [043a6c74](https://github.com/appsignal/appsignal-ruby/commit/043a6c740b708e1182ed7161e3c9ad38bd3314de), [b680fe6f](https://github.com/appsignal/appsignal-ruby/commit/b680fe6f6b283205a13ca61bd4a26167f541dbca))
+
+### Deprecated
+
+- Deprecate the `Appsignal.monitor_and_stop` helper.
+
+  We instead recommend using the `Appsignal.monitor` helper and configuring the `enable_at_exit_hook` config option to `always`.
+
+  (patch [84969aea](https://github.com/appsignal/appsignal-ruby/commit/84969aeaca8f3737921e9adf1efdad55b52e1206))
+
+## 4.5.7
+
+_Published on 2025-03-20._
+
+### Added
+
+- Add the `Appsignal.config_error` and `Appsignal.config_error?` methods. This method contains any error that may have occurred while loading the `config/appsignal.rb` file. If it is `nil` no error occurred or `Appsignal.start` hasn't been called yet. The `Appsignal.config_error?` method is an alias for syntax sugar. (patch [0f3a7372](https://github.com/appsignal/appsignal-ruby/commit/0f3a73729306d96b630339ccf6e218318d1e2870))
+- Add the `check_if_started!` method. This method will raise an error if the AppSignal Ruby gem failed to start.
+
+  Call this method in your CI or on app boot if you wish to verify that AppSignal has started when your application does, and want the application to fail to start if AppSignal hasn't started.
+
+  For example, in this Rails initializer:
+
+  ```
+  # config/initializers/appsignal.rb
+
+  Appsignal.check_if_started!
+  ```
+
+  (patch [b41c9c99](https://github.com/appsignal/appsignal-ruby/commit/b41c9c991bdbcd64b7a04e9832b15ddacda7ae20))
+
 ## 4.5.6
 
 _Published on 2025-03-20._

data/lib/appsignal/config.rb

@@ -93,6 +93,7 @@ module Appsignal
       :ca_file_path => File.expand_path(File.join("../../../resources/cacert.pem"), __FILE__),
       :dns_servers => [],
       :enable_allocation_tracking => true,
+      :enable_at_exit_hook => "on_error",
       :enable_at_exit_reporter => true,
       :enable_host_metrics => true,
       :enable_minutely_probes => true,
@@ -153,6 +154,7 @@ module Appsignal
       :name => "APPSIGNAL_APP_NAME",
       :bind_address => "APPSIGNAL_BIND_ADDRESS",
       :ca_file_path => "APPSIGNAL_CA_FILE_PATH",
+      :enable_at_exit_hook => "APPSIGNAL_ENABLE_AT_EXIT_HOOK",
       :hostname => "APPSIGNAL_HOSTNAME",
       :host_role => "APPSIGNAL_HOST_ROLE",
       :http_proxy => "APPSIGNAL_HTTP_PROXY",
@@ -507,6 +509,8 @@ module Appsignal
         # environment variable is present and not empty.
         env_push_api_key = ENV["APPSIGNAL_PUSH_API_KEY"] || ""
         hash[:active] = true unless env_push_api_key.strip.empty?
+
+        hash[:enable_at_exit_hook] = "always" if Appsignal::Extension.running_in_container?
       end
     end
 

data/lib/appsignal/helpers/instrumentation.rb

@@ -154,6 +154,11 @@ module Appsignal
       #
       # @see monitor
       def monitor_and_stop(action:, namespace: nil, &block)
+        Appsignal::Utils::StdoutAndLoggerMessage.warning \
+          "The `Appsignal.monitor_and_stop` helper is deprecated. " \
+            "Use the `Appsignal.monitor` along with our `enable_at_exit_hook` " \
+            "option instead."
+
         monitor(:namespace => namespace, :action => action, &block)
       ensure
         Appsignal.stop("monitor_and_stop")

data/lib/appsignal/hooks/at_exit.rb

@@ -11,27 +11,41 @@ module Appsignal
       end
 
       def install
-        return unless Appsignal.config[:enable_at_exit_reporter]
-
         Kernel.at_exit(&AtExitCallback.method(:call))
       end
 
-      # Report any unhandled errors and will crash the Ruby process.
+      # Stop AppSignal before the app exists.
+      #
+      # This is the default behavior and can be customized with the
+      # `enable_at_exit_hook` option.
+      #
+      # When the `enable_at_exit_reporter` option is set to `true` (the
+      # default), it will report any unhandled errors that will crash the Ruby
+      # process.
       #
       # If this error was previously reported by any of our instrumentation,
       # the error will not also be reported here. This way we don't report an
       # error from a Rake task or instrumented script twice.
       class AtExitCallback
         def self.call
+          report_error = false
+          return unless Appsignal.config&.[](:enable_at_exit_reporter)
+
           error = $! # rubocop:disable Style/SpecialGlobalVars
           return unless error
           return if ignored_error?(error)
           return if Appsignal::Transaction.last_errors.include?(error)
 
+          report_error = true
+
           Appsignal.report_error(error) do |transaction|
             transaction.set_namespace("unhandled")
           end
-          Appsignal.stop("at_exit")
+        ensure
+          at_exit_hook = Appsignal.config&.[](:enable_at_exit_hook)
+          if at_exit_hook == "always" || (at_exit_hook == "on_error" && report_error)
+            Appsignal.stop("at_exit")
+          end
         end
 
         IGNORED_ERRORS = [

data/lib/appsignal/internal_errors.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Appsignal
+  # @api private
+  class InternalError < StandardError; end
+
+  # @api private
+  class NotStartedError < InternalError
+    MESSAGE = <<~MESSAGE
+      The AppSignal Ruby gem was not started!
+
+      This error was raised by calling `Appsignal.check_if_started!`
+    MESSAGE
+
+    def message
+      MESSAGE
+    end
+  end
+end

data/lib/appsignal/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Appsignal
-  VERSION = "4.5.6"
+  VERSION = "4.5.8"
 end

data/lib/appsignal.rb

@@ -62,6 +62,19 @@ module Appsignal
     #   @see start
     attr_writer :internal_logger
 
+    # Returns the error that was encountered while loading the `appsignal.rb`
+    # config file.
+    #
+    # It does not include any error that occurred while loading the
+    # `appsignal.yml` file.
+    #
+    # If the value is `nil`, no error was encountered or AppSignal wasn't
+    # started yet.
+    #
+    # @return [NilClass/Exception]
+    attr_reader :config_error
+    alias config_error? config_error
+
     # @api private
     def testing?
       false
@@ -483,6 +496,31 @@ module Appsignal
       defined?(@dsl_config_file_loaded) ? true : false
     end
 
+    # Check if the AppSignal Ruby gem has started successfully.
+    #
+    # If it has not (yet) started or encountered an error in the
+    # `config/appsignal.rb` config file during start up that prevented it from
+    # starting, it will raise a {Appsignal::NotStartedError}.
+    #
+    # If there an error raised from the config file, it will include it as the
+    # error cause of the raised error.
+    #
+    # @raise [Appsignal::NotStartedError]
+    # @return [void]
+    def check_if_started!
+      return if started?
+
+      begin
+        raise config_error if config_error?
+      rescue
+        # Raise the NotStartedError and make the config error the error cause
+        raise NotStartedError, config_error
+      end
+
+      # Raise the NotStartedError as normal
+      raise NotStartedError
+    end
+
     private
 
     def params_match_loaded_config?(env_param, root_path_param)
@@ -508,7 +546,7 @@ module Appsignal
         @dsl_config_file_loaded = true
         require path
       rescue => error
-        @config_file_error = error
+        @config_error = error
         message = "Not starting AppSignal because an error occurred while " \
           "loading the AppSignal config file.\n" \
           "File: #{path.inspect}\n" \
@@ -527,7 +565,7 @@ module Appsignal
         end
 
         # Disable on config file error
-        config[:active] = false if defined?(@config_file_error)
+        config[:active] = false if defined?(@config_error)
 
         ENV.delete("_APPSIGNAL_CONFIG_FILE_CONTEXT")
         ENV.delete("_APPSIGNAL_CONFIG_FILE_ENV")
@@ -569,6 +607,7 @@ module Appsignal
   end
 end
 
+require "appsignal/internal_errors"
 require "appsignal/loaders"
 require "appsignal/sample_data"
 require "appsignal/environment"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: appsignal
 version: !ruby/object:Gem::Version
-  version: 4.5.6
+  version: 4.5.8
 platform: ruby
 authors:
 - Robert Beekman
@@ -10,7 +10,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-03-20 00:00:00.000000000 Z
+date: 2025-04-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: logger
@@ -248,6 +248,7 @@ files:
 - lib/appsignal/integrations/sidekiq.rb
 - lib/appsignal/integrations/unicorn.rb
 - lib/appsignal/integrations/webmachine.rb
+- lib/appsignal/internal_errors.rb
 - lib/appsignal/loaders.rb
 - lib/appsignal/loaders/grape.rb
 - lib/appsignal/loaders/hanami.rb