# Set Up Crons | Sentry for Next.js
Once implemented, it'll allow you to get alerts and metrics to help you solve errors, detect timeouts, and prevent disruptions to your service.
## [Requirements](https://docs.sentry.io/platforms/javascript/guides/nextjs/crons.md#requirements)
* Use our [getting started](https://docs.sentry.io/platforms/javascript/guides/nextjs.md) guide to install and configure the Sentry SDK (version `7.51.1` or newer) for your recurring job.
* [Create and configure](https://sentry.io/issues/alerts/new/crons/) your first Monitor.
Cron monitoring is only supported in Server and Edge runtimes for Next.js
## [Automatic Check-Ins (Vercel Only)](https://docs.sentry.io/platforms/javascript/guides/nextjs/crons.md#automatic-check-ins-vercel-only)
If you are hosting your Next.js application on Vercel and you are using [Vercel's Cron Jobs feature](https://vercel.com/docs/cron-jobs), you can configure the Next.js SDK to automatically create Check-Ins for you. Instrumented cron jobs are decided at runtime by examining the `crons` field in your `vercel.json` file.
Set the `automaticVercelMonitors` option to `true` in your Sentry settings in `next.config.js`. See [Manual Setup](https://docs.sentry.io/platforms/javascript/guides/nextjs/manual-setup.md#opt-out-of-auto-instrumentation-of-vercel-cron-jobs) for more details.
Automatic instrumentation of Vercel cron jobs currently only works for the Pages Router. App Router route handlers are not yet supported.
## [Automatic Crons Instrumentation](https://docs.sentry.io/platforms/javascript/guides/nextjs/crons.md#automatic-crons-instrumentation)
If you're using the [`cron`](https://www.npmjs.com/package/cron), [`node-cron`](https://www.npmjs.com/package/node-cron) or [`node-schedule`](https://www.npmjs.com/package/node-schedule) libraries to run your periodic tasks, you can use our instrumentation functions in the `Sentry.cron` export to monitor your cron jobs.
### [Cron](https://docs.sentry.io/platforms/javascript/guides/nextjs/crons.md#cron)
Requires SDK version `7.92.0` or higher.
Use `Sentry.cron.instrumentCron` to instrument the `CronJob` constructor or `CronJob.from` method in the [`cron`](https://www.npmjs.com/package/cron) library. Pass the name of the cron monitor as a second argument to the function.
```JavaScript
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");
},
});
```
### [Node Cron](https://docs.sentry.io/platforms/javascript/guides/nextjs/crons.md#node-cron)
Requires SDK version `7.92.0` or higher.
Use `Sentry.cron.instrumentNodeCron` to instrument the `cron` export from the [`node-cron`](https://www.npmjs.com/package/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.
```JavaScript
import cron from "node-cron";
const cronWithCheckIn = Sentry.cron.instrumentNodeCron(cron);
cronWithCheckIn.schedule(
"* * * * *",
() => {
console.log("running a task every minute");
},
{ name: "my-cron-job" }
);
```
### [Node Schedule](https://docs.sentry.io/platforms/javascript/guides/nextjs/crons.md#node-schedule)
Requires SDK version `7.93.0` or higher.
Use `Sentry.cron.instrumentNodeSchedule` to instrument the `schedule` export from the [`node-schedule`](https://www.npmjs.com/package/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`.
```JavaScript
import * as schedule from "node-schedule";
const scheduleWithCheckIn = Sentry.cron.instrumentNodeSchedule(schedule);
scheduleWithCheckIn.scheduleJob(
"my-cron-job",
"* * * * *",
() => {
console.log("running a task every minute");
}
);
```
## [Job Monitoring](https://docs.sentry.io/platforms/javascript/guides/nextjs/crons.md#job-monitoring)
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`.
```javascript
Sentry.withMonitor("", () => {
// 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-Ins](https://docs.sentry.io/platforms/javascript/guides/nextjs/crons.md#check-ins)
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).
```javascript
// 🟡 Notify Sentry your job is running:
const checkInId = Sentry.captureCheckIn({
monitorSlug: "",
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: "",
status: "ok",
});
```
If your job execution fails, you can notify Sentry about the failure:
```javascript
// 🔴 Notify Sentry your job has failed:
Sentry.captureCheckIn({
// Make sure this variable is named `checkInId`
checkInId,
monitorSlug: "",
status: "error",
});
```
## [Heartbeat](https://docs.sentry.io/platforms/javascript/guides/nextjs/crons.md#heartbeat)
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.
```javascript
// Execute your scheduled task...
// 🟢 Notify Sentry your job completed successfully:
Sentry.captureCheckIn({
monitorSlug: "",
status: "ok",
});
```
If your job execution fails, you can:
```javascript
// 🔴 Notify Sentry your job has failed:
Sentry.captureCheckIn({
monitorSlug: "",
status: "error",
});
```
## [Upserting Cron Monitors](https://docs.sentry.io/platforms/javascript/guides/nextjs/crons.md#upserting-cron-monitors)
You can create and update your Monitors programmatically with code rather than [creating and configuring them in Sentry.io](https://sentry.io/issues/alerts/new/crons/).
To create/update a monitor, use `Sentry.withMonitor()` and pass in your monitor configuration as a third parameter:
```javascript
const monitorConfig = {
schedule: {
type: "crontab",
value: "* * * * *",
},
checkinMargin: 2, // In minutes. Optional.
maxRuntime: 10, // In minutes. Optional.
timezone: "America/Los_Angeles", // Optional.
};
Sentry.withMonitor(
"",
() => {
// 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:
```javascript
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: "",
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: "",
status: "ok",
},
monitorConfig,
);
```
### [Monitor Configuration Properties](https://docs.sentry.io/platforms/javascript/guides/nextjs/crons.md#monitor-configuration-properties)
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:
```json
{"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](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). Optional.
`node-cron` allows you to pass luxon timezones, but you have to convert them to an IANA timezone when using Sentry (for example, using `DateTime.local().zoneName`).
`failureIssueThreshold`:
*requires SDK version `8.7.0` or higher*
The number of consecutive failed check-ins required before an issue can be created. Optional.
`recoveryThreshold`:
*requires SDK version `8.7.0` or higher*
The number of consecutive successful check-ins required for an issue to be considered resolved. Optional.
## [Alerts](https://docs.sentry.io/platforms/javascript/guides/nextjs/crons.md#alerts)
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:
1. Navigate to **Alerts** in the sidebar.
2. Create a new alert and select "Issues" under "Errors" as the alert type.
3. 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](https://docs.sentry.io/product/alerts/create-alerts/issue-alert-config.md).
## [Rate Limits](https://docs.sentry.io/platforms/javascript/guides/nextjs/crons.md#rate-limits)
To prevent abuse and resource overuse, Crons limits check-ins to **6 per minute for each monitor environment**.
For example, if you have a monitor called "database-backup" with two environments:
* `database-backup` in environment `production` can send up to 6 check-ins per minute
* `database-backup` in environment `staging` can also send up to 6 check-ins per minute
* Combined, they can send up to 12 check-ins per minute
You can verify if any check-ins are being dropped by visiting the [Usage Stats](https://docs.sentry.io/product/stats.md#usage-stats) page. To avoid dropped check-ins, ensure your monitors don't exceed the rate limit.