Docs › node-cron monitoring with RunVouch
node-cron monitoring with RunVouch
node-cron monitoring from outside the process: cron.schedule("0 2 * * *", fn) is a timer in your Node process. A crash at 01:59, a deploy that restarted the pod at 02:00, or a scale-to-zero platform, and the job simply does not run; no exception, no log line.
How it runs on node-cron
Inside the scheduled callback with the Node client (rv.vouch reports start, end, status from a thrown error, and evidence from your callback). The agent's cadence is what makes the missing process visible.
Store the key
RUNVOUCH_KEY in the process environment (.env via dotenv, or the platform's variables).
Wrap the job
// npm install node-cron ; curl -O https://runvouch.com/runvouch.js
const cron = require("node-cron");
const rv = require("./runvouch");
const { buildReport } = require("./report");
// once, at boot: cadence and caps (idempotent)
rv.agent("nightly-report", { cadence_s: 86400, grace_s: 1800, evidence_required: true, cap_run_cost: 2 });
cron.schedule("0 2 * * *", () =>
rv.vouch("nightly-report", async (run) => {
const rows = await buildReport(); // your work
await run.tool("openai.chat", { rows }, { cost: 0.04 });
return rows;
}, { source: "node-cron", evidence: (rows) => ({ rows_written: rows > 0 }) })
.catch((e) => console.error("nightly-report failed:", e)), // rv already reported status: fail
{ timezone: "UTC" });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 node-cron
- A rejected promise inside the callback is an unhandled rejection: on Node 15 and later it crashes the process unless caught, which takes every other schedule down with it. The
.catchabove keeps the process alive; the FAILED alert has the message. - node-cron has no persistence and no catch-up: a tick that falls while the process is down is gone.
- Two replicas of the service run the job twice; both runs show under one agent and the daily cap counts both.
- A callback that runs past the next tick overlaps itself; STALLED (max runtime) catches the slow one.
What node-cron does not tell you
node-cron validates the expression and calls your function; it keeps no run history, has no error channel of its own, and does not know a tick was skipped because the process was not running. Whatever you console.log goes to the process stdout, which on most platforms is kept for days and read by nobody until something else breaks.
What RunVouch detects
| Alert | What it means here |
|---|---|
| MISSED | cadence plus grace passed and no run started |
| FAILED | non-zero exit or a reported failure, with the stderr excerpt |
| NO_EVIDENCE | the run said ok but the file, URL or assertion you required is missing |
| STALLED | a run started and never ended within max runtime |
| RETRY_STORM | the same tool called with identical input many times in one run |
| BUDGET_RUN / BUDGET_DAY | cost cap crossed; the agent is paused until you resume it |
| DRIFT | duration or output size far off its 7-run baseline |
Set up in two minutes
- Get a free key (3 agents, no card) and store it where this page says.
- wrap the job: copy the snippet above into the scheduled job.
- 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. - 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