Rename heartbeats to cron check-ins

This is pending confirmation of the specific terms of the rename,
as well as the shape of the new endpoints and so on. The specific
names used here are placeholders.

Invoking the previous method and module names raises a deprecation
warning the first time it takes place, and forwards the call to the
new method and module names.

.changesets/deprecate-heartbeats.md

@@ -0,0 +1,6 @@
+---
+bump: patch
+type: deprecate
+---
+
+Calls to `Appsignal.heartbeat` and `Appsignal::Heartbeat` will emit a deprecation warning.

.changesets/rename-heartbeats-to-cron-check-ins.md

@@ -0,0 +1,18 @@
+---
+bump: patch
+type: change
+---
+
+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
+```

lib/appsignal.rb

@@ -6,7 +6,7 @@
 
 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 @@
 # {Appsignal::Helpers::Metrics}) for ease of use.
 module Appsignal
   class << self
-    include Helpers::Heartbeats
+    include Helpers::Heartbeat
     include Helpers::Instrumentation
     include Helpers::Metrics
 
@@ -461,6 +461,16 @@ def const_missing(name)
             "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
@@ -489,4 +499,4 @@ def const_missing(name)
 require "appsignal/transaction"
 require "appsignal/version"
 require "appsignal/transmitter"
-require "appsignal/heartbeat"
+require "appsignal/check_in"

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.12.7
+      # @see https://docs.appsignal.com/check-ins/cron
+      def cron(name)
+        cron = Appsignal::CheckIn::Cron.new(:name => name)
+        output = nil
+
+        if block_given?
+          cron.start
+          output = yield
+        end
+
+        cron.finish
+        output
+      end
+    end
+  end
+end
+
+require "appsignal/check_in/cron"

lib/appsignal/check_in/cron.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Appsignal
+  module CheckIn
+    class Cron
+      class << self
+        # @api private
+        def transmitter
+          @transmitter ||= Appsignal::Transmitter.new(
+            "#{Appsignal.config[:logging_endpoint]}/checkins/cron/json"
+          )
+        end
+      end
+
+      attr_reader :name, :id
+
+      def initialize(name:)
+        @name = name
+        @id = SecureRandom.hex(8)
+      end
+
+      def start
+        transmit_event("start")
+      end
+
+      def finish
+        transmit_event("finish")
+      end
+
+      private
+
+      def event(kind)
+        {
+          :name => name,
+          :id => @id,
+          :kind => kind,
+          :timestamp => Time.now.utc.to_i
+        }
+      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 `#{name}` (#{id}) #{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

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