feat(nextjs): Enhanced automatic Vercel Cron monitoring

[logaretm]

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.

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)

Loading

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

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

[linear]

JS-45 [Next.js] Support auto-detection for Vercel cron monitors on App Router

[github-actions]

Codecov Results 📊

---

Generated by Codecov Action

[Copilot]

Pull request overview

This PR introduces a new experimental span-based approach for automatic Vercel cron job monitoring that works with both the App Router and Turbopack, addressing limitations of the existing webpack wrapper-based approach.

Changes:

• Adds _experimental.vercelCronsMonitoring configuration option for span-based cron monitoring
• Implements runtime detection of Vercel cron requests via the vercel-cron user agent header
• Hooks into span lifecycle events to create check-ins without modifying user code at build time

Reviewed changes

Copilot reviewed 21 out of 21 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
packages/nextjs/src/server/vercelCronsMonitoring.ts	New module containing the span-based cron monitoring logic with check-in start/completion handlers
packages/nextjs/src/server/handleOnSpanStart.ts	Integrates cron check-in start logic into the existing span start handler
packages/nextjs/src/server/index.ts	Registers the cron check-in completion handler for span end events
packages/nextjs/src/config/withSentryConfig/getFinalConfigObjectUtils.ts	Adds logic to read vercel.json and determine monitoring strategy based on configuration
packages/nextjs/src/config/withSentryConfig/getFinalConfigObjectBundlerUtils.ts	Updates bundler configuration to pass Vercel crons config to appropriate bundlers
packages/nextjs/src/config/getFinalConfigObject.ts	Integrates Vercel crons config determination into the main config flow
packages/nextjs/src/config/webpack.ts	Refactors to support both span-based and wrapper-based strategies, injecting config as global for span-based approach
packages/nextjs/src/config/turbopack/*.ts	Adds Turbopack support for injecting Vercel crons config as global values
packages/nextjs/src/config/types.ts	Adds type definition for the new experimental option
dev-packages/e2e-tests/test-applications/nextjs-{15,16}/*	Comprehensive E2E tests for successful, error, and non-cron scenarios
packages/nextjs/test/config/testUtils.ts	Updates test utilities to handle the new Vercel crons config result

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The NextResponse import is unused. The function throws an error before it could be used, so this import can be removed.

Suggested change

import { NextResponse } from 'next/server';

[Copilot]

The NextResponse import is unused. The function throws an error before it could be used, so this import can be removed.

Suggested change

import { NextResponse } from 'next/server';

[github-actions]

node-overhead report 🧳

Note: This is a synthetic benchmark with a minimal express app and does not necessarily reflect the real-world performance impact in an application.
⚠️ Warning: Base artifact is not the latest one, because the latest workflow run is not done yet. This may lead to incorrect results. Try to re-run all tests to get up to date results.

Scenario	Requests/s	% of Baseline	Prev. Requests/s	Change %
GET Baseline	11,462	-	8,993	+27%
GET With Sentry	1,962	17%	1,634	+20%
GET With Sentry (error only)	7,689	67%	5,964	+29%
POST Baseline	1,185	-	1,174	+1%
POST With Sentry	595	50%	588	+1%
POST With Sentry (error only)	1,057	89%	1,037	+2%
MYSQL Baseline	4,040	-	3,252	+24%
MYSQL With Sentry	571	14%	423	+35%
MYSQL With Sentry (error only)	3,311	82%	2,625	+26%

View base workflow run

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.}

[chargome]

All my potatoes if this really works 🥇