@useward/instrumentation

Next.js instrumentation SDK for full-stack observability.

Installation

npm install @useward/instrumentation

Setup

1. Server-side instrumentation

Create instrumentation.ts in your project root:

import { register as registerWard } from '@useward/instrumentation';

export async function register() {
  if (process.env.NODE_ENV === 'development') {
    await registerWard();
  }
}

2. Client-side instrumentation

Create instrumentation-client.ts in your project root:

import { register as registerWard } from '@useward/instrumentation/client';

export function register() {
  if (process.env.NODE_ENV === 'development') {
    registerWard();
  }
}

3. Middleware (optional)

For trace context propagation across requests:

// middleware.ts
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';
import { wardMiddleware } from '@useward/instrumentation/middleware';

export function middleware(request: NextRequest) {
  const response = NextResponse.next();
  return wardMiddleware(request, response);
}

Configuration

Ward auto-detects your project and sends telemetry to the local devtools server.

Environment Variables

What Gets Traced

Server-Side

• React Server Component renders
• Server Actions execution
• API route handlers
• Database queries (via fetch instrumentation)
• External HTTP requests

Client-Side

• Page navigations
• Hydration timing
• Client-side fetches
• Web Vitals (FCP, LCP)
• Long tasks

Exports

Requirements

• Next.js 15+
• React 18+

License

FSL-1.1-Apache-2.0