@danieljvdm/dev-kit 1.0.2 → 2.0.0

package/skills/sentry/references/sdks/node/crons.md

@@ -0,0 +1,432 @@
+# Crons / Job Monitoring — Sentry Node.js SDK
+
+> Minimum SDK: `@sentry/node` ≥7.51.1 (`captureCheckIn`, `withMonitor`)\
+> `instrumentNodeCron` / `instrumentCron`: ≥7.92.0\
+> `instrumentNodeSchedule`: ≥7.93.0\
+> `failureIssueThreshold` / `recoveryThreshold`: ≥8.7.0\
+> `isolateTrace` in `MonitorConfig`: ≥10.28.0\
+> Status: ✅ **Generally Available**
+
+---
+
+## Overview
+
+Sentry Crons (job monitoring) tracks whether scheduled tasks run on time, succeed, and
+complete within expected durations.
+Sentry will alert when a job:
+
+- Misses its scheduled start time (checkin margin exceeded)
+- Takes too long to complete (maxRuntime exceeded)
+- Fails (status `"error"`)
+
+---
+
+## Core API
+
+### `Sentry.captureCheckIn(checkIn, monitorConfig?)` → `string`
+
+```typescript
+// Three check-in shapes:
+
+// 1. Heartbeat — single-shot, no duration tracking
+Sentry.captureCheckIn({ monitorSlug: "my-job", status: "ok" });
+Sentry.captureCheckIn({ monitorSlug: "my-job", status: "error" });
+
+// 2. In-progress — signals job started, returns ID for completion
+const checkInId = Sentry.captureCheckIn({
+  monitorSlug: "my-job",
+  status: "in_progress",
+});
+
+// 3. Finished — completes an in-progress check-in
+Sentry.captureCheckIn({
+  checkInId,
+  monitorSlug: "my-job",
+  status: "ok", // or "error"
+  duration: 12.3, // optional, in seconds
+});
+```
+
+### `Sentry.withMonitor(slug, callback, monitorConfig?)` → `T`
+
+Wraps a sync or async function.
+Automatically sends `in_progress`, then `ok` on success or `error` on throw.
+Records duration automatically.
+
+```typescript
+// Simple form
+await Sentry.withMonitor("my-job", async () => {
+  await runJob();
+});
+
+// With monitor config
+await Sentry.withMonitor(
+  "my-job",
+  async () => {
+    await runJob();
+  },
+  {
+    schedule: { type: "crontab", value: "0 * * * *" },
+    checkinMargin: 5,
+    maxRuntime: 30,
+    timezone: "America/New_York",
+  },
+);
+```
+
+---
+
+## Check-In Status Values
+
+| Status          | Meaning                                        |
+| --------------- | ---------------------------------------------- |
+| `"in_progress"` | Job has started; Sentry waiting for completion |
+| `"ok"`          | Job completed successfully                     |
+| `"error"`       | Job failed; triggers incident in Sentry        |
+
+---
+
+## Usage Patterns
+
+### Heartbeat (simplest — detect missed runs only)
+
+```typescript
+try {
+  await runMyJob();
+  Sentry.captureCheckIn({ monitorSlug: "my-cron-job", status: "ok" });
+} catch (err) {
+  Sentry.captureCheckIn({ monitorSlug: "my-cron-job", status: "error" });
+  throw err;
+}
+```
+
+### Start/Finish (tracks in-progress state and duration)
+
+```typescript
+const checkInId = Sentry.captureCheckIn({
+  monitorSlug: "my-cron-job",
+  status: "in_progress",
+});
+
+const startTime = Date.now();
+
+try {
+  await runMyJob();
+  Sentry.captureCheckIn({
+    checkInId,
+    monitorSlug: "my-cron-job",
+    status: "ok",
+    duration: (Date.now() - startTime) / 1000, // seconds
+  });
+} catch (err) {
+  Sentry.captureCheckIn({
+    checkInId,
+    monitorSlug: "my-cron-job",
+    status: "error",
+    duration: (Date.now() - startTime) / 1000,
+  });
+  throw err;
+}
+```
+
+### `withMonitor` (recommended — handles all status logic)
+
+```typescript
+await Sentry.withMonitor("my-cron-job", async () => {
+  await runMyJob();
+});
+```
+
+---
+
+## Monitor Configuration (Upsert)
+
+Pass a `MonitorConfig` to create or update the monitor from code — no manual setup in
+Sentry UI needed. On first check-in the monitor is created; subsequent calls update it.
+
+```typescript
+interface MonitorConfig {
+  schedule: CrontabSchedule | IntervalSchedule; // REQUIRED
+  checkinMargin?: number; // minutes: grace period before "missed" alert
+  maxRuntime?: number; // minutes: max execution before timeout alert
+  timezone?: string; // IANA timezone, e.g. "America/New_York"
+  failureIssueThreshold?: number; // consecutive failures before creating issue (≥8.7.0)
+  recoveryThreshold?: number; // consecutive OKs before resolving issue (≥8.7.0)
+  isolateTrace?: boolean; // new trace per monitor run (≥10.28.0)
+}
+```
+
+Pass as the **second argument** to `captureCheckIn()` or **third argument** to
+`withMonitor()`.
+
+---
+
+## Schedule Types
+
+**Crontab schedule:**
+
+```typescript
+{ type: "crontab", value: "* * * * *" }          // every minute
+{ type: "crontab", value: "0 * * * *" }          // every hour
+{ type: "crontab", value: "0 4 * * *" }          // daily at 4:00am
+{ type: "crontab", value: "0 9 * * MON-FRI" }    // weekdays at 9am
+{ type: "crontab", value: "0 0 1 * *" }          // first of every month
+{ type: "crontab", value: "*/15 * * * *" }       // every 15 minutes
+```
+
+**Interval schedule:**
+
+```typescript
+{ type: "interval", value: 1,  unit: "hour" }
+{ type: "interval", value: 30, unit: "minute" }
+{ type: "interval", value: 7,  unit: "day" }
+{ type: "interval", value: 1,  unit: "week" }
+// unit: "year" | "month" | "week" | "day" | "hour" | "minute"
+```
+
+---
+
+## Full Upsert Example
+
+```typescript
+const monitorConfig: Sentry.MonitorConfig = {
+  schedule: {
+    type: "crontab",
+    value: "0 4 * * *", // daily at 4am
+  },
+  checkinMargin: 5, // alert if not started within 5 min
+  maxRuntime: 30, // alert if running > 30 min
+  timezone: "America/New_York",
+  failureIssueThreshold: 3, // create issue after 3 consecutive failures
+  recoveryThreshold: 2, // resolve issue after 2 consecutive successes
+  isolateTrace: true, // SDK ≥10.28.0
+};
+
+await Sentry.withMonitor("daily-report-job", generateDailyReport, monitorConfig);
+```
+
+---
+
+## Scheduler Library Integrations
+
+### `node-cron` (SDK ≥7.92.0)
+
+```typescript
+import cron from "node-cron";
+import * as Sentry from "@sentry/node";
+
+const cronWithCheckIn = Sentry.cron.instrumentNodeCron(cron);
+
+// `name` option is REQUIRED — becomes the monitor slug
+cronWithCheckIn.schedule(
+  "* * * * *",
+  () => {
+    /* task */
+  },
+  { name: "my-cron-job" },
+);
+```
+
+### `cron` package — `CronJob` (SDK ≥7.92.0)
+
+```typescript
+import { CronJob } from "cron";
+import * as Sentry from "@sentry/node";
+
+// Monitor slug is bound at instrumentation time
+const CronJobWithCheckIn = Sentry.cron.instrumentCron(CronJob, "my-cron-job");
+
+// Constructor form
+const job = new CronJobWithCheckIn("* * * * *", () => {
+  /* task */
+});
+
+// Static factory form
+const job2 = CronJobWithCheckIn.from({
+  cronTime: "* * * * *",
+  onTick: () => {
+    /* task */
+  },
+});
+```
+
+### `node-schedule` (SDK ≥7.93.0)
+
+```typescript
+import * as schedule from "node-schedule";
+import * as Sentry from "@sentry/node";
+
+const scheduleWithCheckIn = Sentry.cron.instrumentNodeSchedule(schedule);
+
+// First argument must be the job name (monitor slug)
+scheduleWithCheckIn.scheduleJob(
+  "my-cron-job", // monitor slug — REQUIRED as first arg
+  "* * * * *", // cron expression
+  () => {
+    /* task */
+  },
+);
+```
+
+### Agenda (no official helper — use `withMonitor`)
+
+```typescript
+import Agenda from "agenda";
+import * as Sentry from "@sentry/node";
+
+const agenda = new Agenda({ db: { address: "mongodb://localhost/agenda" } });
+
+agenda.define("send-newsletter", async (job) => {
+  await Sentry.withMonitor(
+    "send-newsletter",
+    async () => {
+      await sendNewsletterEmails();
+    },
+    {
+      schedule: { type: "crontab", value: "0 8 * * MON" },
+      maxRuntime: 60,
+      timezone: "UTC",
+    },
+  );
+});
+```
+
+### Bull / BullMQ (no official helper — use `withMonitor`)
+
+```typescript
+import { Worker } from "bullmq";
+import * as Sentry from "@sentry/node";
+
+const worker = new Worker("report-queue", async (job) => {
+  await Sentry.withMonitor(
+    "report-queue-processor",
+    async () => {
+      await processReportJob(job.data);
+    },
+    {
+      schedule: { type: "interval", value: 5, unit: "minute" },
+      maxRuntime: 10,
+      checkinMargin: 2,
+    },
+  );
+});
+```
+
+---
+
+## Library Integration Signatures
+
+```typescript
+// node-cron
+function instrumentNodeCron<T>(
+  lib: Partial<NodeCron> & T,
+  monitorConfig?: Pick<MonitorConfig, "isolateTrace">,
+): T;
+
+// cron package
+function instrumentCron<T>(
+  lib: T & CronJobConstructor,
+  monitorSlug: string, // REQUIRED — single slug for all jobs from this constructor
+): T;
+
+// node-schedule
+function instrumentNodeSchedule<T>(lib: T & NodeSchedule): T;
+```
+
+---
+
+## Serverless / Lambda
+
+Check-ins are lost if the process terminates before flush.
+Always flush explicitly:
+
+```typescript
+export const handler = async (event: any) => {
+  const checkInId = Sentry.captureCheckIn({
+    monitorSlug: "lambda-scheduled-job",
+    status: "in_progress",
+  });
+
+  try {
+    await doWork(event);
+    Sentry.captureCheckIn({
+      checkInId,
+      monitorSlug: "lambda-scheduled-job",
+      status: "ok",
+    });
+  } catch (err) {
+    Sentry.captureCheckIn({
+      checkInId,
+      monitorSlug: "lambda-scheduled-job",
+      status: "error",
+    });
+    throw err;
+  } finally {
+    // CRITICAL — flush before Lambda container freezes
+    await Sentry.flush(2000);
+  }
+};
+```
+
+For AWS Lambda, prefer `@sentry/aws-serverless` — it handles flushing automatically.
+
+---
+
+## Deno: Native Cron Integration
+
+Deno provides a built-in `Deno.cron()` API. Use `denoCronIntegration` to automatically
+monitor all native Deno crons:
+
+```typescript
+import * as Sentry from "@sentry/deno";
+
+Sentry.init({
+  dsn: Deno.env.get("SENTRY_DSN"),
+  integrations: [Sentry.denoCronIntegration()],
+});
+
+// Automatically monitored — no manual check-ins needed
+Deno.cron("daily-cleanup", "0 0 * * *", async () => {
+  await cleanupOldRecords();
+});
+
+Deno.cron("hourly-sync", "0 * * * *", async () => {
+  await syncExternalData();
+});
+```
+
+The integration intercepts `Deno.cron()` calls and wraps them with automatic
+`in_progress` → `ok`/`error` check-ins.
+The monitor slug is the first argument to `Deno.cron()`.
+
+> **Deno Deploy:** `Deno.cron()` runs natively on Deno Deploy.
+> The integration works in both local Deno and Deno Deploy environments.
+
+> **Node.js and Bun:** `denoCronIntegration` is only available in `@sentry/deno`. For
+> Node.js, use the `node-cron`, `cron`, or `node-schedule` library helpers above.
+
+---
+
+## Rate Limits
+
+- Maximum **6 check-ins per minute** per monitor + environment combination
+- Each environment (production, staging, etc.)
+  counts separately
+- Dropped check-ins appear in Sentry’s Usage Stats page
+
+---
+
+## Troubleshooting
+
+| Problem                               | Likely Cause                       | Fix                                                              |
+| ------------------------------------- | ---------------------------------- | ---------------------------------------------------------------- |
+| Monitor not created in Sentry         | No `MonitorConfig` passed          | Pass `schedule` in `monitorConfig` (upsert)                      |
+| Check-ins not arriving                | Process exits before flush         | Add `await Sentry.flush(2000)` before exit                       |
+| `withMonitor` status wrong            | Callback doesn’t throw on failure  | Ensure your job throws on error                                  |
+| `node-cron` job not tracked           | Missing `name` option              | Add `{ name: "slug" }` to `cron.schedule()` options              |
+| `instrumentNodeSchedule` slug not set | First arg is cron expression       | First arg to `scheduleJob()` must be the job name                |
+| `instrumentCron` tracking wrong job   | Multiple jobs from one constructor | Each constructor call is for one slug; create multiple if needed |
+| Duration always `undefined`           | Using heartbeat pattern            | Switch to start/finish or `withMonitor` for duration tracking    |
+| Missing `failureIssueThreshold`       | SDK < 8.7.0                        | Upgrade to ≥8.7.0                                                |
+| `isolateTrace` not recognized         | SDK < 10.28.0                      | Upgrade to ≥10.28.0                                              |
+| Rate limit errors in logs             | > 6 check-ins/min per monitor      | Reduce check-in frequency or consolidate environments            |