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 Check-Ins (Recommended)

requires SDK version 7.88.0 or higher

Use the DenoCron integration to monitor your Deno.cron calls and get notified when a schedule job 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.

import * as Sentry from "https://deno.land/x/sentry/index.mjs";

Sentry.init({
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
  integrations: [Sentry.denoCronIntegration()],
});

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.