Background jobs
Report each cron tick, queue message, or background task as a Job Run with its own trace. Complete the Node.js quickstart before running these examples.
Monitor a job
Wrap one execution of a job, such as a cron tick, a queue message, or one loop iteration, with withJobMonitor. Each execution is reported as a Job Run with its own trace, even when the job is triggered from inside a web request. Database queries and outgoing calls made inside the job belong to that run.
Pass the job's name and the function to run. This example uses node-cron:
import { withJobMonitor } from "@vigilon/node";
import cron from "node-cron";
cron.schedule("0 3 * * *", () =>
withJobMonitor({ name: "sync-users", schedule: "0 3 * * *" }, async () => {
await syncUsers();
}),
);
The same wrapper works for plain intervals. Queue workers such as BullMQ are covered in the next section.
import { withJobMonitor } from "@vigilon/node";
setInterval(
() => withJobMonitor({ name: "refresh-cache" }, () => refreshCache()),
60_000,
);
BullMQ workers
To monitor BullMQ, wrap the worker's processor in withJobMonitor. Every job the worker picks up is reported as a Job Run with its own trace, and a job that throws is recorded as a failed run with its exception.
import { withJobMonitor } from "@vigilon/node";
import { Queue, Worker } from "bullmq";
const connection = { host: "localhost", port: 6379 };
new Worker(
"emails",
(bullJob) =>
withJobMonitor({ name: "send-email" }, () => sendEmail(bullJob.data)),
{ connection },
);
// Each attempt is reported as its own Job Run
await new Queue("emails", { connection }).add(
"welcome",
{ userId: "42" },
{ attempts: 3, backoff: { type: "exponential", delay: 1000 } },
);
The error is thrown again after it is recorded, so BullMQ still sees the failure and applies attempts and backoff as usual. Each attempt is its own Job Run: a job added with attempts: 3 that fails twice and then succeeds shows two failed runs and one successful run on the Jobs page.
Name the run after the kind of work, not the item. When one worker handles several job types, bullJob.name (the name passed to queue.add) works as the run name. bullJob.id does not: every job would become a new job in Vigilon.
BullMQ talks to Redis through ioredis, which Vigilon instruments. Redis commands made inside the processor appear as spans in the run's trace, next to database queries and outgoing calls. The worker's own polling between jobs happens outside any run and does not create traces.
The run's trace starts in the worker. It is not joined to the web request that added the job, so the request and the job run appear as separate traces.
For repeatable jobs created with upsertJobScheduler, pass the same cron pattern as schedule to turn on missed-run detection. Vigilon reads the pattern in UTC.
import { withJobMonitor } from "@vigilon/node";
import { Queue, Worker } from "bullmq";
const connection = { host: "localhost", port: 6379 };
await new Queue("reports", { connection }).upsertJobScheduler(
"nightly-report",
{ pattern: "0 3 * * *" },
);
new Worker(
"reports",
() =>
withJobMonitor({ name: "nightly-report", schedule: "0 3 * * *" }, () =>
buildNightlyReport(),
),
{ connection },
);
Name and schedule
name is required and should stay the same across runs. Use sync-users, not a different name such as sync-user-42 for every item. A new name creates a new job in Vigilon, so per-item names never build up a history of runs.
schedule is an optional cron expression that turns on missed-run detection, described below. It describes when your scheduler is expected to run the job; it does not schedule or execute anything. Keep using your cron service, queue, or task scheduler.
Detect missed runs
Give a job a schedule and Vigilon marks it Overdue on the Jobs page when it stops running. A job is Overdue once the schedule has expected two runs since its last completed run and neither arrived, so a run that starts a little late is not flagged.
Vigilon reads the cron expression in UTC. With 0 3 * * *, a job last completed at 03:00 UTC on Monday is expected again on Tuesday and becomes Overdue at 03:00 UTC on Wednesday if no run has completed by then.
Overdue detection is off, and the job's status reflects its last run only, when no run carried a schedule, when the schedule is not a cron expression Vigilon can read, or when the schedule runs less often than once every seven days.
A job whose last run failed shows as Failing instead of Overdue. A run that is still in progress has not completed yet, so a very long run looks the same as a job that has stopped.
Return values and errors
Sync and async functions both work. The return value, or promise, passes through unchanged. Errors that leave the job are recorded on the run and thrown again, so your retry logic still works. If you catch an error inside the job, call recordException(error) yourself.
Vigilon has to be running before a job executes. With the --import flag from the quickstart, it always is. A job that runs before startup still does its work, but Vigilon does not receive a Job Run for it.
Scripts that exit
Vigilon sends data in small batches in the background. A script that finishes right after its job, such as a one-off task or a scheduled container, can exit before the last batch is sent. Await shutdown() before the process exits:
import { shutdown, withJobMonitor } from "@vigilon/node";
try {
await withJobMonitor({ name: "sync-users", schedule: "0 3 * * *" }, () =>
syncUsers(),
);
} finally {
await shutdown();
}
shutdown() never throws, so a problem sending data cannot crash your script or hide the result of the job. Call it once, when all the work is done, and await it before calling process.exit(). Long-running servers do not need it, and AWS Lambda is handled automatically.