Next.js Project Guide

Complete rollout pattern for Next.js apps (Node runtime + browser telemetry)

Use this guide when your product surface is Next.js and you need end-to-end visibility across server and browser paths.

Architecture Scope

  • Server runtime: API routes, server actions, SSR logic.
  • Browser runtime: user interactions, route transitions, frontend errors.
  • Shared context: service/env/version/release IDs for correlation.

Server-Side Setup

Initialize the Node SDK in your instrumentation file. This runs once when the server starts.

instrumentation.ts
import { initNodeSDK } from "@obtrace/sdk-js/node";
 
export const ob = initNodeSDK({
  apiKey: process.env.OBTRACE_API_KEY!,
  serviceName: "web-nextjs",
  env: process.env.NODE_ENV,
  serviceVersion: process.env.NEXT_PUBLIC_VERCEL_GIT_COMMIT_SHA,
});

The Node SDK auto-instruments all HTTP requests and console output.

Browser-Side Setup (Zero-Config)

Import the auto entry point in your root layout. Set NEXT_PUBLIC_OBTRACE_API_KEY in your environment.

app/layout.tsx
import '@obtrace/sdk-browser/auto'
 
export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  )
}

The /auto entry point detects NEXT_PUBLIC_ prefixed env vars, initializes the SDK, patches window.fetch, and starts capturing errors, console output, Web Vitals, and session replay.

Browser-Side Setup (React Wrapper)

For more control, use the React entry point:

lib/obtrace.ts
import { obtrace } from '@obtrace/sdk-browser/react'
 
export const ob = obtrace({
  apiKey: process.env.NEXT_PUBLIC_OBTRACE_API_KEY!,
  serviceName: "web-nextjs",
})
app/layout.tsx
import '../lib/obtrace'
 
export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  )
}

Environment Variables

.env.local
OBTRACE_API_KEY=obt_...
NEXT_PUBLIC_OBTRACE_API_KEY=obt_...
NEXT_PUBLIC_OBTRACE_SERVICE_NAME=web-nextjs

Server-side variables use no prefix. Browser-side variables require NEXT_PUBLIC_.

Validation Checklist

  • Browser and server events are both visible in the Obtrace UI
  • Server errors include request context and trace ID
  • Frontend fetch calls produce correlated spans in backend traces
  • Web Vitals metrics appear after page load
  • Session replay records user interactions
  • Deploy events are visible in incident timeline

Production Hardening

  1. Keep server keys private; only use NEXT_PUBLIC_ keys in browser.
  2. Configure replay sampling to control cost.
  3. Ensure graceful shutdown flush for server runtime.
  4. Validate instrumentation after each Next.js upgrade.

On this page