securenow 5.0.0 → 5.0.2

package/docs/NEXTJS-SETUP-COMPLETE.md

@@ -0,0 +1,795 @@
+# Next.js Setup Guide - SecureNow Observability
+
+Complete guide to add distributed tracing and logging to your Next.js application using SecureNow.
+
+---
+
+## Prerequisites
+
+- Next.js 13 or higher (works with both App Router and Pages Router)
+- Node.js 18 or higher
+- An OTLP-compatible observability backend
+
+---
+
+## Installation
+
+```bash
+npm install securenow
+```
+
+---
+
+## Quick Start - App Router (Next.js 13+)
+
+### Step 1: Install Package
+
+```bash
+npm install securenow
+```
+
+### Step 2: Create `instrumentation.ts`
+
+Create `instrumentation.ts` (or `.js`) in your project root (same level as `app/` directory):
+
+```typescript
+// instrumentation.ts
+export async function register() {
+  if (process.env.NEXT_RUNTIME === 'nodejs') {
+    // Enable logging
+    process.env.SECURENOW_LOGGING_ENABLED = '1';
+    
+    // Initialize tracing and logging
+    await import('securenow/register');
+    await import('securenow/console-instrumentation');
+    
+    console.log('SecureNow observability initialized');
+  }
+}
+```
+
+### Step 3: Enable Instrumentation Hook
+
+```javascript
+// next.config.js
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  experimental: {
+    instrumentationHook: true,
+  },
+};
+
+module.exports = nextConfig;
+```
+
+### Step 4: Create `.env.local`
+
+```env
+SECURENOW_APPID=my-nextjs-app
+SECURENOW_INSTANCE=http://localhost:4318
+SECURENOW_LOGGING_ENABLED=1
+SECURENOW_CAPTURE_BODY=1
+NODE_ENV=development
+```
+
+### Step 5: Run Your Application
+
+```bash
+npm run dev
+```
+
+You should see:
+
+```
+[securenow] OTel SDK started → http://localhost:4318/v1/traces
+[securenow] 📋 Logging: ENABLED → http://localhost:4318/v1/logs
+[securenow] Console instrumentation installed
+SecureNow observability initialized
+```
+
+**Done!** Your Next.js app is now sending traces and logs.
+
+---
+
+## Complete Examples
+
+### API Route with Logging
+
+```typescript
+// app/api/users/route.ts
+import { NextRequest, NextResponse } from 'next/server';
+
+export async function GET(request: NextRequest) {
+  console.log('GET /api/users called', {
+    searchParams: Object.fromEntries(request.nextUrl.searchParams),
+    headers: Object.fromEntries(request.headers),
+  });
+  
+  try {
+    const users = await fetchUsersFromDatabase();
+    
+    console.info('Users fetched successfully', {
+      count: users.length,
+      timestamp: new Date().toISOString(),
+    });
+    
+    return NextResponse.json(users);
+  } catch (error) {
+    console.error('Failed to fetch users', {
+      error: error.message,
+      stack: error.stack,
+    });
+    
+    return NextResponse.json(
+      { error: 'Failed to fetch users' },
+      { status: 500 }
+    );
+  }
+}
+
+export async function POST(request: NextRequest) {
+  const body = await request.json();
+  
+  console.info('Creating new user', {
+    email: body.email,
+    name: body.name,
+  });
+  
+  try {
+    // Validation
+    if (!body.email || !body.name) {
+      console.warn('Validation failed', { body });
+      return NextResponse.json(
+        { error: 'Email and name required' },
+        { status: 400 }
+      );
+    }
+    
+    const user = await createUserInDatabase(body);
+    
+    console.log('User created successfully', {
+      userId: user.id,
+      email: user.email,
+    });
+    
+    return NextResponse.json(user, { status: 201 });
+  } catch (error) {
+    console.error('Failed to create user', {
+      error: error.message,
+      body,
+    });
+    
+    return NextResponse.json(
+      { error: 'Failed to create user' },
+      { status: 500 }
+    );
+  }
+}
+```
+
+### Server Component with Logging
+
+```typescript
+// app/dashboard/page.tsx
+export default async function DashboardPage() {
+  console.log('Dashboard page rendering started');
+  
+  try {
+    const data = await fetchDashboardData();
+    
+    console.info('Dashboard data loaded', {
+      itemCount: data.items.length,
+      timestamp: Date.now(),
+    });
+    
+    return (
+      <div>
+        <h1>Dashboard</h1>
+        <div>Items: {data.items.length}</div>
+      </div>
+    );
+  } catch (error) {
+    console.error('Dashboard data fetch failed', {
+      error: error.message,
+      stack: error.stack,
+    });
+    
+    return <div>Error loading dashboard</div>;
+  }
+}
+```
+
+### Server Action with Logging
+
+```typescript
+// app/actions.ts
+'use server';
+
+export async function createUser(formData: FormData) {
+  const name = formData.get('name') as string;
+  const email = formData.get('email') as string;
+  
+  console.info('Form submission received', { name, email });
+  
+  try {
+    const result = await saveUserToDatabase({ name, email });
+    
+    console.log('User saved successfully', {
+      userId: result.id,
+    });
+    
+    return { success: true, id: result.id };
+  } catch (error) {
+    console.error('Form submission failed', {
+      error: error.message,
+      formData: { name, email },
+    });
+    
+    return { success: false, error: error.message };
+  }
+}
+```
+
+### Middleware with Logging
+
+```typescript
+// middleware.ts
+import { NextResponse } from 'next/server';
+import type { NextRequest } from 'next/server';
+
+export function middleware(request: NextRequest) {
+  console.log('Middleware executed', {
+    path: request.nextUrl.pathname,
+    method: request.method,
+    userAgent: request.headers.get('user-agent'),
+  });
+  
+  // Authentication check
+  const token = request.cookies.get('auth-token');
+  
+  if (!token && request.nextUrl.pathname.startsWith('/dashboard')) {
+    console.warn('Unauthorized access attempt', {
+      path: request.nextUrl.pathname,
+      ip: request.ip,
+    });
+    
+    return NextResponse.redirect(new URL('/login', request.url));
+  }
+  
+  console.log('Middleware passed', { path: request.nextUrl.pathname });
+  return NextResponse.next();
+}
+
+export const config = {
+  matcher: ['/dashboard/:path*', '/api/:path*'],
+};
+```
+
+---
+
+## Pages Router Setup (Next.js 12 and below)
+
+### Step 1: Modify `_app.js` or `_app.tsx`
+
+```typescript
+// pages/_app.tsx
+if (typeof window === 'undefined') {
+  // Only run on server-side
+  require('securenow/register');
+  require('securenow/console-instrumentation');
+  console.log('SecureNow initialized');
+}
+
+import type { AppProps } from 'next/app';
+
+function MyApp({ Component, pageProps }: AppProps) {
+  return <Component {...pageProps} />;
+}
+
+export default MyApp;
+```
+
+### Step 2: Create `.env.local`
+
+```env
+SECURENOW_APPID=my-nextjs-app
+SECURENOW_INSTANCE=http://localhost:4318
+SECURENOW_LOGGING_ENABLED=1
+```
+
+### Step 3: Use in API Routes
+
+```typescript
+// pages/api/users.ts
+import type { NextApiRequest, NextApiResponse } from 'next';
+
+export default async function handler(
+  req: NextApiRequest,
+  res: NextApiResponse
+) {
+  console.log('API route called', {
+    method: req.method,
+    query: req.query,
+  });
+  
+  if (req.method === 'GET') {
+    const users = await fetchUsers();
+    console.info('Users fetched', { count: users.length });
+    res.status(200).json(users);
+  } else if (req.method === 'POST') {
+    console.info('Creating user', { body: req.body });
+    const user = await createUser(req.body);
+    console.log('User created', { userId: user.id });
+    res.status(201).json(user);
+  } else {
+    res.status(405).json({ error: 'Method not allowed' });
+  }
+}
+```
+
+### Step 4: Run
+
+```bash
+npm run dev
+```
+
+---
+
+## Environment Variables
+
+### Required
+
+```env
+# Your application identifier
+SECURENOW_APPID=my-nextjs-app
+
+# Your OTLP collector endpoint
+SECURENOW_INSTANCE=http://localhost:4318
+```
+
+### Recommended
+
+```env
+# Enable logging
+SECURENOW_LOGGING_ENABLED=1
+
+# Enable request body capture (for debugging)
+SECURENOW_CAPTURE_BODY=1
+
+# Max body size (default: 10KB)
+SECURENOW_MAX_BODY_SIZE=10240
+
+# Environment name
+NODE_ENV=development
+```
+
+### Optional
+
+```env
+# Authentication headers
+OTEL_EXPORTER_OTLP_HEADERS=x-api-key=your-key
+
+# Disable UUID suffix on service name
+SECURENOW_NO_UUID=1
+
+# Enable debug logging
+OTEL_LOG_LEVEL=debug
+
+# Additional sensitive fields to redact
+SECURENOW_SENSITIVE_FIELDS=internal_token,session_key
+```
+
+---
+
+## Deployment
+
+### Vercel
+
+**Step 1: Ensure instrumentation is set up**
+
+Your `instrumentation.ts` file will be automatically detected by Vercel.
+
+**Step 2: Add environment variables in Vercel Dashboard**
+
+Go to Project Settings → Environment Variables:
+
+```
+SECURENOW_APPID=my-nextjs-app-prod
+SECURENOW_INSTANCE=http://your-collector:4318
+SECURENOW_LOGGING_ENABLED=1
+OTEL_EXPORTER_OTLP_HEADERS=x-api-key=your-key
+```
+
+**Step 3: Deploy**
+
+```bash
+vercel deploy
+```
+
+### Docker
+
+**Dockerfile:**
+
+```dockerfile
+FROM node:20-alpine AS base
+
+# Install dependencies
+FROM base AS deps
+WORKDIR /app
+
+COPY package.json package-lock.json ./
+RUN npm ci
+
+# Build
+FROM base AS builder
+WORKDIR /app
+
+COPY --from=deps /app/node_modules ./node_modules
+COPY . .
+
+RUN npm run build
+
+# Production
+FROM base AS runner
+WORKDIR /app
+
+ENV NODE_ENV=production
+ENV SECURENOW_APPID=my-nextjs-app
+ENV SECURENOW_INSTANCE=http://collector:4318
+ENV SECURENOW_LOGGING_ENABLED=1
+
+COPY --from=builder /app/public ./public
+COPY --from=builder /app/.next/standalone ./
+COPY --from=builder /app/.next/static ./.next/static
+
+EXPOSE 3000
+
+CMD ["node", "server.js"]
+```
+
+**docker-compose.yml:**
+
+```yaml
+version: '3.8'
+
+services:
+  nextjs:
+    build: .
+    ports:
+      - "3000:3000"
+    environment:
+      - SECURENOW_APPID=my-nextjs-app
+      - SECURENOW_INSTANCE=http://collector:4318
+      - SECURENOW_LOGGING_ENABLED=1
+      - SECURENOW_CAPTURE_BODY=1
+      - NODE_ENV=production
+    depends_on:
+      - collector
+
+  collector:
+    image: otel/opentelemetry-collector:latest
+    ports:
+      - "4318:4318"
+```
+
+Run:
+
+```bash
+docker-compose up
+```
+
+---
+
+## Advanced Features
+
+### Request Body Capture
+
+Enable to see request bodies in your traces:
+
+```env
+SECURENOW_CAPTURE_BODY=1
+SECURENOW_MAX_BODY_SIZE=10240
+```
+
+This captures:
+- POST/PUT/PATCH request bodies
+- JSON payloads
+- Form data
+- GraphQL queries
+
+**Note:** File uploads (multipart) are not captured.
+
+### Custom Logger
+
+For more control:
+
+```typescript
+// app/api/custom/route.ts
+import { getLogger } from 'securenow/tracing';
+
+const logger = getLogger('api-handler', '1.0.0');
+
+export async function POST(request: NextRequest) {
+  logger?.emit({
+    severityNumber: 9,
+    severityText: 'INFO',
+    body: 'Custom log message',
+    attributes: {
+      endpoint: '/api/custom',
+      timestamp: Date.now(),
+    },
+  });
+  
+  return NextResponse.json({ success: true });
+}
+```
+
+### Multiple Logger Instances
+
+```typescript
+import { getLogger } from 'securenow/tracing';
+
+const authLogger = getLogger('auth', '1.0.0');
+const dbLogger = getLogger('database', '1.0.0');
+const cacheLogger = getLogger('cache', '1.0.0');
+
+// Use different loggers for different concerns
+authLogger?.emit({ ... });
+dbLogger?.emit({ ... });
+cacheLogger?.emit({ ... });
+```
+
+---
+
+## Troubleshooting
+
+### Instrumentation Not Working
+
+**Check file location:**
+
+`instrumentation.ts` must be in the project root (same level as `app/` or `pages/`), NOT inside `app/` or `src/`.
+
+```
+my-nextjs-app/
+├── app/
+├── instrumentation.ts  ← Here
+├── next.config.js
+└── package.json
+```
+
+**Check next.config.js:**
+
+```javascript
+module.exports = {
+  experimental: {
+    instrumentationHook: true, // This is required!
+  },
+};
+```
+
+**Restart dev server:**
+
+```bash
+# Kill the server completely
+# Then start again
+npm run dev
+```
+
+### Traces Not Appearing
+
+**Enable debug logging:**
+
+```env
+OTEL_LOG_LEVEL=debug
+```
+
+Look for:
+```
+[securenow] OTel SDK started → http://localhost:4318/v1/traces
+```
+
+**Check collector endpoint:**
+
+```bash
+curl http://localhost:4318/v1/traces
+# Should return 200 or 405
+```
+
+### Logs Not Appearing
+
+**Check logging is enabled:**
+
+```env
+SECURENOW_LOGGING_ENABLED=1
+```
+
+**Verify console instrumentation:**
+
+Look for:
+```
+[securenow] Console instrumentation installed
+```
+
+**Check initialization order in instrumentation.ts:**
+
+```typescript
+// ✅ Correct order
+await import('securenow/register');
+await import('securenow/console-instrumentation');
+
+// ❌ Wrong order
+await import('securenow/console-instrumentation');
+await import('securenow/register');
+```
+
+### Duplicate Logs
+
+If you see duplicate logs, check that you're not:
+
+1. Logging both on client and server
+2. Having multiple instances of console instrumentation
+3. Using custom logger AND console instrumentation together
+
+### Build Errors
+
+**Error: Module not found**
+
+Make sure SecureNow is in `dependencies` (not `devDependencies`):
+
+```bash
+npm install securenow
+```
+
+**Webpack warnings:**
+
+If you see webpack warnings about OpenTelemetry modules, ignore them. They're expected and don't affect functionality.
+
+---
+
+## Best Practices
+
+### 1. Use Structured Logging
+
+```typescript
+// ❌ Bad
+console.log('User 123 logged in');
+
+// ✅ Good
+console.log('User logged in', {
+  userId: 123,
+  email: 'user@example.com',
+  timestamp: Date.now(),
+});
+```
+
+### 2. Log in Server Components and API Routes
+
+```typescript
+// app/page.tsx
+export default async function Page() {
+  console.log('Page rendering'); // Logged on server
+  
+  const data = await fetchData();
+  console.info('Data fetched', { count: data.length });
+  
+  return <div>...</div>;
+}
+```
+
+### 3. Don't Log in Client Components
+
+Client-side console logs won't be captured. Only server-side logs are sent.
+
+```typescript
+// app/client-component.tsx
+'use client';
+
+export default function ClientComponent() {
+  // This will NOT be sent to your observability backend
+  console.log('Client-side log');
+  
+  return <div>...</div>;
+}
+```
+
+### 4. Use Different Environments
+
+```env
+# .env.local (development)
+SECURENOW_APPID=my-app-dev
+SECURENOW_INSTANCE=http://localhost:4318
+SECURENOW_CAPTURE_BODY=1
+OTEL_LOG_LEVEL=debug
+
+# .env.production (production)
+SECURENOW_APPID=my-app-prod
+SECURENOW_INSTANCE=http://collector.prod:4318
+SECURENOW_CAPTURE_BODY=0
+OTEL_LOG_LEVEL=error
+```
+
+### 5. Monitor Server Actions
+
+```typescript
+// app/actions.ts
+'use server';
+
+export async function submitForm(data: FormData) {
+  console.info('Form submitted', {
+    fields: Array.from(data.keys()),
+  });
+  
+  try {
+    await processForm(data);
+    console.log('Form processed successfully');
+    return { success: true };
+  } catch (error) {
+    console.error('Form processing failed', { error });
+    return { success: false };
+  }
+}
+```
+
+---
+
+## Complete Environment Variables Reference
+
+```env
+# === Required ===
+SECURENOW_APPID=my-nextjs-app
+SECURENOW_INSTANCE=http://localhost:4318
+
+# === Logging ===
+SECURENOW_LOGGING_ENABLED=1
+
+# === Request Body Capture ===
+SECURENOW_CAPTURE_BODY=1
+SECURENOW_MAX_BODY_SIZE=10240
+SECURENOW_SENSITIVE_FIELDS=custom1,custom2
+
+# === Service Naming ===
+SECURENOW_NO_UUID=1
+OTEL_SERVICE_NAME=my-nextjs-app
+
+# === Connection ===
+OTEL_EXPORTER_OTLP_HEADERS=x-api-key=your-key
+OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4318/v1/traces
+OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://localhost:4318/v1/logs
+
+# === Debugging ===
+OTEL_LOG_LEVEL=debug
+SECURENOW_TEST_SPAN=1
+
+# === Environment ===
+NODE_ENV=development
+```
+
+---
+
+## Performance
+
+- **Minimal overhead:** < 1% CPU impact
+- **Async processing:** No blocking of requests
+- **Server-side only:** Client-side performance unaffected
+- **Production-ready:** Tested with high-traffic applications
+
+---
+
+## Next Steps
+
+- Check your observability backend for traces and logs
+- Set up dashboards for your API routes
+- Create alerts for errors
+- Monitor performance of Server Components
+
+---
+
+## Support
+
+- **Documentation:** [Main Docs](../README.md)
+- **Examples:** [Next.js Examples](../examples/)
+- **Issues:** GitHub Issues
+
+---
+
+**Your Next.js app is now fully observable!** 🎉