jobtick 0.1.4 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7db7f99928881432d43b819fb1ffa2772e6a690f659b0a54ac543bbbbed8e9db
-  data.tar.gz: 8c67224a9ae754c411914958e3e9f8a3255bf9af5b09f2d2d2bd11ddffbf72f6
+  metadata.gz: e04ffd3cc7f9e27dc57953e65230cc43d518e3c03413ad1a0f39ef07ac9cde73
+  data.tar.gz: ab9648e703ca1baa1397f07a397dad8a5bac19d4c9773a32c64a82e8ca1e1f92
 SHA512:
-  metadata.gz: 316eab73c6b4ef66752f86515113cf1f881e059c678045b47b63fc04a0dd67265753cd4c9a607db64e47b7629f71b2e107e7b0d62d959f3a1905326af42e5969
-  data.tar.gz: 65725c57b8f2b1f6f97f3b93b799d3a2e57f5f4fae15cb8f0232f7259d3ee9285a37f60fa0b3bf2212b6f5faef77c565863e4158fe9109c49d712e7ecaa29115
+  metadata.gz: f6ed9a0f0486689336f4eccc6d0d7c75eb20038b999399240ddab1015b5c85d8411a4b7aa08e8ba21943998b5f5efcfa67a6b288a149684ffdd95942744df721
+  data.tar.gz: 4713a1d1f9ee0f4ee9e6e74de2dadac6f18b70fb85bb1f0036554a28feb487a35e1c2b01aea9fe3f7927a9beeb532adc1a87f3840a467cc660fe628fd5a98df8

data/CHANGELOG.md

@@ -1,3 +1,38 @@
+## [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).
+- Performance: switch to `Process.clock_gettime(CLOCK_MONOTONIC)` for duration measurement — no `Time` object allocation per job, and immune to wall-clock jumps.
+- Performance: lazy-load parsers, hooks, middleware, and the registry — only Rails boots that have JobTick enabled pay for them.
+- Performance: the monitor map is frozen after sync, and parser allocations are trimmed on the boot path.
+- Add `Configuration#queue_limit` (default 1000) to bound the background ping queue; over-limit pings are dropped non-blockingly rather than back-pressuring the job thread.
+
+### Measured impact
+
+Benchmarked with `spec/benchmarks/monitor_bench.rb` (10,000 iterations, WebMock-stubbed endpoint so the numbers reflect gem-internal overhead, not real network latency):
+
+| Metric (per monitored job) | v0.1.4 | v0.2.0 | Change |
+|---|---:|---:|---:|
+| Job-thread blocking time | 400.6 µs | 2.0 µs | **~200× faster** |
+| Object allocations on job thread | 2,390 | 9 | **~265× fewer** |
+| End-to-end CPU time (incl. background dispatch) | 400.6 µs | 18.1 µs | **~22× less CPU** |
+
+In production, where each ping pays real network RTT, the job-thread speedup is significantly larger: a single 20 ms RTT × 2–3 pings per job is ~50 ms blocking under v0.1.4, versus ~2 µs under v0.2.0 (~25,000× on the worker thread). Run `bundle exec ruby spec/benchmarks/monitor_bench.rb [iterations]` to reproduce.
+
 ## [0.1.4] - 2026-05-05
 
 - Add `prune` configuration option — when enabled, monitors absent from the latest sync payload are permanently deleted, keeping the dashboard in sync with your schedule config

data/README.md

@@ -58,6 +58,38 @@ That's it. On next deploy, JobTick reads your schedule config, registers a monit
 
 No changes to individual job files. No manual monitor creation. No names to keep in sync.
 
+### Environments
+
+**JobTick is only active in production by default.** In `development`, `staging`, or any other environment it silently does nothing — no pings are sent, no monitors are registered, no errors are raised. This means you can deploy the gem and configure it without worrying about local runs polluting your monitors or counting toward your plan.
+
+If you want to enable JobTick in a non-production environment (e.g. to test your setup on staging before going live), opt in explicitly:
+
+```ruby
+# config/initializers/jobtick.rb
+
+# Enable on staging only
+JobTick.configure do |config|
+  config.api_key  = ENV['JOBTICK_API_KEY']
+  config.enabled  = Rails.env.production? || Rails.env.staging?
+end
+```
+
+```ruby
+# Enable everywhere — useful for a quick local smoke-test
+JobTick.configure do |config|
+  config.api_key  = ENV['JOBTICK_API_KEY']
+  config.enabled  = true
+end
+```
+
+```ruby
+# Drive it from an env var so you can toggle without a deploy
+JobTick.configure do |config|
+  config.api_key  = ENV['JOBTICK_API_KEY']
+  config.enabled  = ENV['JOBTICK_ENABLED'] == 'true'
+end
+```
+
 ### Removing stale monitors automatically
 
 By default, monitors are only added — nothing is removed when you delete a job from your schedule. To have each deploy also clean up monitors that are no longer in your config, enable pruning:
@@ -71,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
@@ -90,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**:
@@ -111,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
@@ -131,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

@@ -1,53 +1,34 @@
 # frozen_string_literal: true
 
-require "net/http"
-require "json"
-require "uri"
+require_relative "dispatcher"
 
 module JobTick
   class Client
-    TIMEOUT = 5
+    PING_PREFIX = "/ping/"
+    SYNC_PATH   = "/monitors/sync"
 
     def ping(monitor_key, status:, duration: nil, message: nil)
-      return unless JobTick.config.enabled
-      return if JobTick.config.api_key.nil?
+      return unless JobTick.config.enabled?
 
       payload = { status: status }
       payload[:duration] = duration.round(3) if duration
       payload[:message]  = message           if message
 
-      post("/ping/#{monitor_key}", payload)
+      Dispatcher.enqueue("#{PING_PREFIX}#{monitor_key}", payload)
     end
 
-    def register(monitors, app_name: nil, prune: false)
-      return unless JobTick.config.enabled
-      return if JobTick.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
-      post("/monitors/sync", payload)
-    end
 
-    private
-
-    def post(path, body)
-      uri  = URI("#{JobTick.config.endpoint}#{path}")
-      http = Net::HTTP.new(uri.host, uri.port)
-      http.use_ssl      = uri.scheme == "https"
-      http.open_timeout = TIMEOUT
-      http.read_timeout = TIMEOUT
-
-      request = Net::HTTP::Post.new(uri)
-      request["Content-Type"]  = "application/json"
-      request["Authorization"] = "Bearer #{JobTick.config.api_key}"
-      request["User-Agent"]    = "jobtick-ruby/#{JobTick::VERSION}"
-      request.body             = body.to_json
-
-      http.request(request)
-    rescue StandardError => e
-      JobTick.logger.warn("[JobTick] HTTP request failed (#{path}): #{e.message}")
-      nil
+      if sync
+        Dispatcher.send_sync(SYNC_PATH, payload)
+      else
+        Dispatcher.enqueue(SYNC_PATH, payload)
+      end
     end
   end
 end

data/lib/jobtick/configuration.rb

@@ -2,13 +2,23 @@
 
 module JobTick
   class Configuration
-    attr_accessor :api_key, :endpoint, :environment, :enabled, :prune
+    DEFAULT_QUEUE_LIMIT = 1000
+
+    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
+      @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?
+      @enabled && !@api_key.nil?
     end
   end
 end

data/lib/jobtick/dispatcher.rb

@@ -0,0 +1,305 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+require "openssl"
+
+module JobTick
+  # Asynchronous, single-threaded HTTP dispatcher with a persistent keep-alive
+  # connection. Job threads call .enqueue and return immediately; the dispatcher
+  # daemon thread drains the queue and posts to the JobTick API.
+  #
+  # 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,
+      Errno::EPIPE, Errno::ETIMEDOUT, Errno::EHOSTUNREACH,
+      Net::OpenTimeout, Net::ReadTimeout,
+      OpenSSL::SSL::SSLError, SocketError
+    ].freeze
+
+    class << self
+      attr_accessor :synchronous
+
+      def enqueue(path, payload)
+        return send_request(path, payload) if @synchronous
+
+        guard_fork!
+        ensure_started
+        @queue.push([path, payload], true)
+        nil
+      rescue ThreadError
+        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 && @thread&.alive?
+
+        ack = Queue.new
+        begin
+          @queue.push([FLUSH_SENTINEL, ack])
+        rescue ThreadError
+          return
+        end
+        ack.pop(timeout: timeout)
+        nil
+      end
+
+      def shutdown(timeout: 2)
+        return unless @running
+
+        @running = false
+        @queue&.push(SHUTDOWN_SIGNAL)
+        @thread&.join(timeout)
+        close_http
+        nil
+      end
+
+      def dropped
+        @dropped || 0
+      end
+
+      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
+        @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
+
+        boot_mutex.synchronize do
+          return if @running
+
+          @queue   = SizedQueue.new(queue_limit)
+          @dropped = 0
+          @thread = Thread.new { run_loop }
+          @thread.name = "jobtick-dispatcher" if @thread.respond_to?(:name=)
+          @running = true
+          register_at_exit
+        end
+      end
+
+      def boot_mutex
+        @boot_mutex ||= Mutex.new
+      end
+
+      def http_mutex
+        @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
+
+      def register_at_exit
+        return if @at_exit_registered
+
+        @at_exit_registered = true
+        at_exit { shutdown }
+      end
+
+      def run_loop
+        while (item = @queue.pop)
+          break if item == SHUTDOWN_SIGNAL
+
+          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}")
+      ensure
+        close_http
+      end
+
+      def send_request(path, payload)
+        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
+
+      def http_connection
+        return @http if @http&.started?
+
+        uri = endpoint_uri
+        @http = Net::HTTP.new(uri.host, uri.port)
+        @http.use_ssl            = uri.scheme == "https"
+        @http.open_timeout       = OPEN_TIMEOUT
+        @http.read_timeout       = READ_TIMEOUT
+        @http.keep_alive_timeout = KEEP_ALIVE_TIMEOUT
+        @http.start
+        @http
+      end
+
+      def teardown_http
+        return unless @http
+
+        @http.finish if @http.started?
+      rescue StandardError
+        nil
+      ensure
+        @http = nil
+      end
+
+      def close_http
+        http_mutex.synchronize { teardown_http }
+      end
+
+      def monotonic
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+end

data/lib/jobtick/hooks/active_job.rb

@@ -5,7 +5,7 @@ module JobTick
     module ActiveJob
       def self.included(base)
         base.around_perform do |job, block|
-          key = JobTick.monitor_key_for(job.class.name)
+          key = JobTick.monitor_map[job.class.name]
           next block.call unless key
 
           JobTick::Monitor.run(key) { block.call }

data/lib/jobtick/middleware/sidekiq.rb

@@ -7,7 +7,7 @@ module JobTick
         # Active Job wrappers are handled by the around_perform hook
         return yield if job["wrapped"]
 
-        key = JobTick.monitor_key_for(job["class"])
+        key = JobTick.monitor_map[job["class"]]
         return yield unless key
 
         JobTick::Monitor.run(key, &)

data/lib/jobtick/monitor.rb

@@ -2,14 +2,18 @@
 
 module JobTick
   class Monitor
+    MONOTONIC = Process::CLOCK_MONOTONIC
+
     def self.run(key)
-      return yield unless JobTick.config.enabled
+      config = JobTick.config
+      return yield unless config.enabled?
 
-      started_at = Time.now
-      JobTick.client.ping(key, status: :started)
-      result   = yield
-      duration = Time.now - started_at
-      JobTick.client.ping(key, status: :completed, duration: duration)
+      client = JobTick.client
+      client.ping(key, status: :started) if config.ping_started
+      started = Process.clock_gettime(MONOTONIC)
+      result  = yield
+      duration = Process.clock_gettime(MONOTONIC) - started
+      client.ping(key, status: :completed, duration: duration)
       result
     rescue StandardError => e
       JobTick.client.ping(key, status: :failed, message: e.message)

data/lib/jobtick/parsers/sidekiq.rb

@@ -1,11 +1,9 @@
 # frozen_string_literal: true
 
+require_relative "../parsers"
+
 module JobTick
   module Parsers
-    def self.slugify(str)
-      str.downcase.gsub(/[^a-z0-9]+/, "_").gsub(/\A_+|_+\z/, "")
-    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.map do |key, config|
-          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?
 
-          {
-            key: "solid_queue.#{key}",
-            schedule: config["schedule"],
-            source: "solid_queue",
-            task: config["class"]
-          }
-        end.compact
+        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,11 +2,25 @@
 
 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
 
-        JobTick::Registry.sync
+        require_relative "parsers/whenever"
+        require_relative "parsers/solid_queue"
+        require_relative "parsers/sidekiq"
+        require_relative "registry"
+        require_relative "hooks/active_job"
+        require_relative "middleware/sidekiq"
+
+        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)
@@ -16,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
 
-      JobTick.monitor_map = monitors.each_with_object({}) do |m, map|
-        map[m[:task]] = m[:key] if m[:task]
-      end
+      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.1.4"
+  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,15 +5,12 @@ require_relative "jobtick/version"
 require_relative "jobtick/configuration"
 require_relative "jobtick/client"
 require_relative "jobtick/monitor"
-require_relative "jobtick/parsers/whenever"
-require_relative "jobtick/parsers/solid_queue"
-require_relative "jobtick/parsers/sidekiq"
-require_relative "jobtick/registry"
-require_relative "jobtick/hooks/active_job"
-require_relative "jobtick/middleware/sidekiq"
+require_relative "jobtick/parsers"
 require_relative "jobtick/railtie" if defined?(Rails::Railtie)
 
 module JobTick
+  EMPTY_MAP = {}.freeze
+
   class Error < StandardError; end
 
   class << self
@@ -29,12 +26,24 @@ 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
-      @monitor_map ||= {}
+      @monitor_map ||= EMPTY_MAP
     end
 
     attr_writer :monitor_map
@@ -44,9 +53,10 @@ module JobTick
     end
 
     def reset!
+      Dispatcher.reset! if defined?(Dispatcher)
       @config = nil
       @client = nil
-      @monitor_map = {}
+      @monitor_map = EMPTY_MAP
     end
   end
 end

data/lib/tasks/jobtick.rake

@@ -3,6 +3,11 @@
 namespace :jobtick do
   desc "Sync discovered jobs with jobtick.app"
   task sync: :environment do
+    require "jobtick/parsers/whenever"
+    require "jobtick/parsers/solid_queue"
+    require "jobtick/parsers/sidekiq"
+    require "jobtick/registry"
+
     monitors = JobTick::Registry.sync
     count    = monitors&.length || 0
     puts "[JobTick] Synced #{count} monitor(s)"

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.1.4
+  version: 0.3.0
 platform: ruby
 authors:
 - Clearstack Labs
@@ -38,9 +38,11 @@ files:
 - lib/jobtick.rb
 - lib/jobtick/client.rb
 - lib/jobtick/configuration.rb
+- lib/jobtick/dispatcher.rb
 - 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