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.

Requirements

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

Automatic Crons Instrumentation

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.

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 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");
  },
});

Node Cron

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" }
);

Node Schedule

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");
  }
);

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.

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

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

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",
});

Upserting Cron Monitors

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
);

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:

{"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.

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.

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.