Sentry Cloudflare Sdk

# Crons / Job Monitoring — Sentry Cloudflare SDK

> Minimum SDK: `@sentry/cloudflare` v8.0.0+ (`captureCheckIn`, `withMonitor`)
> Auto-instrumented `scheduled` handler: v10.x+
> Status: ✅ **Generally Available**

---

## Overview

Sentry Crons tracks whether scheduled tasks run on time, succeed, and complete within expected durations. Sentry alerts when a job:
- Misses its scheduled start time (checkin margin exceeded)
- Takes too long to complete (maxRuntime exceeded)
- Fails (status `"error"`)

Cloudflare Workers support cron triggers via the `scheduled` handler. When wrapped with `withSentry`, the scheduled handler is automatically instrumented with a `faas.cron` span that includes:
- `faas.cron` — the cron expression
- `faas.time` — the scheduled time (ISO 8601)
- `faas.trigger` — `"timer"`

---

## Automatic Scheduled Handler Instrumentation

When you use `withSentry`, the `scheduled` handler is automatically wrapped. Errors are captured and the span records duration:

```typescript
import * as Sentry from "@sentry/cloudflare";

export default Sentry.withSentry(
  (env: Env) => ({
    dsn: env.SENTRY_DSN,
    tracesSampleRate: 1.0,
  }),
  {
    async fetch(request, env, ctx) {
      return new Response("OK");
    },

    async scheduled(controller, env, ctx) {
      // Automatically instrumented — errors captured, spans created
      await cleanupOldRecords(env.DB);
    },
  } satisfies ExportedHandler<Env>,
);
```

Configure the cron trigger in `wrangler.toml`:

```toml
[triggers]
crons = ["*/5 * * * *"]  # Every 5 minutes
```

---

## `Sentry.withMonitor` — Named Monitor Tracking

For fine-grained monitoring with named monitors (visible in the Sentry Crons dashboard):

```typescript
async scheduled(controller, env, ctx) {
  ctx.waitUntil(
    Sentry.withMonitor("cleanup-old-records", async () => {
      await cleanupOldRecords(env.DB);
    }),
  );
},
```

### With Monitor Config (Upsert)

Supply a config to auto-create or update the monitor in Sentry:

```typescript
const monitorConfig = {
  schedule: {
    type: "crontab",
    value: "*/5 * * * *",
  },
  checkinMargin: 2,    // In minutes — how late is "missed"
  maxRuntime: 10,      // In minutes — when to alert for "timed out"
  timezone: "America/Los_Angeles",
};

async scheduled(controller, env, ctx) {
  ctx.waitUntil(
    Sentry.withMonitor(
      "cleanup-old-records",
      async () => {
        await cleanupOldRecords(env.DB);
      },
      monitorConfig,
    ),
  );
},
```

---

## `Sentry.captureCheckIn` — Manual Check-Ins

For more control over the check-in lifecycle:

### Heartbeat (Single-Shot)

```typescript
// Report success
Sentry.captureCheckIn({ monitorSlug: "health-check", status: "ok" });

// Report failure
Sentry.captureCheckIn({ monitorSlug: "health-check", status: "error" });
```

### In-Progress + Completion

```typescript
// Signal start
const checkInId = Sentry.captureCheckIn({
  monitorSlug: "data-sync",
  status: "in_progress",
});

try {
  await syncData(env.DB);

  // Signal success
  Sentry.captureCheckIn({
    checkInId,
    monitorSlug: "data-sync",
    status: "ok",
  });
} catch (error) {
  // Signal failure
  Sentry.captureCheckIn({
    checkInId,
    monitorSlug: "data-sync",
    status: "error",
  });
  throw error;
}
```

### With Upsert Config

```typescript
const checkInId = Sentry.captureCheckIn(
  { monitorSlug: "data-sync", status: "in_progress" },
  {
    schedule: { type: "crontab", value: "0 * * * *" },
    checkinMargin: 5,
    maxRuntime: 30,
    timezone: "UTC",
  },
);
```

---

## Schedule Types

| Type | Format | Example |
|------|--------|---------|
| `crontab` | Standard cron expression | `"*/5 * * * *"` (every 5 min) |
| `interval` | Repeated interval | `{ value: 10, unit: "minute" }` |

### Interval Schedule

```typescript
const monitorConfig = {
  schedule: {
    type: "interval",
    value: 10,
    unit: "minute", // "minute", "hour", "day", "week", "month", "year"
  },
  checkinMargin: 2,
  maxRuntime: 10,