feat(nextjs): Enhanced automatic Vercel Cron monitoring (#19192)

This PR introduces a new experimental approach for automatic Vercel cron
job monitoring that leverages span lifecycle events instead of wrapping
route handlers at build time.

**Summary**

The current `automaticVercelMonitors` option works by wrapping cron
route handlers during webpack compilation. This forced a couple of
limitations, we couldn't do Turbopack and we couldn't do App Router.

This new approach (`_experimental.vercelCronsMonitoring`) instead hooks
into the span start/end events to detect cron requests at runtime and
send check-ins accordingly. This is less invasive and works without
modifying user code.

**How it works**

When a request comes in, we check if it's a Vercel cron request by
looking for the `vercel-cron` user agent header we already collected. If
it matches a configured cron path from `vercel.json`, we start an
"in_progress" check-in and store the check-in ID on the span as
attributes.

When the span ends, we complete the check-in with either "ok" or "error"
status based on the span's final status and delete the attributes we
added earlier.

```mermaid
sequenceDiagram
    participant Vercel
    participant NextJS as Next.js App
    participant SDK as Sentry SDK
    participant Sentry

    Vercel->>NextJS: GET /api/my-cron (User-Agent: vercel-cron/1.0)
    NextJS->>SDK: Span starts
    SDK->>SDK: Detect vercel-cron user agent
    SDK->>SDK: Match route to vercel.json crons config
    SDK->>Sentry: Check-in (status: in_progress)
    SDK->>SDK: Store check-in ID as span attribute
    NextJS->>NextJS: Execute route handler
    NextJS->>SDK: Span ends
    SDK->>SDK: Read check-in ID from span
    SDK->>SDK: Determine status from span (ok/error)
    SDK->>Sentry: Check-in (status: ok or error)
```

**Backward Compatibility**

The existing `automaticVercelMonitors` option continues to work
unchanged. When both options are enabled, the SDK prefers the new
span-based approach and logs a warning suggesting to remove the legacy
option.

| Configuration | Behavior |
|---------------|----------|
| Only `webpack.automaticVercelMonitors: true` | Uses existing wrapper
approach |
| Only `_experimental.vercelCronsMonitoring: true` | Uses new span-based
approach |
| Both enabled | Uses span-based approach + warning |

**Usage**

```javascript
// next.config.js
module.exports = withSentryConfig(nextConfig, {
  _experimental: {
    vercelCronsMonitoring: true,
  },
});
```

---

**Why is it experimental?**

I need to test this out in production with a few scenarios, it works
locally and it works when I half-assed a prod vercel app via a tunnel to
my local Verdaccio.

Also I think it is a bit flimsy, it all depends if the header is there.
If Vercel changes the implementation or we stop applying the headers on
the spans then this easily breaks.

I'm thinking we can dogfood this initially and see how well it works for
us before trying something else.

Closes #11637

Author: logaretm

CHANGELOG.md

@@ -10,6 +10,21 @@ Work in this release was contributed by @limbonaut. Thank you for your contribut
 
   The `sentryTanstackStart` Vite plugin now automatically instruments middleware in `createServerFn().middleware([...])` calls. This captures performance data without requiring manual wrapping with `wrapMiddlewaresWithSentry()`.
 
+- **feat(nextjs): New experimental automatic vercel cron monitoring ([#19066](https://github.com/getsentry/sentry-javascript/pull/19192))**
+
+Setting `_experimental.vercelCronMonitoring` to `true` in your Sentry configuration will automatically create Sentry cron monitors for your Vercel Cron Jobs.
+
+Please note that this is an experimental unstable feature and subject to change.
+
+```ts
+// next.config.ts
+export default withSentryConfig(nextConfig, {
+  _experimental: {
+    vercelCronMonitoring: true,
+  },
+});
+```
+
 ## 10.38.0
 
 ### Important Changes

dev-packages/e2e-tests/test-applications/nextjs-15/app/api/cron-test-error/route.ts

@@ -0,0 +1,5 @@
+export const dynamic = 'force-dynamic';
+
+export async function GET() {
+  throw new Error('Cron job error');
+}

dev-packages/e2e-tests/test-applications/nextjs-15/app/api/cron-test/route.ts

@@ -0,0 +1,9 @@
+import { NextResponse } from 'next/server';
+
+export const dynamic = 'force-dynamic';
+
+export async function GET() {
+  // Simulate some work
+  await new Promise(resolve => setTimeout(resolve, 100));
+  return NextResponse.json({ message: 'Cron job executed successfully' });
+}

dev-packages/e2e-tests/test-applications/nextjs-15/next.config.js

@@ -1,5 +1,8 @@
 const { withSentryConfig } = require('@sentry/nextjs');
 
+// Simulate Vercel environment for cron monitoring tests
+process.env.VERCEL = '1';
+
 /** @type {import('next').NextConfig} */
 const nextConfig = {};
 
@@ -8,4 +11,7 @@ module.exports = withSentryConfig(nextConfig, {
   release: {
     name: 'foobar123',
   },
+  _experimental: {
+    vercelCronsMonitoring: true,
+  },
 });

dev-packages/e2e-tests/test-applications/nextjs-15/tests/vercel-cron-monitoring.test.ts

@@ -0,0 +1,146 @@
+import { expect, test } from '@playwright/test';
+import { waitForEnvelopeItem } from '@sentry-internal/test-utils';
+
+test('Sends cron check-in envelope for successful cron job', async ({ request }) => {
+  const inProgressEnvelopePromise = waitForEnvelopeItem('nextjs-15', envelope => {
+    return (
+      envelope[0].type === 'check_in' &&
+      // @ts-expect-error envelope[1] is untyped
+      envelope[1]['monitor_slug'] === '/api/cron-test' &&
+      // @ts-expect-error envelope[1] is untyped
+      envelope[1]['status'] === 'in_progress'
+    );
+  });
+
+  const okEnvelopePromise = waitForEnvelopeItem('nextjs-15', envelope => {
+    return (
+      envelope[0].type === 'check_in' &&
+      // @ts-expect-error envelope[1] is untyped
+      envelope[1]['monitor_slug'] === '/api/cron-test' &&
+      // @ts-expect-error envelope[1] is untyped
+      envelope[1]['status'] === 'ok'
+    );
+  });
+
+  const response = await request.get('/api/cron-test', {
+    headers: {
+      'User-Agent': 'vercel-cron/1.0',
+    },
+  });
+
+  expect(response.status()).toBe(200);
+  expect(await response.json()).toStrictEqual({ message: 'Cron job executed successfully' });
+
+  const inProgressEnvelope = await inProgressEnvelopePromise;
+  const okEnvelope = await okEnvelopePromise;
+
+  expect(inProgressEnvelope[1]).toEqual(
+    expect.objectContaining({
+      check_in_id: expect.any(String),
+      monitor_slug: '/api/cron-test',
+      status: 'in_progress',
+      monitor_config: {
+        schedule: {
+          type: 'crontab',
+          value: '0 * * * *',
+        },
+        max_runtime: 720,
+      },
+    }),
+  );
+
+  expect(okEnvelope[1]).toEqual(
+    expect.objectContaining({
+      check_in_id: expect.any(String),
+      monitor_slug: '/api/cron-test',
+      status: 'ok',
+      duration: expect.any(Number),
+    }),
+  );
+  // @ts-expect-error envelope[1] is untyped
+  expect(okEnvelope[1]['check_in_id']).toBe(inProgressEnvelope[1]['check_in_id']);
+});
+
+test('Sends cron check-in envelope with error status for failed cron job', async ({ request }) => {
+  const inProgressEnvelopePromise = waitForEnvelopeItem('nextjs-15', envelope => {
+    return (
+      envelope[0].type === 'check_in' &&
+      // @ts-expect-error envelope[1] is untyped
+      envelope[1]['monitor_slug'] === '/api/cron-test-error' &&
+      // @ts-expect-error envelope[1] is untyped
+      envelope[1]['status'] === 'in_progress'
+    );
+  });
+
+  const errorEnvelopePromise = waitForEnvelopeItem('nextjs-15', envelope => {
+    return (
+      envelope[0].type === 'check_in' &&
+      // @ts-expect-error envelope[1] is untyped
+      envelope[1]['monitor_slug'] === '/api/cron-test-error' &&
+      // @ts-expect-error envelope[1] is untyped
+      envelope[1]['status'] === 'error'
+    );
+  });
+
+  await request.get('/api/cron-test-error', {
+    headers: {
+      'User-Agent': 'vercel-cron/1.0',
+    },
+  });
+
+  const inProgressEnvelope = await inProgressEnvelopePromise;
+  const errorEnvelope = await errorEnvelopePromise;
+
+  expect(inProgressEnvelope[1]).toEqual(
+    expect.objectContaining({
+      check_in_id: expect.any(String),
+      monitor_slug: '/api/cron-test-error',
+      status: 'in_progress',
+      monitor_config: {
+        schedule: {
+          type: 'crontab',
+          value: '30 * * * *',
+        },
+        max_runtime: 720,
+      },
+    }),
+  );
+
+  expect(errorEnvelope[1]).toEqual(
+    expect.objectContaining({
+      check_in_id: expect.any(String),
+      monitor_slug: '/api/cron-test-error',
+      status: 'error',
+      duration: expect.any(Number),
+    }),
+  );
+
+  // @ts-expect-error envelope[1] is untyped
+  expect(errorEnvelope[1]['check_in_id']).toBe(inProgressEnvelope[1]['check_in_id']);
+});
+
+test('Does not send cron check-in envelope for regular requests without vercel-cron user agent', async ({
+  request,
+}) => {
+  let checkInReceived = false;
+
+  waitForEnvelopeItem('nextjs-15', envelope => {
+    if (
+      envelope[0].type === 'check_in' && // @ts-expect-error envelope[1] is untyped
+      envelope[1]['monitor_slug'] === '/api/cron-test'
+    ) {
+      checkInReceived = true;
+      return true;
+    }
+    return false;
+  });
+
+  const response = await request.get('/api/cron-test');
+
+  expect(response.status()).toBe(200);
+  expect(await response.json()).toStrictEqual({ message: 'Cron job executed successfully' });
+
+  await new Promise(resolve => setTimeout(resolve, 2000));
+
+  expect(checkInReceived).toBe(false);
+});

dev-packages/e2e-tests/test-applications/nextjs-15/vercel.json

@@ -0,0 +1,12 @@
+{
+  "crons": [
+    {
+      "path": "/api/cron-test",
+      "schedule": "0 * * * *"
+    },
+    {
+      "path": "/api/cron-test-error",
+      "schedule": "30 * * * *"
+    }
+  ]
+}

dev-packages/e2e-tests/test-applications/nextjs-16/app/api/cron-test-error/route.ts

@@ -0,0 +1,5 @@
+export const dynamic = 'force-dynamic';
+
+export async function GET() {
+  throw new Error('Cron job error');
+}

dev-packages/e2e-tests/test-applications/nextjs-16/app/api/cron-test/route.ts

@@ -0,0 +1,9 @@
+import { NextResponse } from 'next/server';
+
+export const dynamic = 'force-dynamic';
+
+export async function GET() {
+  // Simulate some work
+  await new Promise(resolve => setTimeout(resolve, 100));
+  return NextResponse.json({ message: 'Cron job executed successfully' });
+}

dev-packages/e2e-tests/test-applications/nextjs-16/next.config.ts

@@ -1,8 +1,14 @@
 import { withSentryConfig } from '@sentry/nextjs';
 import type { NextConfig } from 'next';
 
+// Simulate Vercel environment for cron monitoring tests
+process.env.VERCEL = '1';
+
 const nextConfig: NextConfig = {};
 
 export default withSentryConfig(nextConfig, {
   silent: true,
+  _experimental: {
+    vercelCronsMonitoring: true,
+  },
 });

dev-packages/e2e-tests/test-applications/nextjs-16/tests/vercel-cron-monitoring.test.ts

@@ -0,0 +1,147 @@
+import { expect, test } from '@playwright/test';
+import { waitForEnvelopeItem } from '@sentry-internal/test-utils';
+
+test('Sends cron check-in envelope for successful cron job', async ({ request }) => {
+  const inProgressEnvelopePromise = waitForEnvelopeItem('nextjs-16', envelope => {
+    return (
+      envelope[0].type === 'check_in' &&
+      // @ts-expect-error envelope[1] is untyped
+      envelope[1]['monitor_slug'] === '/api/cron-test' &&
+      // @ts-expect-error envelope[1] is untyped
+      envelope[1]['status'] === 'in_progress'
+    );
+  });
+
+  const okEnvelopePromise = waitForEnvelopeItem('nextjs-16', envelope => {
+    return (
+      envelope[0].type === 'check_in' &&
+      // @ts-expect-error envelope[1] is untyped
+      envelope[1]['monitor_slug'] === '/api/cron-test' &&
+      // @ts-expect-error envelope[1] is untyped
+      envelope[1]['status'] === 'ok'
+    );
+  });
+
+  const response = await request.get('/api/cron-test', {
+    headers: {
+      'User-Agent': 'vercel-cron/1.0',
+    },
+  });
+
+  expect(response.status()).toBe(200);
+  expect(await response.json()).toStrictEqual({ message: 'Cron job executed successfully' });
+
+  const inProgressEnvelope = await inProgressEnvelopePromise;
+  const okEnvelope = await okEnvelopePromise;
+
+  expect(inProgressEnvelope[1]).toEqual(
+    expect.objectContaining({
+      check_in_id: expect.any(String),
+      monitor_slug: '/api/cron-test',
+      status: 'in_progress',
+      monitor_config: {
+        schedule: {
+          type: 'crontab',
+          value: '0 * * * *',
+        },
+        max_runtime: 720,
+      },
+    }),
+  );
+
+  expect(okEnvelope[1]).toEqual(
+    expect.objectContaining({
+      check_in_id: expect.any(String),
+      monitor_slug: '/api/cron-test',
+      status: 'ok',
+      duration: expect.any(Number),
+    }),
+  );
+
+  // @ts-expect-error envelope[1] is untyped
+  expect(okEnvelope[1]['check_in_id']).toBe(inProgressEnvelope[1]['check_in_id']);
+});
+
+test('Sends cron check-in envelope with error status for failed cron job', async ({ request }) => {
+  const inProgressEnvelopePromise = waitForEnvelopeItem('nextjs-16', envelope => {
+    return (
+      envelope[0].type === 'check_in' &&
+      // @ts-expect-error envelope[1] is untyped
+      envelope[1]['monitor_slug'] === '/api/cron-test-error' &&
+      // @ts-expect-error envelope[1] is untyped
+      envelope[1]['status'] === 'in_progress'
+    );
+  });
+
+  const errorEnvelopePromise = waitForEnvelopeItem('nextjs-16', envelope => {
+    return (
+      envelope[0].type === 'check_in' &&
+      // @ts-expect-error envelope[1] is untyped
+      envelope[1]['monitor_slug'] === '/api/cron-test-error' &&
+      // @ts-expect-error envelope[1] is untyped
+      envelope[1]['status'] === 'error'
+    );
+  });
+
+  await request.get('/api/cron-test-error', {
+    headers: {
+      'User-Agent': 'vercel-cron/1.0',
+    },
+  });
+
+  const inProgressEnvelope = await inProgressEnvelopePromise;
+  const errorEnvelope = await errorEnvelopePromise;
+
+  expect(inProgressEnvelope[1]).toEqual(
+    expect.objectContaining({
+      check_in_id: expect.any(String),
+      monitor_slug: '/api/cron-test-error',
+      status: 'in_progress',
+      monitor_config: {
+        schedule: {
+          type: 'crontab',
+          value: '30 * * * *',
+        },
+        max_runtime: 720,
+      },
+    }),
+  );
+
+  expect(errorEnvelope[1]).toEqual(
+    expect.objectContaining({
+      check_in_id: expect.any(String),
+      monitor_slug: '/api/cron-test-error',
+      status: 'error',
+      duration: expect.any(Number),
+    }),
+  );
+
+  // @ts-expect-error envelope[1] is untyped
+  expect(errorEnvelope[1]['check_in_id']).toBe(inProgressEnvelope[1]['check_in_id']);
+});
+
+test('Does not send cron check-in envelope for regular requests without vercel-cron user agent', async ({
+  request,
+}) => {
+  let checkInReceived = false;
+
+  waitForEnvelopeItem('nextjs-16', envelope => {
+    if (
+      envelope[0].type === 'check_in' && // @ts-expect-error envelope[1] is untyped
+      envelope[1]['monitor_slug'] === '/api/cron-test'
+    ) {
+      checkInReceived = true;
+      return true;
+    }
+    return false;
+  });
+
+  const response = await request.get('/api/cron-test');
+
+  expect(response.status()).toBe(200);
+  expect(await response.json()).toStrictEqual({ message: 'Cron job executed successfully' });
+
+  await new Promise(resolve => setTimeout(resolve, 2000));
+
+  expect(checkInReceived).toBe(false);
+});