Next.js API Routes: The Monitoring Blind Spots

Next.js is the most-used JavaScript meta-framework — 52.9% of JS developers use it according to the State of JS 2024 survey. Most teams reach for it for both the frontend and the API layer. What most teams don't have: any monitoring that tells them which routes are slow, which are erroring, or which are spiking at 3am.

The framework doesn't ship with that. And the gap between 'the app is running' and 'the app is observable' is where production incidents live.

What Next.js Gives You by Default

Out of the box, Next.js logs HTTP status codes to stdout: `GET /api/users 200 43ms`. That's it. No percentiles. No per-route error rates. No breakdown of which routes are actually slow versus which just look slow in your dev environment.

Vercel's dashboard does show function invocation data — but per-route latency breakdowns and percentile data are locked behind the paid Observability Plus tier. A solo developer on the free or Pro plan gets aggregate request counts and little else. You're flying blind on the routes that matter most.

Four Gaps That Actually Burn You in Production

• Per-route latency — you know your app is 'slow' but not which route. Without per-endpoint p95/p99 data you're guessing at what to optimize.
• Server Actions — App Router Server Actions don't emit OpenTelemetry spans by default. Sentry's own engineering blog calls this out explicitly: manual instrumentation is required, and most teams skip it.
• Edge Runtime — App Router splits execution across Node.js, Edge, and client runtimes. Each needs separate instrumentation. A route running in the Edge Runtime is invisible to Node.js-based monitors.
• Cold starts — serverless functions cold-start on first invocation. This adds 500ms–2,000ms to your first request and is invisible in aggregate metrics because it gets diluted by subsequent warm requests. It only shows up in your p99.

Why Route Averages Lie to You

Your `/api/checkout` averages 160ms. Sounds fine. But the p99 is 2,400ms. That's 1 in 100 requests. If 1,000 users hit that route today, 10 of them waited 2.4 seconds to complete a purchase. Average metrics buried that.

P95 and P99 latency per route is what you actually need. Cold start spikes, database connection pool exhaustion, downstream API timeouts — none of these appear in average response times. They all appear in the tail.

Adding Per-Route Monitoring in Three Lines

Create one shared file that initialises the SDK, then wrap your Route Handlers. The `route()` helper instruments latency, error rates, and request volume per endpoint automatically.

// lib/statvisor.ts — create once, import everywhere
import { nextjs } from "@statvisor/sdk";

export const { route } = nextjs({
  apiKey: process.env.STATVISOR_API_KEY!,
});

// app/api/users/route.ts — wrap your handlers
import { NextResponse } from "next/server";
import { route } from "@/lib/statvisor";

export const { GET, POST } = route("/api/users", {
  GET: async (request) => {
    const users = await db.query("SELECT * FROM users");
    return NextResponse.json({ users });
  },
  POST: async (request) => {
    const body = await request.json();
    const user = await db.create(body);
    return NextResponse.json({ user }, { status: 201 });
  },
});

What to Actually Track Per Route

Once you have instrumentation in place, these are the metrics worth watching per endpoint:

• P95 and P99 latency — not averages. These surface cold starts, tail latency from slow database queries, and third-party API timeouts that are invisible at the median.
• Error rate per route — 500s on /api/checkout are different from 500s on /api/health. You need per-route error rates, not a global error count.
• Request volume over time — a sudden 10x spike in requests to /api/search before an error spike is causation, not correlation. Traffic context makes errors interpretable.
• Latency trend over 24h — the difference between 'slow today' and 'slow every Monday at 9am' tells you whether the problem is your code or your infrastructure.

Cold start spikes are the one thing most teams miss even after they add monitoring: they only show in the p99, and only if you look at a narrow time window. A 5-minute p99 chart after a deployment or a period of low traffic will catch them. A 24-hour average will hide them completely.