Skip to content
Tutorials Center
My learning

Topics

Lesson 60 of 72 ยท Deployment and Production

Observability and Scaling

Run Next.js in production with confidence: OpenTelemetry traces, structured logs, CDN cache headers, a shared cache, rate limiting and security headers.

Shipping a Next.js app is the easy part. The hard part starts when real traffic arrives and something is slow, something fails for only some users, or a second server joins the pool and the pages start disagreeing with each other. Observability is the set of tools that lets you answer "what is my app doing right now, and why?" without guessing. Scaling is what you do once the answer is "too much work for one machine".

This lesson walks through the production checklist for a Next.js app: tracing with OpenTelemetry, useful logs, the cache headers that make a CDN work for you, what changes when you run several instances, rate limiting, and security headers. It builds on Building and Deploying and Caching in Next.js: the Big Picture.

Real or stand-in? The Next.js files, packages and config in this lesson are real code in read-only blocks, because this site cannot run a Next.js server or an OpenTelemetry collector. The three runnable examples are plain Node.js stand-ins: a tiny tracer, two rate limiters and a CDN freshness calculator. They show the ideas that the real tools implement, with a fake clock so the output is always the same.

The production checklist

Three signals to watch

Logs What happened, in words.
Metrics How much and how fast, as numbers.
Traces Where one request spent its time.

Logs say what, metrics say how often, traces say where.

1 / 2

Traces with OpenTelemetry

OpenTelemetry (often "OTel") is a vendor-neutral standard for traces, metrics and logs. A trace describes one request. It is made of spans: a span has a name, a start and end time, optional attributes and a parent. Put them together and you get a tree that shows where the time went.

Next.js has built-in OTel support. It emits spans for the incoming request, for rendering a route, for each fetch and more. To turn it on you create an instrumentation.ts file in the project root (or in src/) that exports a register function. Next.js calls it once when the server starts:

TypeScript
// instrumentation.ts
import { registerOTel } from '@vercel/otel';

export function register() {
  registerOTel({ serviceName: 'storefront' });
}

@vercel/otel is a small helper package that wires up the OpenTelemetry SDK for you. You point it at a collector or a hosted backend such as Jaeger, Grafana Tempo, Honeycomb or Datadog with the standard OTEL_EXPORTER_OTLP_ENDPOINT environment variable. If you want full control, you can instead set up the Node SDK yourself in register. In that case, guard Node-only imports so the same file does not break the Edge runtime (see Node.js and Edge Runtimes):

TypeScript
// instrumentation.ts
export async function register() {
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    await import('./instrumentation-node');
  }
}

You can add custom spans around your own code with @opentelemetry/api. Wrap anything slow or important: a database query, a payment call, a pricing calculation.

TypeScript
import { trace } from '@opentelemetry/api';

const tracer = trace.getTracer('storefront');

export async function loadCart(userId: string) {
  return tracer.startActiveSpan('load-cart', async (span) => {
    try {
      span.setAttribute('user.id', userId);
      return await db.cart.findFirst({ where: { userId } });
    } finally {
      span.end();
    }
  });
}

Always end the span in finally, or an error will leave it open forever. Never put secrets or personal data into attributes: traces are usually stored for weeks and read by many people.

The next example is a stand-in tracer. It keeps a stack of open spans, so each new span learns its parent, and it uses a fake clock that only moves when we say "work took 180 ms". The printed tree has the same shape as what a trace viewer would show.

Node.js A tiny tracer with parent and child spans

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Read trace 1 from the top. The request took 307 ms in total, and the two fetches account for 275 ms of it. They run one after the other, which a trace makes obvious and a log line never would. Running them in parallel with Promise.all would cut the total to roughly 210 ms (see Fetching Data in Server Components). Trace 2 shows how a failing child span marks its parents too, so you can find the root cause from the top-level request. The real span names Next.js emits are similar in style (GET /route, render route (app) /route, fetch GET url) but not identical, so check your viewer for the exact ones.

Logs worth reading

In a Next.js server, console.log writes to the process's standard output, and your platform (Docker, systemd, a cloud provider) collects it. Two habits make those logs useful:

  • One JSON object per line. A log line like {"level":"error","msg":"payment failed","orderId":"o_81","durationMs":412} can be searched and filtered by a log service. A free-form sentence cannot.
  • A request id. Add one in the proxy file as a request header, read it with headers() in a Server Component or action, and include it in every log line and error report. When a customer reports a problem, you can then find every line for that request.

During development, the logging option in next.config.ts can print each fetch the server makes, with a fullUrl setting for the whole URL. Treat that as a debugging aid, not a production feature.

For errors, export onRequestError from instrumentation.ts. Next.js calls it whenever the server hits an unhandled error while rendering, in a Route Handler, in a Server Action or in the proxy:

TypeScript
// instrumentation.ts
import type { Instrumentation } from 'next';

export const onRequestError: Instrumentation.onRequestError = async (error, request, context) => {
  await fetch('https://errors.example.com/report', {
    method: 'POST',
    headers: { 'content-type': 'application/json' },
    body: JSON.stringify({
      message: error.message,
      digest: error.digest,
      path: request.path,
      routeType: context.routeType,
    }),
  });
};

The digest is a short hash that Next.js also shows to the user on the error page. It lets support staff connect "Error ID 3481203" from a screenshot to the full server-side error. Debugging and Error Handling goes deeper.

Cache headers and the CDN

A CDN (content delivery network) keeps copies of your responses in data centres near your visitors. Whether it may keep a copy is decided by the Cache-Control header on each response. Next.js sets sensible defaults, which you should verify with curl -I https://your-site/page:

Response Typical header Meaning
Files in /_next/static/ public, max-age=31536000, immutable Content-hashed file names, so cache for a year
Prerendered (static) page s-maxage=... The CDN may keep it for that many seconds
Page with revalidate (ISR) s-maxage=N, stale-while-revalidate Fresh for N seconds, then refreshed in the background
Dynamic page private, no-cache, no-store, max-age=0, must-revalidate Never share between users

Three directives matter most. max-age is for the browser. s-maxage is for shared caches such as a CDN, and wins over max-age there. stale-while-revalidate allows serving an expired copy immediately while a fresh one is fetched, so visitors never wait. The expireTime option in next.config.ts controls how long Next.js lets the stale window last for pages it generates.

This stand-in applies those rules the way a CDN does. It parses a header and tells you, for a copy of a given age, whether the CDN serves it fresh, serves it stale while refreshing, or goes back to your server.

Node.js What a CDN does with Cache-Control

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The first header is the ISR shape: for the first minute everybody gets the cached copy, for the next five minutes visitors still get an instant (slightly old) answer while one background request refreshes it, and only after that does a request wait for your server. The last header is what a personalized page must send. If a dynamic page ever shows up with public or s-maxage by accident, one user's page could be served to another. See Static vs Dynamic Rendering for how Next.js decides, and remember that cookies, headers and searchParams make a route dynamic.

Scaling beyond one instance

flowchart LR
    V["Visitors"] --> C["CDN"]
    C -->|miss| L["Load balancer"]
    L --> A["Next.js instance A"]
    L --> B["Next.js instance B"]
    A --> S["Shared cache + database"]
    B --> S

A CDN absorbs most traffic. The rest is spread over instances that must share cache and data.

Adding instances is easy because the app is stateless, as long as you do not store anything important on one machine. Three things need attention:

  1. The data cache and ISR output. By default each instance keeps its own cache on its own disk and in memory. Instance A may revalidate a page while instance B still serves the old one, and an on-demand revalidateTag call reaches only the instance that received it. The fix is a shared cache handler: a module you register with the cacheHandler option (and cacheHandlers for "use cache") that stores entries in Redis or an object store. Self-Hosting and Docker shows the details. If you deploy on a managed platform, this is handled for you.
  2. Build identity. Every instance must run the same build. Rolling out a new version while old instances still serve requests can break Server Action calls, because the action id belongs to a particular build. Set the same encryption key for Server Actions on all instances (the NEXT_SERVER_ACTIONS_ENCRYPTION_KEY environment variable) so closed-over values decrypt on any of them.
  3. Sessions. Use signed cookies or a shared session store, never in-memory sessions (see Authentication and Sessions).

Rate limiting

Some routes are expensive or abusable: login, password reset, search, anything that sends email or calls a paid API. A rate limiter says "at most N requests per time window per client".

Two common algorithms differ in how they treat bursts. A fixed window counts requests in clock-aligned slices, such as "5 per 10 seconds". It is simple, but a client can send 5 requests at the very end of one window and 5 more at the start of the next, which is 10 in about a second. A token bucket holds up to capacity tokens and refills at a steady rate. Each request spends one token, so a burst is allowed once but sustained speed is capped.

Node.js Fixed window versus token bucket

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The fixed window lets all ten requests through, because the counter resets at 10,000 ms. The token bucket allows the first five and then blocks until a token refills (one every two seconds here). When you reject a request, respond with status 429 and a Retry-After header, as the stand-in computes.

In Next.js you can run a limiter in the proxy file for coarse, per-IP protection, and again inside the specific Server Action or Route Handler for finer rules such as "5 login attempts per account per 15 minutes". Two cautions apply:

  • An in-memory limiter only counts what one instance sees. With four instances, a client gets four times the limit. For production use a shared store such as Redis, or a limiter at the CDN or load balancer.
  • The client's IP comes from a header such as x-forwarded-for. That header is only trustworthy when your own proxy sets it. A client can send any value if the request reaches your server directly.

Security headers

Security headers tell the browser to switch on defenses that cost you nothing. In Next.js, the simplest place to set them for every route is headers() in next.config.ts (see Configuring Next.js):

TypeScript
// next.config.ts
import type { NextConfig } from 'next';

const securityHeaders = [
  { key: 'X-Content-Type-Options', value: 'nosniff' },
  { key: 'Referrer-Policy', value: 'strict-origin-when-cross-origin' },
  { key: 'X-Frame-Options', value: 'DENY' },
  { key: 'Strict-Transport-Security', value: 'max-age=63072000; includeSubDomains' },
  { key: 'Permissions-Policy', value: 'camera=(), microphone=(), geolocation=()' },
];

const nextConfig: NextConfig = {
  poweredByHeader: false,
  async headers() {
    return [{ source: '/(.*)', headers: securityHeaders }];
  },
};

export default nextConfig;

What each one does, briefly: nosniff stops browsers from guessing a file's type, Referrer-Policy limits what URL information leaks to other sites, X-Frame-Options: DENY blocks clickjacking by forbidding your pages in frames, Strict-Transport-Security makes browsers use HTTPS only (add preload only when you are sure, because it is hard to undo), and Permissions-Policy switches off browser features you do not use.

The strongest header is Content-Security-Policy (CSP). It lists where scripts, styles and images may come from, which limits what an injected script can do. Next.js adds inline scripts for hydration, so a strict CSP needs a nonce: a random value generated per request in the proxy file, sent in the CSP header and passed to Next.js, which attaches it to its scripts. That works, but it forces dynamic rendering for the pages involved, so weigh it against the caching benefits above. Roll out a CSP first with the Content-Security-Policy-Report-Only header and read the reports before enforcing.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does a trace tell you that a log line usually does not?

    A trace is a tree of spans with start and end times for one request, so you can see where the time went, for example two sequential fetches.
  2. 2. Which Cache-Control directive applies to shared caches such as a CDN and overrides max-age there?

    s-maxage is the lifetime for shared caches. max-age is what the browser uses. private forbids shared caches altogether.
  3. 3. Two Next.js instances run behind a load balancer with the default cache settings. What is the likely problem?

    The default cache lives on each instance's disk and memory. A shared cache handler, for example backed by Redis, makes all instances see the same entries.
  4. 4. A fixed-window limiter allows 5 requests per 10 seconds. What weakness does the token bucket fix?

    With clock-aligned windows, 5 requests at the end of one window and 5 at the start of the next all pass. A token bucket refills steadily, so a sustained rate stays capped.
  5. 5. Why should you start a Content-Security-Policy in report-only mode?

    A strict CSP can block inline scripts or third-party widgets you rely on. Report-only collects violations without blocking anything, so you can adjust first.

Summary

  • Observability is logs (what), metrics (how much) and traces (where the time went). Next.js has built-in OpenTelemetry support through instrumentation.ts and its register function.
  • Wrap important code in custom spans, always end them in finally, and keep secrets out of attributes. Use onRequestError to report unhandled errors, with the digest linking user-visible error ids to server logs.
  • Write one JSON object per log line and include a request id.
  • A CDN follows Cache-Control: s-maxage for shared caches, stale-while-revalidate for instant stale answers. Personalized pages must be private or no-store. Check real headers with curl -I.
  • Several instances need a shared cache handler, one build everywhere, a shared Server Actions encryption key and cookie or shared-store sessions.
  • Rate limit expensive routes with a token bucket or similar, return 429 with Retry-After, and use a shared store when you run more than one instance.
  • Set security headers in next.config.ts, and introduce a nonce-based CSP carefully, in report-only mode first.

Next: Upgrading and Migrating from Pages Router