Docs › BullMQ repeatable job monitoring with RunVouch

BullMQ repeatable job monitoring with RunVouch

BullMQ repeatable job monitoring for the queue that fills up quietly: queue.upsertJobScheduler("nightly", { pattern: "0 2 * * *" }) puts a delayed job in Redis; a Worker picks it up. With the Worker down, jobs move from delayed to waiting and stay there, and every scheduled tick adds one more.

How it runs on BullMQ job schedulers

Inside the Worker's processor function with the Node client, so the run starts when the job is actually picked up, not when it was scheduled. For long jobs call run.heartbeat() next to job.updateProgress().

Store the key

RUNVOUCH_KEY in the Worker process environment; the producer that upserts the scheduler does not need it.

Wrap the job

// producer (once, idempotent): BullMQ 5.16+ job schedulers; older: queue.add(name, data, { repeat: { pattern } })
const { Queue, Worker } = require("bullmq");
const rv = require("./runvouch");
const connection = { host: "redis", port: 6379 };
const queue = new Queue("reports", { connection });
await queue.upsertJobScheduler("nightly-report", { pattern: "0 2 * * *", tz: "UTC" }, { name: "nightly-report" });

// worker
new Worker("reports", async (job) =>
  rv.vouch("nightly-report", async (run) => {
    const rows = await buildReport(job.data);
    await run.heartbeat();                  // long jobs: keeps STALLED honest
    return rows;
  }, { source: "bullmq", evidence: (rows) => ({ rows_written: rows > 0 }) }),
  { connection, concurrency: 1, lockDuration: 600000 });

// rv agent nightly-report --cadence 24h --grace 30m --max-runtime 1h --evidence

rv fails open: if RunVouch is unreachable the job still runs and you get one warning line.

Register the cadence and caps

rv agent nightly-report --cadence 24h --grace 30m --max-runtime 1h --evidence --cap-run-cost 2

Register the agent once, from anywhere with the key. Cadence is what turns a schedule that stopped into an alert; --evidence makes a run without evidence a failure; the caps pause the agent when it overspends.

What goes silent on BullMQ job schedulers

• No Worker means the scheduled job sits in the waiting list with no error; MISSED after cadence plus grace is the signal. queue.getJobCounts() would show it, if something polled it.
• A job whose lock expires (lockDuration, default 30 s) while the processor is still running is marked stalled by BullMQ and retried up to maxStalledCount; each retry is another run under the same agent.
• Redis with an eviction policy other than noeviction can drop the scheduler key itself; the docs require noeviction, and MISSED is what tells you it was ignored.
• A processor that returns without throwing is completed; an empty result is completed too.

What BullMQ job schedulers does not tell you

BullMQ moves a failed job to the failed set and emits failed and stalled events on a QueueEvents instance, if a process is listening. It has no notification, no notion of a job that should have been added but was not (a lost scheduler, a producer that never ran), and no record of a completed job's usefulness. Taskforce.sh and Bull Board show the counts; someone has to look.

What RunVouch detects

Set up in two minutes

1. Get a free key (3 agents, no card) and store it where this page says.
2. wrap the job: copy the snippet above into the scheduled job.
3. Register the cadence once: rv agent nightly-report --cadence 24h --grace 30m --evidence, or let the first run create the agent and set the cadence on the dashboard.
4. Send one test alert: curl -X POST https://api.runvouch.com/v1/settings/test-alert -H "X-API-Key: $RUNVOUCH_KEY". The next missed, failed or empty run reaches the same channels.

Need a key? Get a free key · Stuck? contact