jobtick 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: abfce9cfddae0a798d132217b9376b130afe9446f85e279d3241e7016ed1a89f
-  data.tar.gz: 36590511cdf6e5b07541cdb66589fc5efd7f2250aeb4d5e5e4b20a18976642de
+  metadata.gz: e04ffd3cc7f9e27dc57953e65230cc43d518e3c03413ad1a0f39ef07ac9cde73
+  data.tar.gz: ab9648e703ca1baa1397f07a397dad8a5bac19d4c9773a32c64a82e8ca1e1f92
 SHA512:
-  metadata.gz: a81d1bf56a1e48ed5395bd5d913b8f49aafa163095261e7f066182f138c71f00259d7e428c5ee5a4e685a4320464aecd66aedde77a1f4c41cbb8431491999a39
-  data.tar.gz: f1fc3adfece35b9253e59be4beab12c5b2e1292c8330f287a386f37a71715d9cda922ca216a5219052e7097e1db13404b23c8118a10203fdbbf4024f37651e51
+  metadata.gz: f6ed9a0f0486689336f4eccc6d0d7c75eb20038b999399240ddab1015b5c85d8411a4b7aa08e8ba21943998b5f5efcfa67a6b288a149684ffdd95942744df721
+  data.tar.gz: 4713a1d1f9ee0f4ee9e6e74de2dadac6f18b70fb85bb1f0036554a28feb487a35e1c2b01aea9fe3f7927a9beeb532adc1a87f3840a467cc660fe628fd5a98df8

data/CHANGELOG.md

@@ -1,3 +1,18 @@
+## [0.3.0] - 2026-08-20
+
+- **Fix: Whenever monitors never actually registered.** `Parsers::Whenever` called a `Whenever::JobList#jobs` API that doesn't exist on the real gem (only `attr_reader :roles`), so every discovery attempt raised and was silently swallowed — no Whenever job has ever been registered by prior versions. The parser now reads the real, public `generate_cron_output` instead, and `WheneverSetup` injects the monitor key as a literal job option so the registered key and the pinged key are always the same value by construction. `config/schedule.rb` needs `require 'jobtick/whenever_setup'` before `JobTick::WheneverSetup.install!(self)` now — see the README.
+- **Fix: the Whenever shell wrapper could send a false failure alert.** `inner && ping_completed || ping_failed` fired the `failed` ping whenever the *completed* ping's own `curl` call failed — even though the job succeeded. Rewritten as `if <job> ; then ... completed ; else ... failed ; fi`, plus `curl --max-time 10` so a hung ping can't wedge a cron slot, and `exit $rc` so cron still sees the job's real exit status.
+- **Fix: the persistent HTTPS connection was fork-unsafe.** A clustered app server (Puma with `preload_app!`, Passenger, Unicorn) forking after boot left every worker sharing one file descriptor, corrupting or dropping pings under load. The dispatcher now detects a pid change on every call from `.enqueue`/`.send_sync` and rebuilds its connection and background thread in the child without touching the parent's socket.
+- **Fix: `Configuration#environment`-scoped `config/recurring.yml` registered environment names as monitors.** When the current environment had no matching top-level key, the parser fell back to treating the whole file as a task list — registering `solid_queue.production`, `solid_queue.staging`, etc. as permanently-down monitors. It now returns no monitors (with a warning) instead.
+- **Fix:** HTTP responses were previously discarded entirely — a bad API key returned 401 forever in total silence. The dispatcher now logs a 401/403 once and opens a circuit breaker so pings stop being sent to an API that's rejecting them; other error statuses are logged at a throttled rate.
+- **Fix:** `Dispatcher.reset!` could leave a stale connection open (e.g. after only `.send_sync` had ever run), so a subsequent endpoint change kept posting to the old host.
+- Add a circuit breaker: after 3 consecutive network failures, the dispatcher stops attempting connections for a backed-off window (30s–300s) instead of paying a connect timeout per queued ping during an outage.
+- Boot-time sync no longer blocks: it now goes through the async dispatcher, and is skipped entirely for `rails console`, `rails runner`, and rake tasks (configurable via `config.sync_on_boot`). `rake jobtick:sync` remains a blocking call for use as an explicit deploy step.
+- Add `config.ping_started` (default `true`) to suppress the `started` ping for high-frequency jobs.
+- `Parsers::Whenever`/`Parsers::SolidQueue` now resolve their config file paths against `Rails.root` (or `Dir.pwd` outside Rails) instead of the process's current working directory.
+- Two monitors that resolve to the same job class now log a warning naming both, instead of one silently losing its pings to the other.
+- `Configuration#enabled?` is now used consistently by `Client` and `Monitor` instead of each open-coding the same check.
+
 ## [0.2.0] - 2026-05-28
 
 - Performance: pings are now dispatched asynchronously on a single daemon thread, so job workers no longer block on network I/O. A persistent, keep-alive HTTPS connection is reused for all pings (no more TCP/TLS handshake per ping).

data/README.md

@@ -103,6 +103,20 @@ end
 
 With `prune` enabled, a deploy acts as the single source of truth: any monitor whose key is not present in the current payload is permanently deleted. You can also remove individual monitors manually from the JobTick dashboard at any time.
 
+### Deploying
+
+JobTick syncs your monitors automatically the first time a web or worker process boots after a deploy — this sync runs in the background and never blocks startup, even if the JobTick API is slow or unreachable.
+
+To skip the wait until that first boot (or to sync from CI as an explicit deploy step), run it directly:
+
+```
+bundle exec rake jobtick:sync
+```
+
+This is the one case where the sync blocks — it prints the number of monitors registered, so its output is only trustworthy if it actually waited for the API to respond.
+
+Boot-time sync is automatically skipped for `rails console`, `rails runner`, and any rake task — none of them should pay for a sync just to boot, and `rails runner` matters especially, since Whenever's cron wrapper shells out through it on every tick. Set `config.sync_on_boot = false` to disable the automatic sync everywhere and rely solely on `rake jobtick:sync`.
+
 ---
 
 ## What gets monitored
@@ -122,6 +136,8 @@ sync_exchange_rates:
 
 At boot, JobTick reads this file and registers a monitor for each entry. It then installs an `around_perform` hook into `ActiveJob::Base` so every job execution automatically sends `started`, `completed`, and `failed` pings. No changes to your job files.
 
+Entries scheduled with `command:` instead of `class:` run a raw shell command rather than a Ruby job class, so there's no hook point for JobTick to instrument automatically — these are skipped (with a log line naming them) rather than registered as a monitor JobTick can never ping.
+
 ### Sidekiq periodic jobs
 
 Supports both **sidekiq-cron** and **Sidekiq::Periodic**:
@@ -143,15 +159,19 @@ JobTick installs a server middleware that wraps every job execution. For native
 
 ### Whenever (`config/schedule.rb`)
 
-Whenever schedules jobs as cron shell commands, so there is no Ruby hook point to instrument automatically. Add one line to `config/schedule.rb`:
+Whenever schedules jobs as cron shell commands, so there is no Ruby hook point to instrument automatically. Add two lines to the top of `config/schedule.rb`:
 
 ```ruby
+require 'jobtick/whenever_setup'
 JobTick::WheneverSetup.install!(self)
 ```
 
-This overrides the built-in `runner`, `rake`, and `command` job types to wrap every execution with `curl` pings. Your existing schedule entries need no changes:
+`jobtick/whenever_setup` is a separate file from the main gem on purpose — `config/schedule.rb` is evaluated standalone (by `whenever --update-crontab`, and again by JobTick itself at boot to discover your jobs), not as part of a normal Rails boot, so it needs its own explicit require regardless of whether `gem 'jobtick'` is already in your Gemfile.
+
+This overrides the built-in `runner`, `rake`, and `command` job types to wrap every execution with `curl` pings, gated by a real `if`/`then`/`else` so a network blip on the ping itself can never be mistaken for the job failing. Your existing schedule entries need no other changes:
 
 ```ruby
+require 'jobtick/whenever_setup'
 JobTick::WheneverSetup.install!(self)
 
 every 1.day, at: '2:00 am' do
@@ -163,14 +183,7 @@ every :hour do
 end
 ```
 
-After adding the line, run `whenever --update-crontab` as normal and all jobs will start sending heartbeats.
-
-If jobtick is not already loaded via your Rails environment, require it first:
-
-```ruby
-require 'jobtick/whenever_setup'
-JobTick::WheneverSetup.install!(self)
-```
+After adding these lines, run `whenever --update-crontab` as normal and all jobs will start sending heartbeats. JobTick discovers Whenever monitors by reading the same file back with the real `whenever` gem, so `whenever` must be a dependency of your app (it usually already is) — add it with `require: false` is fine, JobTick loads it itself when needed.
 
 ---
 

data/lib/jobtick/client.rb

@@ -8,8 +8,7 @@ module JobTick
     SYNC_PATH   = "/monitors/sync"
 
     def ping(monitor_key, status:, duration: nil, message: nil)
-      config = JobTick.config
-      return unless config.enabled && !config.api_key.nil?
+      return unless JobTick.config.enabled?
 
       payload = { status: status }
       payload[:duration] = duration.round(3) if duration
@@ -18,15 +17,18 @@ module JobTick
       Dispatcher.enqueue("#{PING_PREFIX}#{monitor_key}", payload)
     end
 
-    def register(monitors, app_name: nil, prune: false)
-      config = JobTick.config
-      return unless config.enabled && !config.api_key.nil?
+    def register(monitors, app_name: nil, prune: false, sync: true)
+      return unless JobTick.config.enabled?
 
       payload = { monitors: monitors }
       payload[:app_name] = app_name if app_name && !app_name.empty?
       payload[:prune]    = true if prune
 
-      Dispatcher.send_sync(SYNC_PATH, payload)
+      if sync
+        Dispatcher.send_sync(SYNC_PATH, payload)
+      else
+        Dispatcher.enqueue(SYNC_PATH, payload)
+      end
     end
   end
 end

data/lib/jobtick/configuration.rb

@@ -4,14 +4,17 @@ module JobTick
   class Configuration
     DEFAULT_QUEUE_LIMIT = 1000
 
-    attr_accessor :api_key, :endpoint, :environment, :enabled, :prune, :queue_limit
+    attr_accessor :api_key, :endpoint, :environment, :enabled, :prune, :queue_limit,
+                  :sync_on_boot, :ping_started
 
     def initialize
-      @endpoint    = "https://api.jobtick.app/v1"
-      @environment = ENV["RAILS_ENV"] || ENV["RACK_ENV"] || "production"
-      @enabled     = @environment == "production"
-      @prune       = false
-      @queue_limit = DEFAULT_QUEUE_LIMIT
+      @endpoint     = "https://api.jobtick.app/v1"
+      @environment  = ENV["RAILS_ENV"] || ENV["RACK_ENV"] || "production"
+      @enabled      = @environment == "production"
+      @prune        = false
+      @queue_limit  = DEFAULT_QUEUE_LIMIT
+      @sync_on_boot = true
+      @ping_started = true
     end
 
     def enabled?

data/lib/jobtick/dispatcher.rb

@@ -12,14 +12,30 @@ module JobTick
   #
   # All HTTP work (sync register + async pings) shares one Net::HTTP instance
   # serialized by @http_mutex. The connection is reopened lazily after errors.
+  #
+  # Fork safety: .enqueue and .send_sync are always called from the thread
+  # that survives a fork (the caller's thread — a job thread, or the process
+  # that just booted). Neither the background dispatcher thread nor its
+  # Net::HTTP socket survive a fork, even though the Ruby objects referencing
+  # them do (they're just inherited memory). guard_fork! runs first on both
+  # public entry points and drops those stale references — without closing
+  # the socket, which still belongs to the parent — so each process lazily
+  # builds its own connection and dispatcher thread.
   module Dispatcher
     SHUTDOWN_SIGNAL = :__shutdown__
+    FLUSH_SENTINEL = :__flush__
     HEADER_CONTENT_TYPE = "application/json"
     USER_AGENT = "jobtick-ruby/#{JobTick::VERSION}".freeze
     OPEN_TIMEOUT = 5
     READ_TIMEOUT = 5
     KEEP_ALIVE_TIMEOUT = 30
 
+    UNAUTHORIZED_CODES = %w[401 403].freeze
+    FAILURE_THRESHOLD = 3
+    CIRCUIT_INITIAL_BACKOFF = 30
+    CIRCUIT_MAX_BACKOFF = 300
+    STATUS_WARN_INTERVAL = 60
+
     NETWORK_ERRORS = [
       IOError, EOFError,
       Errno::ECONNRESET, Errno::ECONNREFUSED, Errno::ECONNABORTED,
@@ -34,26 +50,31 @@ module JobTick
       def enqueue(path, payload)
         return send_request(path, payload) if @synchronous
 
+        guard_fork!
         ensure_started
         @queue.push([path, payload], true)
         nil
       rescue ThreadError
-        @dropped += 1
+        dropped_mutex.synchronize { @dropped = (@dropped || 0) + 1 }
         nil
       end
 
       def send_sync(path, payload)
+        guard_fork!
         send_request(path, payload)
       end
 
       def flush(timeout: 5)
-        return unless @running && @queue
+        return unless @running && @queue && @thread&.alive?
 
-        deadline = monotonic + timeout
-        until @queue.empty? && @inflight.zero?
-          sleep 0.001
-          break if monotonic > deadline
+        ack = Queue.new
+        begin
+          @queue.push([FLUSH_SENTINEL, ack])
+        rescue ThreadError
+          return
         end
+        ack.pop(timeout: timeout)
+        nil
       end
 
       def shutdown(timeout: 2)
@@ -72,17 +93,46 @@ module JobTick
 
       def reset!
         shutdown(timeout: 1) if @running
+        close_http # shutdown is a no-op if only .send_sync ever ran, so close explicitly too
         @queue = nil
         @thread = nil
         @dropped = 0
-        @inflight = 0
         @endpoint_uri = nil
         @at_exit_registered = false
         @synchronous = false
+        @pid = nil
+        @consecutive_failures = 0
+        @circuit_until = nil
+        @unauthorized_warned = false
+        @status_warned_at = nil
       end
 
       private
 
+      # Atomic under fork_mutex so a thread that loses the race can never null
+      # out @queue/@http *after* another thread has already rebuilt them for
+      # the new pid — once this returns, @pid always matches Process.pid, and
+      # that transition only ever happens once per fork.
+      def guard_fork!
+        return if @pid == Process.pid
+
+        fork_mutex.synchronize do
+          return if @pid == Process.pid
+
+          http_mutex.synchronize { @http = nil } # not #finish — the socket belongs to the parent
+          boot_mutex.synchronize do
+            @queue = nil
+            @thread = nil
+            @running = false
+          end
+          @pid = Process.pid
+        end
+      end
+
+      def fork_mutex
+        @fork_mutex ||= Mutex.new
+      end
+
       def ensure_started
         return if @running
 
@@ -91,7 +141,6 @@ module JobTick
 
           @queue   = SizedQueue.new(queue_limit)
           @dropped = 0
-          @inflight = 0
           @thread = Thread.new { run_loop }
           @thread.name = "jobtick-dispatcher" if @thread.respond_to?(:name=)
           @running = true
@@ -107,6 +156,10 @@ module JobTick
         @http_mutex ||= Mutex.new
       end
 
+      def dropped_mutex
+        @dropped_mutex ||= Mutex.new
+      end
+
       def queue_limit
         JobTick.config.queue_limit || Configuration::DEFAULT_QUEUE_LIMIT
       end
@@ -122,10 +175,13 @@ module JobTick
         while (item = @queue.pop)
           break if item == SHUTDOWN_SIGNAL
 
-          @inflight = 1
-          path, payload = item
-          send_request(path, payload)
-          @inflight = 0
+          key, payload = item
+          if key.equal?(FLUSH_SENTINEL)
+            payload.push(true)
+            next
+          end
+
+          send_request(key, payload)
         end
       rescue StandardError => e
         JobTick.logger.warn("[JobTick] Dispatcher thread crashed: #{e.message}")
@@ -134,26 +190,82 @@ module JobTick
       end
 
       def send_request(path, payload)
-        body = JSON.generate(payload)
-        full_path = "#{endpoint_uri.path}#{path}"
-        http_mutex.synchronize do
-          http = http_connection
-          request = Net::HTTP::Post.new(full_path)
-          request["Content-Type"]  = HEADER_CONTENT_TYPE
-          request["Authorization"] = "Bearer #{JobTick.config.api_key}"
-          request["User-Agent"]    = USER_AGENT
-          request.body = body
-          http.request(request)
-        end
+        return nil if circuit_open?
+
+        response = http_mutex.synchronize { http_connection.request(build_request(path, payload)) }
+        handle_response(path, response)
+        response
       rescue *NETWORK_ERRORS => e
         JobTick.logger.warn("[JobTick] HTTP request failed (#{path}): #{e.message}")
         teardown_http
+        record_failure
         nil
       rescue StandardError => e
         JobTick.logger.warn("[JobTick] HTTP request failed (#{path}): #{e.message}")
         nil
       end
 
+      def build_request(path, payload)
+        request = Net::HTTP::Post.new("#{endpoint_uri.path}#{path}")
+        request["Content-Type"]  = HEADER_CONTENT_TYPE
+        request["Authorization"] = "Bearer #{JobTick.config.api_key}"
+        request["User-Agent"]    = USER_AGENT
+        request.body = JSON.generate(payload)
+        request
+      end
+
+      def handle_response(path, response)
+        code = response.code
+
+        if code.start_with?("2")
+          record_success
+        elsif UNAUTHORIZED_CODES.include?(code)
+          warn_unauthorized_once
+          open_circuit(CIRCUIT_MAX_BACKOFF)
+        else
+          record_failure
+          warn_status_throttled(code, path)
+        end
+      end
+
+      def circuit_open?
+        !@circuit_until.nil? && monotonic < @circuit_until
+      end
+
+      def open_circuit(seconds)
+        @circuit_until = monotonic + seconds + rand(5)
+      end
+
+      def record_failure
+        @consecutive_failures = (@consecutive_failures || 0) + 1
+        return if @consecutive_failures < FAILURE_THRESHOLD
+
+        backoff = CIRCUIT_INITIAL_BACKOFF * (2**(@consecutive_failures - FAILURE_THRESHOLD))
+        open_circuit([backoff, CIRCUIT_MAX_BACKOFF].min)
+      end
+
+      def record_success
+        @consecutive_failures = 0
+        @circuit_until = nil
+      end
+
+      def warn_unauthorized_once
+        return if @unauthorized_warned
+
+        @unauthorized_warned = true
+        JobTick.logger.warn("[JobTick] API rejected the API key (401/403); pings are being discarded")
+      end
+
+      def warn_status_throttled(code, path)
+        @status_warned_at ||= {}
+        last = @status_warned_at[code]
+        now = monotonic
+        return if last && (now - last) < STATUS_WARN_INTERVAL
+
+        @status_warned_at[code] = now
+        JobTick.logger.warn("[JobTick] API returned #{code} (#{path})")
+      end
+
       def endpoint_uri
         @endpoint_uri ||= URI(JobTick.config.endpoint)
       end

data/lib/jobtick/monitor.rb

@@ -6,10 +6,10 @@ module JobTick
 
     def self.run(key)
       config = JobTick.config
-      return yield unless config.enabled && !config.api_key.nil?
+      return yield unless config.enabled?
 
       client = JobTick.client
-      client.ping(key, status: :started)
+      client.ping(key, status: :started) if config.ping_started
       started = Process.clock_gettime(MONOTONIC)
       result  = yield
       duration = Process.clock_gettime(MONOTONIC) - started

data/lib/jobtick/parsers/sidekiq.rb

@@ -1,14 +1,9 @@
 # frozen_string_literal: true
 
+require_relative "../parsers"
+
 module JobTick
   module Parsers
-    SLUG_RE = /[^a-z0-9]+/
-    SLUG_TRIM_RE = /\A_+|_+\z/
-
-    def self.slugify(str)
-      str.downcase.gsub(SLUG_RE, "_").gsub(SLUG_TRIM_RE, "")
-    end
-
     class Sidekiq
       def self.parse
         return [] unless defined?(::Sidekiq)

data/lib/jobtick/parsers/solid_queue.rb

@@ -8,28 +8,78 @@ module JobTick
       RECURRING_FILE = "config/recurring.yml"
 
       def self.parse
-        return [] unless File.exist?(RECURRING_FILE)
+        return [] unless File.exist?(recurring_path)
 
-        yaml = YAML.load_file(RECURRING_FILE, aliases: true)
-        env  = JobTick.config.environment
+        yaml = YAML.load_file(recurring_path, aliases: true)
+        return [] unless yaml.is_a?(Hash)
 
-        tasks = yaml[env] || yaml["default"] || yaml
-        return [] unless tasks.is_a?(Hash)
+        tasks = resolve_tasks(yaml)
+        return [] if tasks.empty?
 
-        tasks.each_with_object([]) do |(key, config), out|
-          next unless config.is_a?(Hash)
+        class_tasks, command_only = tasks.partition { |_, config| task_class?(config) }
+        warn_command_only(command_only) if command_only.any?
 
-          out << {
-            key: "solid_queue.#{key}",
-            schedule: config["schedule"],
-            source: "solid_queue",
-            task: config["class"]
-          }
-        end
+        class_tasks.map { |key, config| monitor_for(key, config) }
       rescue StandardError => e
         JobTick.logger.warn("[JobTick] Solid Queue parser failed: #{e.message}")
         []
       end
+
+      # recurring.yml is either flat (task name => task config at the top
+      # level) or environment-scoped (environment name => { task name =>
+      # task config }). Distinguish by whether any top-level value actually
+      # looks like a task, rather than assuming the current environment is
+      # always present — a document scoped to "production"/"development"
+      # read under "staging" used to fall through to `yaml` itself and
+      # register every *environment name* as an unpingable monitor.
+      def self.resolve_tasks(yaml)
+        return yaml if yaml.any? { |_, v| task?(v) }
+
+        env = JobTick.config.environment
+        scoped = yaml[env] || yaml["default"]
+        return scoped if scoped.is_a?(Hash)
+
+        JobTick.logger.warn(
+          "[JobTick] #{RECURRING_FILE} is environment-scoped but has no entry for " \
+          "\"#{env}\" (or \"default\"); no Solid Queue monitors registered"
+        )
+        {}
+      end
+      private_class_method :resolve_tasks
+
+      def self.task?(value)
+        value.is_a?(Hash) && (value.key?("class") || value.key?("command"))
+      end
+      private_class_method :task?
+
+      def self.task_class?(value)
+        value.is_a?(Hash) && value.key?("class")
+      end
+      private_class_method :task_class?
+
+      def self.monitor_for(key, config)
+        { key: "solid_queue.#{key}", schedule: config["schedule"], source: "solid_queue", task: config["class"] }
+      end
+      private_class_method :monitor_for
+
+      # command: tasks run a raw shell command rather than a Ruby job class,
+      # so there's no ActiveJob/Sidekiq hook to ping them from — unlike
+      # Whenever, Solid Queue gives us no shell wrapping point either.
+      # Registering them anyway would create monitors that alert as
+      # permanently down, so we skip them and say why once.
+      def self.warn_command_only(command_only)
+        keys = command_only.map(&:first).join(", ")
+        JobTick.logger.warn(
+          "[JobTick] #{RECURRING_FILE} declares command-based task(s) (#{keys}) which have no " \
+          "Ruby class to hook into; JobTick cannot monitor them automatically"
+        )
+      end
+      private_class_method :warn_command_only
+
+      def self.recurring_path
+        File.expand_path(RECURRING_FILE, JobTick.root)
+      end
+      private_class_method :recurring_path
     end
   end
 end

data/lib/jobtick/parsers/whenever.rb

@@ -1,34 +1,77 @@
 # frozen_string_literal: true
 
+require_relative "../parsers"
+
 module JobTick
   module Parsers
     class Whenever
       SCHEDULE_FILE = "config/schedule.rb"
+      JOBTICK_KEY_RE = /JOBTICK_KEY=(\S+)/
 
+      # Whenever::JobList has no public reader for its parsed jobs (only
+      # attr_reader :roles), and its internal @jobs is a private, nested
+      # [mailto][time_scope] => [Job] structure with no [] accessor on Job
+      # either. The only stable, public surface is #generate_cron_output —
+      # the same text Whenever writes to the crontab. We scan that instead
+      # of reaching into private internals.
+      #
+      # This only finds anything once JobTick::WheneverSetup.install!(self)
+      # has been added to config/schedule.rb: that's what stamps a literal
+      # JOBTICK_KEY=<key> into each job's command, which is what we key off
+      # of here. That also guarantees the registered key and the pinged key
+      # can never drift apart — they're the same literal.
       def self.parse
-        return [] unless defined?(::Whenever)
-        return [] unless File.exist?(SCHEDULE_FILE)
-
-        schedule = ::Whenever::JobList.new(file: SCHEDULE_FILE)
-        schedule.jobs.flat_map do |period, jobs|
-          jobs.map do |job|
-            {
-              key: job_key(job),
-              schedule: period.to_s,
-              source: "whenever",
-              task: job[:task].to_s.strip
-            }
-          end
-        end
+        return [] unless whenever_available?
+        return [] unless File.exist?(schedule_path)
+
+        schedule = ::Whenever::JobList.new(file: schedule_path)
+        monitors = schedule.generate_cron_output.to_s.each_line.filter_map { |line| monitor_from_line(line) }
+
+        warn_if_not_installed if monitors.empty?
+        monitors
       rescue StandardError => e
         JobTick.logger.warn("[JobTick] Whenever parser failed: #{e.message}")
         []
       end
 
-      def self.job_key(job)
-        "whenever.#{Parsers.slugify(job[:task].to_s.strip)}"
+      def self.monitor_from_line(line)
+        key = line[JOBTICK_KEY_RE, 1]
+        return nil unless key
+
+        { key: key, schedule: cron_fields(line), source: "whenever", task: nil }
+      end
+      private_class_method :monitor_from_line
+
+      def self.cron_fields(line)
+        line = line.strip
+        return line[/\A@\S+/] if line.start_with?("@")
+
+        line.split(/\s+/, 6).first(5).join(" ")
+      end
+      private_class_method :cron_fields
+
+      def self.whenever_available?
+        return true if defined?(::Whenever::JobList)
+
+        require "whenever"
+        true
+      rescue LoadError
+        false
+      end
+      private_class_method :whenever_available?
+
+      def self.warn_if_not_installed
+        JobTick.logger.warn(
+          "[JobTick] #{SCHEDULE_FILE} found but JobTick::WheneverSetup.install!(self) " \
+          "is not installed there; no Whenever monitors registered"
+        )
+      end
+      private_class_method :warn_if_not_installed
+
+      def self.schedule_path
+        File.expand_path(SCHEDULE_FILE, JobTick.root)
       end
-      private_class_method :job_key
+      private_class_method :schedule_path
     end
   end
 end

data/lib/jobtick/parsers.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module JobTick
+  module Parsers
+    SLUG_RE = /[^a-z0-9]+/
+    SLUG_TRIM_RE = /\A_+|_+\z/
+
+    def self.slugify(str)
+      str.downcase.gsub(SLUG_RE, "_").gsub(SLUG_TRIM_RE, "")
+    end
+
+    # Shared by Parsers::Whenever (which reads it back out of the generated
+    # crontab) and WheneverSetup (which injects it as a job option). Keeping
+    # both sides derived from this one method is what guarantees the key a
+    # monitor is registered under matches the key its pings are sent to.
+    def self.whenever_key(task)
+      "whenever.#{slugify(task.to_s.strip)}"
+    end
+  end
+end

data/lib/jobtick/railtie.rb

@@ -2,6 +2,13 @@
 
 module JobTick
   class Railtie < Rails::Railtie
+    # Processes where a boot-time sync would be pure waste: `rails console`,
+    # any rake task, and `rails runner` — the latter matters most, since
+    # WheneverSetup shells out through `bundle exec rails runner` on every
+    # cron tick, so without this a minutely job would pay a full sync POST
+    # every minute just to boot.
+    ONE_OFF_PROCESSES = %w[rake].freeze
+
     initializer "jobtick.sync_registry" do
       ActiveSupport.on_load(:after_initialize) do
         next unless JobTick.config.enabled
@@ -13,7 +20,7 @@ module JobTick
         require_relative "hooks/active_job"
         require_relative "middleware/sidekiq"
 
-        JobTick::Registry.sync
+        JobTick::Registry.sync(sync: false) if JobTick::Railtie.sync_on_boot?
 
         ::ActiveJob::Base.include(JobTick::Hooks::ActiveJob) if defined?(::ActiveJob::Base)
         JobTick::Middleware::Sidekiq.install if defined?(::Sidekiq)
@@ -23,5 +30,24 @@ module JobTick
     rake_tasks do
       load File.expand_path("../tasks/jobtick.rake", __dir__)
     end
+
+    def self.sync_on_boot?
+      return false unless JobTick.config.sync_on_boot
+
+      !one_off_process?
+    end
+
+    # `Rails::Console` / `Rails::Command::RunnerCommand` / `Rails::Command::RakeCommand`
+    # are only defined when boot was reached via `bin/rails console|runner|<task>` — the
+    # command file that defines each constant has to be loaded before boot can start.
+    # A plain `bundle exec rake <task>` never loads railties' command layer at all, so
+    # it's caught by the $PROGRAM_NAME basename check instead.
+    def self.one_off_process?
+      return true if defined?(Rails::Console)
+      return true if defined?(Rails::Command::RunnerCommand)
+      return true if defined?(Rails::Command::RakeCommand)
+
+      ONE_OFF_PROCESSES.include?(File.basename($PROGRAM_NAME.to_s, ".*"))
+    end
   end
 end

data/lib/jobtick/registry.rb

@@ -2,24 +2,54 @@
 
 module JobTick
   class Registry
-    def self.sync
+    # sync: true blocks the caller until the register POST completes (used by
+    # `rake jobtick:sync`, whose printed count must be truthful). The railtie
+    # boot hook passes sync: false so a slow or unreachable API cannot delay
+    # every process boot.
+    def self.sync(sync: true)
       monitors = [
         Parsers::Whenever.parse,
         Parsers::SolidQueue.parse,
         Parsers::Sidekiq.parse
       ].flatten.compact
 
-      map = {}
-      monitors.each { |m| map[m[:task]] = m[:key] if m[:task] }
-      JobTick.monitor_map = map.freeze
+      JobTick.monitor_map = build_monitor_map(monitors)
 
       return [] if monitors.empty?
 
       app_name = Rails.application.class.module_parent_name if defined?(Rails)
-      options  = { app_name: app_name }
+      options  = { app_name: app_name, sync: sync }
       options[:prune] = true if JobTick.config.prune
       JobTick.client.register(monitors, **options)
       monitors
     end
+
+    # Builds the class-name => monitor-key map the ActiveJob hook and Sidekiq
+    # middleware use to find a job's monitor. Two monitors can legitimately
+    # target the same class (e.g. the same recurring job class scheduled
+    # twice with different arguments) — that's a real config ambiguity, not a
+    # crash, so we log it and keep the first mapping rather than silently
+    # letting the second overwrite it.
+    def self.build_monitor_map(monitors)
+      map = {}
+
+      monitors.each do |monitor|
+        task = monitor[:task]
+        next unless task
+
+        if map.key?(task)
+          JobTick.logger.warn(
+            "[JobTick] Multiple monitors target #{task} (#{map[task]} and #{monitor[:key]}); " \
+            "only #{map[task]} will receive pings for it"
+          )
+          next
+        end
+
+        map[task] = monitor[:key]
+      end
+
+      map.freeze
+    end
+    private_class_method :build_monitor_map
   end
 end

data/lib/jobtick/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module JobTick
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

data/lib/jobtick/whenever_setup.rb

@@ -11,27 +11,48 @@ module JobTick
   #
   # This replaces the :runner, :rake, and :command job types so that every
   # scheduled job automatically sends started/completed/failed heartbeats without
-  # any per-job configuration.
+  # any per-job configuration. The monitor key is injected as a literal job
+  # option (:jobtick_key) rather than recomputed in shell, so it always matches
+  # the key Parsers::Whenever reads back out of the generated crontab.
   module WheneverSetup
+    TEMPLATES = {
+      runner: "cd :path && bundle exec rails runner ':task' :output",
+      rake: "cd :path && bundle exec rake :task :output",
+      command: ":task :output"
+    }.freeze
+
+    KEY_INJECTOR = Module.new do
+      TEMPLATES.each_key do |type|
+        define_method(type) do |task, *args|
+          opts = args[0].is_a?(Hash) ? args[0].dup : {}
+          opts[:jobtick_key] = JobTick::Parsers.whenever_key(task)
+          super(task, opts)
+        end
+      end
+    end
+    private_constant :KEY_INJECTOR
+
     def self.install!(schedule)
       endpoint = JobTick.config.endpoint
 
-      schedule.job_type :runner,  wrap(endpoint, "cd :path && bundle exec rails runner ':task' :output")
-      schedule.job_type :rake,    wrap(endpoint, "cd :path && bundle exec rake :task :output")
-      schedule.job_type :command, wrap(endpoint, "cd :path && :task :output")
+      TEMPLATES.each { |type, inner| schedule.job_type(type, wrap(endpoint, inner)) }
+
+      # Prepended after job_type defines the singleton methods above, but order
+      # doesn't matter for resolution: a prepended module always sits ahead of
+      # the singleton class in the ancestor chain, so this always wins and
+      # `super` always reaches the method job_type just defined.
+      schedule.singleton_class.prepend(KEY_INJECTOR)
     end
 
     def self.wrap(endpoint, inner_cmd)
-      # Shell equivalent of Parsers.slugify: downcase, collapse non-alnum runs to _, strip leading/trailing _.
-      sed = "sed 's/[^a-z0-9][^a-z0-9]*/_/g' | sed 's/^_*//;s/_*$//'"
-      slug = "$(printf '%s' ':task' | tr '[:upper:]' '[:lower:]' | #{sed})"
-      key_assign = %(JOBTICK_KEY="whenever.#{slug}")
-
-      "#{key_assign} ; " \
-        "curl -sf \"#{endpoint}/ping/$JOBTICK_KEY/started\" ; " \
-        "#{inner_cmd} && " \
-        "curl -sf \"#{endpoint}/ping/$JOBTICK_KEY/completed\" || " \
-        "curl -sf \"#{endpoint}/ping/$JOBTICK_KEY/failed\""
+      key_assign = "JOBTICK_KEY=:jobtick_key"
+      started   = %(curl -sf --max-time 10 "#{endpoint}/ping/$JOBTICK_KEY/started")
+      completed = %(curl -sf --max-time 10 "#{endpoint}/ping/$JOBTICK_KEY/completed")
+      failed    = %(curl -sf --max-time 10 "#{endpoint}/ping/$JOBTICK_KEY/failed")
+
+      "#{key_assign} ; #{started} ; " \
+        "if #{inner_cmd} ; then rc=0 ; #{completed} ; " \
+        "else rc=$? ; #{failed} ; fi ; exit $rc"
     end
     private_class_method :wrap
   end

data/lib/jobtick.rb

@@ -5,6 +5,7 @@ require_relative "jobtick/version"
 require_relative "jobtick/configuration"
 require_relative "jobtick/client"
 require_relative "jobtick/monitor"
+require_relative "jobtick/parsers"
 require_relative "jobtick/railtie" if defined?(Rails::Railtie)
 
 module JobTick
@@ -25,8 +26,20 @@ module JobTick
       @client ||= Client.new
     end
 
+    # The app's root directory, used to resolve schedule/recurring config
+    # files. Falls back to the process's working directory when Rails isn't
+    # loaded (or hasn't set a root yet) so discovery doesn't silently depend
+    # on the caller's cwd.
+    def root
+      if defined?(Rails) && Rails.respond_to?(:root) && Rails.root
+        Rails.root.to_s
+      else
+        Dir.pwd
+      end
+    end
+
     def logger
-      defined?(Rails) ? Rails.logger : Logger.new($stdout)
+      (defined?(Rails) && Rails.logger) || (@fallback_logger ||= Logger.new($stdout))
     end
 
     def monitor_map

data/sig/jobtick.rbs

@@ -1,4 +1,4 @@
-module Jobtick
+module JobTick
   VERSION: String
   # See the writing guide of rbs: https://github.com/ruby/rbs#guides
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jobtick
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Clearstack Labs
@@ -42,6 +42,7 @@ files:
 - lib/jobtick/hooks/active_job.rb
 - lib/jobtick/middleware/sidekiq.rb
 - lib/jobtick/monitor.rb
+- lib/jobtick/parsers.rb
 - lib/jobtick/parsers/sidekiq.rb
 - lib/jobtick/parsers/solid_queue.rb
 - lib/jobtick/parsers/whenever.rb