feat(nextjs): Enhanced automatic Vercel Cron monitoring

[github-actions]

Note

The pull request "feat(nextjs): Enhanced automatic Vercel Cron monitoring" was created by @logaretm but did not reference an issue. Therefore this issue was created for better visibility in external tools like Linear.

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.

[linear]

JS-1650