@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

| Variable | Default | Description | |----------|---------|-------------| | WARD_PROJECT_ID | Auto-detected | Project identifier | | WARD_ENDPOINT | http://localhost:19393 | Devtools server URL | | WARD_DEBUG | false | Enable debug logging |

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

| Export | Description | |--------|-------------| | @useward/instrumentation | Main entry | | @useward/instrumentation | Server-side instrumentation | | @useward/instrumentation/client | Client-side instrumentation | | @useward/instrumentation/middleware | Next.js middleware utilities | | @useward/instrumentation/session-meta | Session metadata component |

Requirements

• Next.js 15+
• React 18+

License

FSL-1.1-Apache-2.0