Set Up Crons
Sentry Crons allows you to monitor the uptime and performance of any scheduled, recurring job. Once implemented, it'll allow you to get alerts and metrics to help you solve errors, detect timeouts, and prevent disruptions to your service.
- Use our getting started guide to install and configure the Sentry SDK (version
7.51.1
or newer) for your recurring job. - Create and configure your first Monitor.
Cron monitoring is only supported in SvelteKit server-side
If you're using the cron
, node-cron
or node-schedule
libraries to run your periodic tasks, you can use our instrumentation functions in the Sentry.cron
export to monitor your cron jobs.
Requires SDK version 7.92.0
or higher.
Use Sentry.cron.instrumentCron
to instrument the CronJob
constructor or CronJob.from
method in the cron
library. Pass the name of the cron monitor as a second argument to the function.
import { CronJob } from "cron";
const CronJobWithCheckIn = Sentry.cron.instrumentCron(CronJob, "my-cron-job");
// use the constructor
const job = new CronJobWithCheckIn("* * * * *", () => {
console.log("You will see this message every minute");
});
// or from method
const job = CronJobWithCheckIn.from({
cronTime: "* * * * *",
onTick: () => {
console.log("You will see this message every minute");
},
});
Requires SDK version 7.92.0
or higher.
Use Sentry.cron.instrumentNodeCron
to instrument the cron
export from the node-cron
library. This returns an object with the same API as the original cron
export, but with the schedule
method instrumented. You can pass the name of the cron monitor and an optional time zone as part of the third options argument to the function.
import cron from "node-cron";
const cronWithCheckIn = Sentry.cron.instrumentNodeCron(cron);
cronWithCheckIn.schedule(
"* * * * *",
() => {
console.log("running a task every minute");
},
{ name: "my-cron-job" }
);
Requires SDK version 7.93.0
or higher.
Use Sentry.cron.instrumentNodeSchedule
to instrument the schedule
export from the node-schedule
library. This returns an object with the same API as the original schedule
export, but with the scheduleJob
method instrumented. You can pass the name of the cron job as the first argument to the function. Currently this only supports cronstring as the second argument to scheduleJob
.
import * as schedule from "node-schedule";
const scheduleWithCheckIn = Sentry.cron.instrumentNodeSchedule(schedule);
scheduleWithCheckIn.scheduleJob(
"my-cron-job",
"* * * * *",
() => {
console.log("running a task every minute");
}
);
Use the Sentry.withMonitor()
API to monitor a callback and notify you if your periodic task is missed (or doesn't start when expected), if it fails due to a problem in the runtime (such as an error), or if it fails by exceeding its maximum runtime.
Sentry.withMonitor()
requires SDK version 7.76.0
.
Sentry.withMonitor("<monitor-slug>", () => {
// Execute your scheduled task here...
});
If you are using an SDK version prior to 7.76.0
, you can use the Sentry.captureCheckIn()
API documented below.
Check-in monitoring allows you to track a job's progress by completing two check-ins: one at the start of your job and another at the end of your job. This two-step process allows Sentry to notify you if your job didn't start when expected (missed) or if it exceeded its maximum runtime (failed).
// 🟡 Notify Sentry your job is running:
const checkInId = Sentry.captureCheckIn({
monitorSlug: "<monitor-slug>",
status: "in_progress",
});
// Execute your scheduled task here...
// 🟢 Notify Sentry your job has completed successfully:
Sentry.captureCheckIn({
// Make sure this variable is named `checkInId`
checkInId,
monitorSlug: "<monitor-slug>",
status: "ok",
});
If your job execution fails, you can notify Sentry about the failure:
// 🔴 Notify Sentry your job has failed:
Sentry.captureCheckIn({
// Make sure this variable is named `checkInId`
checkInId,
monitorSlug: "<monitor-slug>",
status: "error",
});
Heartbeat monitoring notifies Sentry of a job's status through one check-in. This setup will only notify you if your job didn't start when expected (missed). If you need to track a job to see if it exceeded its maximum runtime (failed), use check-ins instead.
// Execute your scheduled task...
// 🟢 Notify Sentry your job completed successfully:
Sentry.captureCheckIn({
monitorSlug: "<monitor-slug>",
status: "ok",
});
If your job execution fails, you can:
// 🔴 Notify Sentry your job has failed:
Sentry.captureCheckIn({
monitorSlug: "<monitor-slug>",
status: "error",
});
You can create and update your Monitors programmatically with code rather than creating and configuring them in Sentry.io.
To create/update a monitor, use Sentry.withMonitor()
and pass in your monitor configuration as a third parameter:
const monitorConfig = {
schedule: {
type: "crontab",
value: "* * * * *",
},
checkinMargin: 2, // In minutes. Optional.
maxRuntime: 10, // In minutes. Optional.
timezone: "America/Los_Angeles", // Optional.
};
Sentry.withMonitor(
"<monitor-slug>",
() => {
// Execute your scheduled task here...
},
monitorConfig
);
To configure the monitor's check-ins, use Sentry.captureCheckIn()
and pass in your monitor configuration as a second parameter:
const monitorConfig = {
schedule: {
type: "crontab",
value: "* * * * *",
},
checkinMargin: 2, // In minutes. Optional.
maxRuntime: 10, // In minutes. Optional.
timezone: "America/Los_Angeles", // Optional.
};
// 🟡 Notify Sentry your job is running:
const checkInId = Sentry.captureCheckIn(
{
monitorSlug: "<monitor-slug>",
status: "in_progress",
},
monitorConfig
);
// Execute your scheduled task here...
// 🟢 Notify Sentry your job has completed successfully:
Sentry.captureCheckIn(
{
// Make sure this variable is named `checkInId`
checkInId,
monitorSlug: "<monitor-slug>",
status: "ok",
},
monitorConfig
);
The following are available monitor configuration properties:
schedule
:
The job's schedule:
The schedule representation for your monitor, either crontab
or interval
. The structure will vary depending on the type:
{"type": "crontab", "value": "0 * * * *"}
{"type": "interval", "value": "2", "unit": "hour"}
checkinMargin
:
The amount of time (in minutes) Sentry should wait for your check-in before it's considered missed ("grace period"). Optional.
We recommend that your check-in margin be less than or equal to your interval.
maxRuntime
:
The amount of time (in minutes) your job is allowed to run before it's considered failed. Optional.
timezone
:
The tz
where your job is running. This is usually your server's timezone, (such as America/Los_Angeles
). See list of tz database time zones. Optional.
When your recurring job fails to check in (missed), runs beyond its configured maximum runtime (failed), or manually reports a failure, Sentry will create an error event with a tag to your monitor.
To receive alerts about these events:
- Navigate to Alerts in the sidebar.
- Create a new alert and select "Issues" under "Errors" as the alert type.
- Configure your alert and define a filter match to use:
The event's tags match {key} {match} {value}
.
Example: The event's tags match monitor.slug equals my-monitor-slug-here
Learn more in Issue Alert Configuration.
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").