Set Up Crons

Sentry Crons allows you to monitor the uptime and performance of any scheduled, recurring job in your application.

Once implemented, it'll allow you to get alerts and metrics to help you solve errors, detect timeouts, and prevent disruptions to your service.

Cron monitoring is only supported in Server and Edge runtimes for Next.js

If you are hosting your Next.js application on Vercel and you are using Vercel's Cron Jobs feature, 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 for more details.

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.

Copied
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.

Copied
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.

Copied
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.

Copied
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).

Copied
// 🟡 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:

Copied
// 🔴 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.

Copied
// Execute your scheduled task...

// 🟢 Notify Sentry your job completed successfully:
Sentry.captureCheckIn({
  monitorSlug: '<monitor-slug>',
  status: 'ok',
});

If your job execution fails, you can:

Copied
// 🔴 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:

Copied
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:

Copied
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:

Copied
{"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:

  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

Cron completed alert filter

Learn more in Issue Alert Configuration.

Help improve this content
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").