Monitoring sidekiq-cron and sidekiq-scheduler: Loading, Gaps, Alerts
Contents
sidekiq-cron and sidekiq-scheduler both keep the schedule in Redis and enqueue jobs from inside running Sidekiq processes, so a job runs only if its entry is in Redis, is enabled, and a Sidekiq process with the scheduler on is alive at the due time. Most "the cron job stopped" incidents come from the first condition: a schedule file change, a missing file, or a dynamic job nobody remembers creating. Neither gem tells anyone when a run doesn't happen, so add a check-in from each job that an outside service expects on schedule.
This guide covers sidekiq-cron 2.4.0 and sidekiq-scheduler 6.0.2 with Sidekiq 8, checked November 16, 2026. For Sidekiq queues, retries, and dead jobs in general, see Sidekiq monitoring; for Rails 8's built-in recurring tasks, see Rails scheduled jobs. CronRadar has no Ruby SDK and no Sidekiq integration, so the check-ins below are plain HTTP with Ruby's standard library.
How sidekiq-cron Loads Jobs#
sidekiq-cron stores each cron job as a hash in Redis. Jobs get there two ways (README):
- The schedule file. On Sidekiq server startup, the gem reads
config/schedule.yml(ERB allowed; change the path withcron_schedule_file, or set it tonilto turn loading off) and loads it withSidekiq::Cron::Job.load_from_hash!orload_from_array!, marking each job's source asschedule(schedule_loader.rb). - Code.
Sidekiq::Cron::Job.create(...),Job.new(...).save, or the non-bangload_from_hash/load_from_array, from an initializer, a console, or application code. These jobs aredynamic.
The bang and non-bang loaders differ in one way that matters:
| Method | Creates and updates listed jobs | Removes jobs not in the list |
|---|---|---|
load_from_hash / load_from_array |
Yes | No |
load_from_hash! / load_from_array! |
Yes | Yes, but only jobs whose source is schedule |
A minimal schedule file:
# config/schedule.yml
nightly_report:
cron: '0 2 * * *'
class: 'NightlyReportJob'
queue: 'default'
hourly_sync:
cron: '15 * * * * America/Chicago'
class: 'InventorySyncJob'Why Jobs Vanish, or Linger, After a Schedule Change#
Because the file is loaded with the bang loader at startup, the file is authoritative for schedule-source jobs:
- Renaming a key removes the old job and creates a new one.
nightly_reportrenamed toreports_nightlyis a different job; the old entry is destroyed and its history goes with it. - Deleting an entry deletes the job the next time a Sidekiq process starts.
- A missing file changes nothing. The loader skips loading when the file doesn't exist, so a container image built without
config/schedule.ymlkeeps whatever is already in Redis. The schedule then silently stops tracking your code. - Dynamic jobs are never pruned. A job created from a console or initializer stays until someone calls
Sidekiq::Cron::Job.destroy("name"). The loader treats any job not saved with sourcescheduleas dynamic, so jobs created another way, including ones saved before the gem tracked sources, linger too. - Rolling deploys load twice. Each Sidekiq process loads the file when it starts. While old and new versions overlap, an old process that restarts loads the old file and undoes the new one until a new process starts again.
Disabled jobs are the other quiet state. A job with status: "disabled" in its hash, or one disabled from the Web UI or with disable!, stays in Redis and never enqueues. Reloading the file doesn't change a job's status unless the entry sets status explicitly, so a job someone disabled in the UI stays disabled across deploys.
Namespaces add one more way to look in the wrong place. Sidekiq::Cron::Job.all returns the default namespace only; pass "*" to see everything.
List What's in Redis#
Run this in a Rails console or a rake task in each environment and compare it with the file:
require "yaml"
require "erb"
file_jobs = YAML.safe_load(ERB.new(File.read("config/schedule.yml")).result).keys
Sidekiq::Cron::Job.all("*").sort_by(&:name).each do |job|
in_file = file_jobs.include?(job.name) ? "file" : "NOT IN FILE"
puts [job.name, job.cron, job.status, job.source, in_file, job.last_enqueue_time].join(" | ")
end
missing = file_jobs - Sidekiq::Cron::Job.all("*").map(&:name)
puts "In file but not in Redis: #{missing.join(', ')}" if missing.any?Jobs marked disabled, dynamic jobs you didn't expect, and file entries missing from Redis are the three things to look for.
The Poller and What It Needs#
Loading puts jobs in Redis; the poller enqueues them. Every Sidekiq process with sidekiq-cron enabled polls every cron_poll_interval seconds (30 by default) and pushes jobs that are due. Several processes don't produce duplicates: the README says a Redis sorted set ensures only the first process to ask enqueues a given run.
Two consequences:
- No Sidekiq process, no runs. Jobs are added only while at least one Sidekiq process is running. A worker fleet scaled to zero, crash-looping, or mid-deploy enqueues nothing.
- Short gaps are caught up, long ones aren't. After downtime the gem enqueues runs it missed, but by default only those due less than
reschedule_grace_period(60 seconds) earlier. Raise it if deploys take longer than that and a missed run should still happen.
Seconds are supported with a six-field expression (*/30 * * * * *), and the poll interval must then be shorter than the job's interval.
Time Zones in sidekiq-cron#
A cron string is evaluated in the Rails time zone (config.time_zone) in a Rails app, and in UTC otherwise. Append an IANA zone to override it per job, as in 15 * * * * America/Chicago. In a Rails app with config.time_zone = "Eastern Time (US & Canada)", 0 2 * * * means 02:00 New York time, not UTC, which surprises people who copied the expression from a server crontab.
sidekiq-scheduler Works Differently#
sidekiq-scheduler uses rufus-scheduler inside each Sidekiq process and reads the schedule from Sidekiq's config (README):
# config/sidekiq.yml
:scheduler:
:schedule:
nightly_report:
cron: '0 2 * * *'
class: NightlyReportJob
inventory_sync:
every: '15m'
class: InventorySyncJob
enabled: falseWhat differs from sidekiq-cron:
- Schedule types.
cron,every, andintervalrepeat;atandinrun once.everyandintervalcount from process start, so a restart resets them. - Duplicates.
cronandatjobs are pushed once across instances, but the README notes duplicates can still happen under high CPU load, many jobs firing at once, or slow Redis.every,interval, andinjobs are pushed once per host. It recommends a single scheduler process, with:enabled: falseunder:scheduler:on the others. - The stored schedule. The schedule is written to Redis on boot and drives the Web UI; with several processes, the last one to boot decides what's stored. A process running an older config can overwrite it.
- Dynamic schedules. With
:dynamic: true,Sidekiq.set_schedule(name, {...})adds or updates entries at run time and processes reload every 5 seconds (:dynamic_every). Without it, changes needSidekiqScheduler::Scheduler.instance.reload_schedule!.Sidekiq.get_schedulereturns what's loaded. - Missed runs. If no Sidekiq process with the scheduler is running at the trigger time, the job isn't enqueued and isn't caught up later.
- Time zones. Cron uses the server's time zone outside Rails and
config.time_zonein Rails (rufus-scheduler 3.3.3 or later). An appended zone must be a full IANA name, such asEurope/Stockholm.
Add a Check-In to Each Scheduled Job#
Every failure above has the same symptom: the job didn't run and nothing said so. The Sidekiq Web UI shows what's in Redis and what failed, not what should have happened and didn't. A per-job check-in fixes that: the job reports when it starts and finishes, and CronRadar alerts when an expected report doesn't arrive.
This helper uses only Ruby's standard library. It follows the ingestion API: a POST to /start, then /complete or /fail, with the API key as the Basic auth username and an empty password. Every request has a five-second timeout, every error is caught, and the job's own exception is re-raised:
# app/lib/cron_checkin.rb
require "net/http"
require "uri"
module CronCheckin
BASE_URL = "https://cron.life/api/v1/ping"
# Wraps a scheduled job's work. Monitoring never changes the job's result.
def self.track(key, schedule:, run_id:)
report(key, "start", schedule: schedule, run_id: run_id)
result = yield
report(key, "complete", run_id: run_id)
result
rescue StandardError => error
# The exception class only: never arguments, payloads, or log output.
report(key, "fail", run_id: run_id, message: error.class.name)
raise
end
def self.report(key, event, params)
api_key = ENV["CRONRADAR_API_KEY"]
return if api_key.nil? || api_key.empty?
uri = URI("#{BASE_URL}/#{URI.encode_www_form_component(key)}/#{event}")
uri.query = URI.encode_www_form(params.compact)
request = Net::HTTP::Post.new(uri)
request.basic_auth(api_key, "")
request["Content-Type"] = "text/plain"
request.body = ""
Net::HTTP.start(uri.host, uri.port, use_ssl: true,
open_timeout: 5, read_timeout: 5, write_timeout: 5) do |http|
http.request(request)
end
rescue StandardError => error
warn "CronRadar #{event} for #{key} not recorded (#{error.class})"
end
endUse it inside perform. Sidekiq keeps a job's jid across retries, which makes it the right run_id: retry attempts of one scheduled run pair with each other, and separate runs don't:
# app/jobs/nightly_report_job.rb
class NightlyReportJob
include Sidekiq::Job
sidekiq_options retry: 3
SCHEDULE = "0 2 * * *" # Same as config/schedule.yml, without any zone suffix.
def perform
CronCheckin.track("nightly-report", schedule: SCHEDULE, run_id: jid) do
ReportBuilder.run
end
end
endSet CRONRADAR_API_KEY in the Sidekiq processes' environment. The first start creates the nightly-report monitor from schedule, and because every start carries it, a deleted monitor re-creates itself. Use lowercase letters, digits, and hyphens in keys, at most 100 characters.
Match the Schedule and Time Zone#
CronRadar evaluates the five-field schedule in the application's time zone, an IANA name set in the application's settings (UTC if unset). Set it to match what the gem uses:
| Gem and setup | Gem evaluates cron in | CronRadar application time zone |
|---|---|---|
| sidekiq-cron, no Rails | UTC | UTC (leave unset) |
| sidekiq-cron or sidekiq-scheduler with Rails | config.time_zone |
The same zone as an IANA name |
| sidekiq-scheduler, no Rails | The server's zone | The server's zone |
| Either, with a zone suffix on the job | That zone | A separate application in that zone |
Send the expression without the zone suffix. Six-field expressions with seconds have no five-field form, and every/interval jobs count from process start, so neither can be expected at a fixed time; give those a cron schedule if you want missed-run alerts.
What You'll Be Told#
- Missed: no
startby the expected time plus the grace period sends the monitor fromwarningtocriticaland alerts by email, Slack, webhook, Discord, or PagerDuty. That covers a job pruned from Redis, a disabled job, a missing schedule file, a stopped fleet, and a run lost during a deploy. - Failed: an exception reports
failand alerts immediately. With Sidekiq retries, each failed attempt reports, under the samerun_id. - Stuck: a
startwith no finish is flagged as stuck. That includes a run interrupted by shutdown: Sidekiq raisesSidekiq::Shutdown, which isn't aStandardError, so the helper doesn't report it as a failure, and Sidekiq pushes the job back to run again. - Twice: two runs are both recorded; CronRadar doesn't alert on an extra run. Cron job running twice covers finding the cause.
One gap is yours to close: a job that's removed from Redis and never ran under its key creates no monitor, so nothing is expected. Once a job has reported, its monitor stays and keeps expecting runs, which is exactly what catches a later removal. For a brand-new job, trigger it once after deploying, or check that its monitor appeared. Use a separate CronRadar application and key per environment, and see pricing for monitor counts.
Frequently Asked Questions#
Why did my sidekiq-cron job disappear?#
Jobs loaded from config/schedule.yml are reloaded with load_from_hash! when each Sidekiq process starts, which deletes schedule-source jobs no longer in the file. A renamed key, a deleted entry, or an old process restarting with an older file during a deploy all remove jobs. Dynamic jobs created in code aren't affected.
What is the difference between load_from_hash and load_from_hash! in sidekiq-cron?#
Both create and update the jobs in the hash. load_from_hash! also removes jobs with source schedule that aren't in the hash, so it's the one to use when a file is the source of truth. Pass the same namespace option to both creation and pruning if you use namespaces.
What time zone does sidekiq-cron use?#
The Rails time zone in a Rails app, and UTC otherwise. Append an IANA zone to the cron string, such as 0 22 * * 1-5 America/Chicago, to set it per job.
Does sidekiq-cron run jobs missed during downtime?#
Only recent ones. After downtime it enqueues missed runs that were due less than reschedule_grace_period earlier, 60 seconds by default. Raise that setting if deploys or restarts take longer and those runs should still happen. sidekiq-scheduler doesn't catch up missed runs.
Is there a CronRadar Ruby SDK or Sidekiq integration?#
No. Ruby jobs report over HTTP, as in the CronCheckin helper above, with one monitor key and schedule per scheduled job. The helper uses only the standard library, has a five-second timeout, never raises into the job, and re-raises the job's own errors.
Put this guide to work
Know when the next run is missing
Connect one scheduled job, confirm a real completion, then verify the alert destination. Keep your existing scheduler in charge of running the work.