appsignal 3.12.5 → 3.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dd62bf754a88f4f79b2ca6fb08a783bb86e97fe0c412bf7f3ea70262bf4c5d9f
-  data.tar.gz: 647bac8317c4f1c4ce67bf53b8ae06f28ffd89f89b4d64d930037b0733e11f76
+  metadata.gz: 3908c76b33dae84dfbaaa42896c709c8ceaf8443dd3855c4811e660fd9da5df0
+  data.tar.gz: a5be1a3498ff49fe1e6de1d09abe81bb4d2ce2a5cc44a69e6fa45ebe9b9d8496
 SHA512:
-  metadata.gz: b10727bb338031cb33310bec347d42f186f2e44c8e91464b6e400b2ca4e9693f975d8be2e209e332083cf17f0a28d77e279e6f7d7afd082c6bf878404e151f4b
-  data.tar.gz: 9cc47facf2c3e4448a8c18f73980d2e286b72e568c2bebdf1cf11356fc757a22781def5f4507ded0ba63d31045a935b84c811688368c2b0bc882627cac82fd9c
+  metadata.gz: 98b58eda188a7abce65a74ee3a8dbf3b7c59f6f7c9af28c7cc18181942d7ac9a886f5648f4425af78417d475739172b0ef925851f06307ba2e586d52d9763077
+  data.tar.gz: 8311cc2b6c88447565c87cc231c50e3aa0640905cef72f400cb1620057ae22ef779da497dac76287ec9404957684fe838fd6c6471d9fcc5081b5cde94e747f05

data/CHANGELOG.md

@@ -1,5 +1,78 @@
 # AppSignal for Ruby gem Changelog
 
+## 3.13.0
+
+_Published on 2024-08-14._
+
+### Changed
+
+- Remove the HTTP gem's exception handling. Errors from the HTTP gem will no longer always be reported. The error will be reported only when an HTTP request is made in an instrumented context. This gives applications the opportunity to add their own custom exception handling.
+
+  ```ruby
+  begin
+    HTTP.get("https://appsignal.com/error")
+  rescue => error
+    # Either handle the error or report it to AppSignal
+  end
+  ```
+
+  (minor [2a452ff0](https://github.com/appsignal/appsignal-ruby/commit/2a452ff07e0b0938b1623fa8846af6ef37917ec2))
+- Rename heartbeats to cron check-ins. Calls to `Appsignal.heartbeat` and `Appsignal::Heartbeat` should be replaced with calls to `Appsignal::CheckIn.cron` and `Appsignal::CheckIn::Cron`, for example:
+
+  ```ruby
+  # Before
+  Appsignal.heartbeat("do_something") do
+    do_something
+  end
+
+  # After
+  Appsignal::CheckIn.cron("do_something") do
+    do_something
+  end
+  ```
+
+  (patch [2f686cd0](https://github.com/appsignal/appsignal-ruby/commit/2f686cd00d5daa6e0854a8cacfe0e874a3a7c146))
+
+### Deprecated
+
+- Calls to `Appsignal.heartbeat` and `Appsignal::Heartbeat` will emit a deprecation warning. (patch [2f686cd0](https://github.com/appsignal/appsignal-ruby/commit/2f686cd00d5daa6e0854a8cacfe0e874a3a7c146))
+
+## 3.12.6
+
+_Published on 2024-08-05._
+
+### Changed
+
+- Configure AppSignal with the install CLI when no known frameworks is found. Automate the configure step so that this doesn't have to be done manually along with the manual setup for the app. (patch [a9c546fa](https://github.com/appsignal/appsignal-ruby/commit/a9c546fa86afbec290cd8439a559bf60cad21fc8))
+
+### Deprecated
+
+- Deprecate the `Appsignal.listen_for_error` helper. Use a manual error rescue with `Appsignal.report_error`. This method allows for more customization of the reported error.
+
+  ```ruby
+  # Before
+  Appsignal.listen_for_error do
+    raise "some error"
+  end
+
+  # After
+  begin
+    raise "some error"
+  rescue => error
+    Appsignal.report_error(error)
+  end
+  ```
+
+  Read our [Exception handling guide](https://docs.appsignal.com/ruby/instrumentation/exception-handling.html) for more information.
+
+  (patch [14bd8882](https://github.com/appsignal/appsignal-ruby/commit/14bd88824dea2993cb0165bbbed0def29d69f72a))
+- Deprecate the `Appsignal.configure`'s `app_path` writer. Use the `Appsignal.configure`'s `root_path` keyword argument to configure the path. (patch [c79f46c3](https://github.com/appsignal/appsignal-ruby/commit/c79f46c3cd96ac51726a963f38999bfb3c246d52))
+
+### Fixed
+
+- Fix an error on the Padrino require in the installer CLI. The latest Padrino version will crash the installer on load. Ignore the error when it fails to load. (patch [dfe23707](https://github.com/appsignal/appsignal-ruby/commit/dfe23707f769ff818714ee7cf14340f9472ce2e4))
+- Fix the `Appsignal.configure` path config not being customizable. It's now possible to pass a `root_path` keyword argument to `Appsignal.configure` to customize the path from which AppSignal reads the config file, `config/appsignal.yml`. (patch [c79f46c3](https://github.com/appsignal/appsignal-ruby/commit/c79f46c3cd96ac51726a963f38999bfb3c246d52))
+
 ## 3.12.5
 
 _Published on 2024-08-01._

data/lib/appsignal/check_in/cron.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Appsignal
+  module CheckIn
+    class Cron
+      class << self
+        # @api private
+        def transmitter
+          @transmitter ||= Appsignal::Transmitter.new(
+            "#{Appsignal.config[:logging_endpoint]}/check_ins/json"
+          )
+        end
+
+        def emit_initializer_deprecation_warning
+          return if @initializer_deprecation_warning_emitted
+
+          callers = caller
+          Appsignal::Utils::StdoutAndLoggerMessage.warning(
+            "Passing a `name` keyword argument to `Appsignal::CheckIn::Cron.new` is deprecated. " \
+              "Please use the `identifier` keyword argument instead, " \
+              "in the following file and elsewhere, to remove this message.\n#{callers[2]}"
+          )
+          @initializer_deprecation_warning_emitted = true
+        end
+      end
+
+      # @api private
+      attr_reader :identifier, :digest
+
+      def initialize(identifier: nil, name: nil)
+        @identifier = identifier || name || raise(ArgumentError, "missing keyword: :identifier")
+        Cron.emit_initializer_deprecation_warning unless name.nil?
+        @digest = SecureRandom.hex(8)
+      end
+
+      def start
+        transmit_event("start")
+      end
+
+      def finish
+        transmit_event("finish")
+      end
+
+      private
+
+      def event(kind)
+        {
+          :identifier => @identifier,
+          :digest => @digest,
+          :kind => kind,
+          :timestamp => Time.now.utc.to_i,
+          :check_in_type => "cron"
+        }
+      end
+
+      def transmit_event(kind)
+        unless Appsignal.active?
+          Appsignal.internal_logger.debug(
+            "AppSignal not active, not transmitting cron check-in event"
+          )
+          return
+        end
+
+        response = self.class.transmitter.transmit(event(kind))
+
+        if response.code.to_i >= 200 && response.code.to_i < 300
+          Appsignal.internal_logger.debug(
+            "Transmitted cron check-in `#{identifier}` (#{digest}) #{kind} event"
+          )
+        else
+          Appsignal.internal_logger.error(
+            "Failed to transmit cron check-in #{kind} event: status code was #{response.code}"
+          )
+        end
+      rescue => e
+        Appsignal.internal_logger.error("Failed to transmit cron check-in #{kind} event: #{e}")
+      end
+    end
+  end
+end

data/lib/appsignal/check_in.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Appsignal
+  module CheckIn
+    class << self
+      # Track cron check-ins.
+      #
+      # Track the execution of certain processes by sending a cron check-in.
+      #
+      # To track the duration of a piece of code, pass a block to {.cron}
+      # to report both when the process starts, and when it finishes.
+      #
+      # If an exception is raised within the block, the finish event will not
+      # be reported, triggering a notification about the missing cron check-in.
+      # The exception will bubble outside of the cron check-in block.
+      #
+      # @example Send a cron check-in
+      #   Appsignal::CheckIn.cron("send_invoices")
+      #
+      # @example Send a cron check-in with duration
+      #   Appsignal::CheckIn.cron("send_invoices") do
+      #     # your code
+      #   end
+      #
+      # @param name [String] name of the cron check-in to report.
+      # @yield the block to monitor.
+      # @return [void]
+      # @since 3.13.0
+      # @see https://docs.appsignal.com/check-ins/cron
+      def cron(identifier)
+        cron = Appsignal::CheckIn::Cron.new(:identifier => identifier)
+        output = nil
+
+        if block_given?
+          cron.start
+          output = yield
+        end
+
+        cron.finish
+        output
+      end
+    end
+  end
+end
+
+require "appsignal/check_in/cron"

data/lib/appsignal/cli/install.rb

@@ -18,16 +18,16 @@ module Appsignal
           $stdout.sync = true
 
           puts
-          puts colorize "#######################################", :green
-          puts colorize "## Starting AppSignal Installer      ##", :green
-          puts colorize "## --------------------------------- ##", :green
-          puts colorize "## Need help?  support@appsignal.com ##", :green
-          puts colorize "## Docs?       docs.appsignal.com    ##", :green
-          puts colorize "#######################################", :green
+          puts colorize "############################################", :green
+          puts colorize "## Starting AppSignal Installer           ##", :green
+          puts colorize "## -------------------------------------- ##", :green
+          puts colorize "## Need help?  support@appsignal.com      ##", :green
+          puts colorize "## Docs:       https://docs.appsignal.com ##", :green
+          puts colorize "############################################", :green
           puts
           unless push_api_key
             puts colorize "Problem encountered:", :red
-            puts "  No push API key entered."
+            puts "  No Push API key entered."
             puts "  - Sign up for AppSignal and follow the instructions"
             puts "  - Already signed up? Click 'Add app' on the account overview page"
             puts
@@ -37,22 +37,25 @@ module Appsignal
           config = new_config
           config[:push_api_key] = push_api_key
 
-          print "Validating API key"
+          print "Validating Push API key"
           periods
           puts
           begin
             auth_check = Appsignal::AuthCheck.new(config)
             unless auth_check.perform == "200"
-              puts "\n  API key '#{config[:push_api_key]}' is not valid, please get a new one on https://appsignal.com"
+              print colorize("  Error:", :red)
+              puts " Push API key '#{config[:push_api_key]}' is not valid. " \
+                "Please get a new one at https://appsignal.com/accounts"
               return
             end
           rescue => e
-            puts "  There was an error validating your API key:"
+            print colorize("  Error:", :red)
+            puts "There was an error validating your Push API key:"
             puts colorize "'#{e}'", :red
-            puts "  Please try again"
+            puts "  Please check the Push API key and try again"
             return
           end
-          puts colorize "  API key valid!", :green
+          puts colorize "  Push API key valid!", :green
           puts
 
           if installed_frameworks.include?(:rails)
@@ -66,12 +69,7 @@ module Appsignal
           elsif installed_frameworks.include?(:sinatra)
             install_for_sinatra(config)
           else
-            print colorize "Warning:", :red
-            puts " We could not detect which framework you are using. " \
-              "We'd be very grateful if you email us on support@appsignal.com " \
-              "with information about your setup."
-            puts
-            done_notice
+            install_for_unknown_framework(config)
           end
         end
 
@@ -119,11 +117,18 @@ module Appsignal
           puts
           configure(config, %w[development production staging], true)
 
-          puts "Finish Sinatra configuration"
-          puts "  Sinatra requires some manual configuration."
-          puts "  Add this line beneath require 'sinatra':"
+          puts "Sinatra installation"
+          puts "  Sinatra apps requires some manual setup."
+          puts "  Update the `config.ru` (or the application's main file) to " \
+            "look like this:"
+          puts
+          puts %(require "appsignal")
+          puts %(require "sinatra" # or require "sinatra/base")
           puts
-          puts "  require 'appsignal/integrations/sinatra'"
+          puts "Appsignal.load(:sinatra) # Load the Sinatra integration"
+          puts "Appsignal.start # Start AppSignal"
+          puts
+          puts "# Rest of the config.ru file"
           puts
           puts "  You can find more information in the documentation:"
           puts "  https://docs.appsignal.com/ruby/integrations/sinatra.html"
@@ -137,11 +142,14 @@ module Appsignal
           puts
           configure(config, %w[development production staging], true)
 
-          puts "Finish Padrino installation"
-          puts "  Padrino requires some manual configuration."
-          puts "  After installing the gem, add the following line to /config/boot.rb:"
+          puts "Padrino installation"
+          puts "  Padrino apps requires some manual setup."
+          puts "  After installing the gem, add the following lines to `config/boot.rb`:"
+          puts
+          puts %(require "appsignal")
           puts
-          puts "  require 'appsignal/integrations/padrino"
+          puts "Appsignal.load(:padrino) # Load the Padrino integration"
+          puts "Appsignal.start # Start AppSignal"
           puts
           puts "  You can find more information in the documentation:"
           puts "  https://docs.appsignal.com/ruby/integrations/padrino.html"
@@ -157,7 +165,8 @@ module Appsignal
 
           configure(config, %w[development production staging], true)
 
-          puts "Manual Grape configuration needed"
+          puts "Grape installation"
+          puts "  Grape apps require some manual setup."
           puts "  See the installation instructions at:"
           puts "  https://docs.appsignal.com/ruby/integrations/grape.html"
           press_any_key
@@ -170,11 +179,17 @@ module Appsignal
           puts
           configure(config, %w[development production staging], true)
 
-          puts "Finish Hanami installation"
-          puts "  Hanami requires some manual configuration."
-          puts "  After installing the gem, add the following line to config.ru:"
+          puts "Hanami installation"
+          puts "  Hanami apps requires some manual setup."
+          puts "  Update the config.ru file to include the following:"
+          puts
+          puts %(  require "appsignal")
+          puts %(  require "hanami/boot")
           puts
-          puts "  require 'appsignal/integrations/hanami'"
+          puts "Appsignal.load(:hanami) # Load the Hanami integration"
+          puts "Appsignal.start # Start AppSignal"
+          puts
+          puts "# Rest of the config.ru file"
           puts
           puts "  You can find more information in the documentation:"
           puts "  https://docs.appsignal.com/ruby/integrations/hanami.html"
@@ -197,6 +212,23 @@ module Appsignal
           puts
         end
 
+        def install_for_unknown_framework(config)
+          puts "Installing"
+          config[:name] = required_input("  Enter application name: ")
+          puts
+          configure(config, %w[development production staging], true)
+
+          puts colorize "Warning: We could not detect which framework you are using", :red
+          puts "  Some manual installation is most likely required."
+          puts "  Please check our documentation for supported libraries: "
+          puts "  https://docs.appsignal.com/ruby/integrations.html"
+          puts
+          puts "  We'd be very grateful if you email us on " \
+            "support@appsignal.com with information about your setup."
+          press_any_key
+          done_notice
+        end
+
         def configure(config, environments, name_overwritten)
           install_for_capistrano
 
@@ -240,29 +272,27 @@ module Appsignal
         end
 
         def done_notice
-          sleep 0.3
-          puts colorize "#####################################", :green
-          puts colorize "## AppSignal installation complete ##", :green
-          puts colorize "#####################################", :green
-          sleep 0.3
-          puts
           if Gem.win_platform?
-            puts "The AppSignal agent currently does not work on Microsoft " \
+            print colorize "Warning:", :red
+            puts " The AppSignal agent currently does not work on Microsoft " \
               "Windows. Please push these changes to your staging/production " \
               "environment and make sure some actions are performed. " \
-              "AppSignal should pick up your app after a few minutes."
+              "AppSignal will pick up your app after a few minutes."
           else
-            puts "  Sending example data to AppSignal..."
+            puts "Sending example data to AppSignal..."
             if Appsignal::Demo.transmit
               puts "  Example data sent!"
               puts "  It may take about a minute for the data to appear on https://appsignal.com/accounts"
-              puts
-              puts "  Please return to your browser and follow the instructions."
             else
-              puts "  Couldn't start the AppSignal agent and send example data to AppSignal.com"
-              puts "  Please use `appsignal diagnose` to debug your configuration."
+              print colorize "Error:", :red
+              puts " Couldn't start the AppSignal agent and send example data to AppSignal.com"
+              puts "  Please contact us at support@appsignal.com and " \
+                "send us a diagnose report using `appsignal diagnose`."
+              return
             end
           end
+          puts
+          puts "Please return to your browser and follow the instructions."
         end
 
         def installed_frameworks
@@ -281,7 +311,7 @@ module Appsignal
         def framework_available?(framework_file)
           require framework_file
           true
-        rescue LoadError
+        rescue LoadError, NameError
           false
         end
 

data/lib/appsignal/config.rb

@@ -212,7 +212,7 @@ module Appsignal
     # Initialize a new configuration object for AppSignal.
     #
     # @param root_path [String] Root path of the app.
-    # @param env [String] The environment to load when AppSignal is started. It
+    # @param initial_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.
     # @param initial_config [Hash<String, Object>] The initial configuration to
@@ -622,8 +622,12 @@ module Appsignal
         @config.root_path
       end
 
-      def app_path=(path)
-        @config.root_path = path
+      def app_path=(_path)
+        Appsignal::Utils::StdoutAndLoggerMessage.warning \
+          "The `Appsignal.configure`'s `app_path=` writer is deprecated " \
+            "and can no longer be used to set the root path. " \
+            "Use the `Appsignal.configure`'s method `root_path` keyword argument " \
+            "to set the root path."
       end
 
       def env

data/lib/appsignal/helpers/heartbeat.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Appsignal
+  module Helpers
+    module Heartbeat
+      # @deprecated Use {Appsignal::CheckIn.cron} instead.
+      def heartbeat(name, &block)
+        unless @heartbeat_helper_deprecation_warning_emitted
+          callers = caller
+          Appsignal::Utils::StdoutAndLoggerMessage.warning \
+            "The helper Appsignal.heartbeat has been deprecated. " \
+              "Please update the helper call to Appsignal::CheckIn.cron " \
+              "in the following file and elsewhere to remove this message.\n#{callers.first}"
+          @heartbeat_helper_deprecation_warning_emitted = true
+        end
+        Appsignal::CheckIn.cron(name, &block)
+      end
+    end
+  end
+end

data/lib/appsignal/helpers/instrumentation.rb

@@ -300,7 +300,10 @@ module Appsignal
       # @see .send_error
       # @see https://docs.appsignal.com/ruby/instrumentation/integrating-appsignal.html
       #   AppSignal integration guide
+      # @see https://docs.appsignal.com/ruby/instrumentation/exception-handling.html
+      #   Exception handling guide
       #
+      # @deprecated Use `rescue => error` with {.report_error} instead.
       # @param tags [Hash, nil]
       # @param namespace [String] the namespace for this error.
       # @yield yields the given block.
@@ -309,6 +312,11 @@ module Appsignal
         tags = nil,
         namespace = Appsignal::Transaction::HTTP_REQUEST
       )
+        stdout_and_logger_warning \
+          "The `Appsignal.listen_for_error` helper is deprecated. " \
+            "Please use `rescue => error` and `Appsignal.report_error` instead. " \
+            "Read our exception handling documentation: " \
+            "https://docs.appsignal.com/ruby/instrumentation/exception-handling.html"
         yield
       rescue Exception => error # rubocop:disable Lint/RescueException
         send_error(error) do |transaction|

data/lib/appsignal/integrations/http.rb

@@ -8,13 +8,8 @@ module Appsignal
         parsed_request_uri = uri.is_a?(URI) ? uri : URI.parse(uri.to_s)
         request_uri = "#{parsed_request_uri.scheme}://#{parsed_request_uri.host}"
 
-        begin
-          Appsignal.instrument("request.http_rb", "#{verb.upcase} #{request_uri}") do
-            super
-          end
-        rescue Exception => error # rubocop:disable Lint/RescueException
-          Appsignal.set_error(error)
-          raise error
+        Appsignal.instrument("request.http_rb", "#{verb.upcase} #{request_uri}") do
+          super
         end
       end
     end

data/lib/appsignal/version.rb

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

data/lib/appsignal.rb

@@ -6,7 +6,7 @@ require "stringio"
 
 require "appsignal/logger"
 require "appsignal/utils/stdout_and_logger_message"
-require "appsignal/helpers/heartbeats"
+require "appsignal/helpers/heartbeat"
 require "appsignal/helpers/instrumentation"
 require "appsignal/helpers/metrics"
 
@@ -18,7 +18,7 @@ require "appsignal/helpers/metrics"
 # {Appsignal::Helpers::Metrics}) for ease of use.
 module Appsignal
   class << self
-    include Helpers::Heartbeats
+    include Helpers::Heartbeat
     include Helpers::Instrumentation
     include Helpers::Metrics
 
@@ -228,24 +228,28 @@ module Appsignal
     #   # Or for the environment given as an argument
     #   Appsignal.configure(:production)
     #
+    # @param env [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.
     # @return [void]
     # @see config
     # @see Config
     # @see https://docs.appsignal.com/ruby/configuration.html Configuration guide
     # @see https://docs.appsignal.com/ruby/configuration/options.html Configuration options
-    def configure(env = nil)
+    def configure(env = nil, root_path: nil)
       if Appsignal.started?
         Appsignal.internal_logger
           .warn("AppSignal is already started. Ignoring `Appsignal.configure` call.")
         return
       end
 
-      if config && (env.nil? || config.env == env.to_s)
+      if config && ((env.nil? || config.env == env.to_s) &&
+          (root_path.nil? || config.root_path == root_path))
         config
       else
         @config = Config.new(
-          Config.determine_root_path,
+          root_path || Config.determine_root_path,
           Config.determine_env(env),
           {},
           Appsignal.internal_logger,
@@ -457,6 +461,16 @@ module Appsignal
             "Please update the constant name to Appsignal::Probes " \
             "in the following file to remove this message.\n#{callers.first}"
         Appsignal::Probes
+      when :Heartbeat
+        unless @heartbeat_constant_deprecation_warning_emitted
+          callers = caller
+          Appsignal::Utils::StdoutAndLoggerMessage.warning \
+            "The constant Appsignal::Heartbeat has been deprecated. " \
+              "Please update the constant name to Appsignal::CheckIn::Cron " \
+              "in the following file and elsewhere to remove this message.\n#{callers.first}"
+          @heartbeat_constant_deprecation_warning_emitted = true
+        end
+        Appsignal::CheckIn::Cron
       else
         super
       end
@@ -485,4 +499,4 @@ require "appsignal/integrations/railtie" if defined?(::Rails)
 require "appsignal/transaction"
 require "appsignal/version"
 require "appsignal/transmitter"
-require "appsignal/heartbeat"
+require "appsignal/check_in"