securenow 5.0.0 → 5.0.2

package/NPM_README.md

@@ -0,0 +1,1328 @@
+# SecureNow - Complete OpenTelemetry Observability for Node.js
+
+OpenTelemetry instrumentation library for Node.js applications. Send distributed traces and logs to any OTLP-compatible observability backend.
+
+**Features:**
+- 🚀 Zero-config automatic instrumentation
+- 📊 Distributed tracing for all popular frameworks
+- 📋 Automatic logging with console instrumentation
+- 🔐 Built-in sensitive data redaction
+- 🎯 Request body capture for debugging
+- 🔧 Fully configurable via environment variables
+
+---
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Framework-Specific Setup](#framework-specific-setup)
+  - [Express.js](#expressjs)
+  - [Next.js](#nextjs)
+  - [Fastify](#fastify)
+  - [NestJS](#nestjs)
+  - [Koa](#koa)
+  - [Hapi](#hapi)
+- [Environment Variables Reference](#environment-variables-reference)
+- [Logging Setup](#logging-setup)
+- [Request Body Capture](#request-body-capture)
+- [Advanced Configuration](#advanced-configuration)
+- [TypeScript Support](#typescript-support)
+- [Troubleshooting](#troubleshooting)
+
+---
+
+## Installation
+
+```bash
+npm install securenow
+```
+
+Or with yarn:
+
+```bash
+yarn add securenow
+```
+
+---
+
+## Quick Start
+
+### 1. Set Environment Variables
+
+```bash
+# Required: Your application identifier
+export SECURENOW_APPID=my-app
+
+# Required: Your OTLP collector endpoint
+export SECURENOW_INSTANCE=http://your-otlp-collector:4318
+
+# Optional: Enable logging
+export SECURENOW_LOGGING_ENABLED=1
+```
+
+### 2. Initialize in Your Application
+
+**Option A: Using NODE_OPTIONS (Recommended)**
+
+```bash
+NODE_OPTIONS="-r securenow/register" node app.js
+```
+
+**Option B: Code-based initialization**
+
+```javascript
+// At the very top of your main file
+require('securenow/register');
+
+// Your application code
+const express = require('express');
+const app = express();
+// ...
+```
+
+### 3. Run Your Application
+
+```bash
+node app.js
+```
+
+You'll see confirmation in the console:
+
+```
+[securenow] OTel SDK started → http://your-otlp-collector:4318/v1/traces
+[securenow] 📝 Request body capture: ENABLED
+```
+
+---
+
+## Framework-Specific Setup
+
+### Express.js
+
+#### Basic Tracing Setup
+
+**Step 1: Install**
+
+```bash
+npm install securenow express
+```
+
+**Step 2: Create `.env` file**
+
+```env
+SECURENOW_APPID=my-express-app
+SECURENOW_INSTANCE=http://localhost:4318
+SECURENOW_LOGGING_ENABLED=1
+```
+
+**Step 3: Initialize at the top of your main file**
+
+```javascript
+// app.js or server.js
+require('securenow/register');
+require('securenow/console-instrumentation'); // Optional: for automatic logging
+
+const express = require('express');
+const app = express();
+
+app.use(express.json());
+
+app.get('/', (req, res) => {
+  console.log('Home page accessed'); // Automatically logged if console-instrumentation is enabled
+  res.send('Hello World');
+});
+
+app.post('/api/users', (req, res) => {
+  console.info('User created', { userId: 123 });
+  res.json({ success: true });
+});
+
+const PORT = process.env.PORT || 3000;
+app.listen(PORT, () => {
+  console.log(`Server running on port ${PORT}`);
+});
+```
+
+**Step 4: Run**
+
+```bash
+# With NODE_OPTIONS
+NODE_OPTIONS="-r securenow/register -r securenow/console-instrumentation" node app.js
+
+# Or directly (if you added require statements)
+node app.js
+```
+
+#### With PM2
+
+```javascript
+// ecosystem.config.js
+module.exports = {
+  apps: [{
+    name: 'my-app',
+    script: './app.js',
+    instances: 4,
+    exec_mode: 'cluster',
+    node_args: '-r securenow/register -r securenow/console-instrumentation',
+    env: {
+      SECURENOW_APPID: 'my-express-app',
+      SECURENOW_INSTANCE: 'http://localhost:4318',
+      SECURENOW_LOGGING_ENABLED: '1',
+      SECURENOW_NO_UUID: '1', // Use same service name across all instances
+      SECURENOW_CAPTURE_BODY: '1' // Enable request body capture
+    }
+  }]
+};
+```
+
+```bash
+pm2 start ecosystem.config.js
+```
+
+---
+
+### Next.js
+
+#### App Router (Next.js 13+)
+
+**Step 1: Install**
+
+```bash
+npm install securenow
+```
+
+**Step 2: Create `instrumentation.ts` (or `.js`) in your project root**
+
+```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 in `next.config.js`**
+
+```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
+```
+
+**Step 5: Use in your application**
+
+```typescript
+// app/api/users/route.ts
+import { NextRequest, NextResponse } from 'next/server';
+
+export async function GET(request: NextRequest) {
+  console.log('GET /api/users called');
+  
+  // Your logic here
+  const users = await fetchUsers();
+  
+  console.info('Users fetched', { count: users.length });
+  return NextResponse.json(users);
+}
+
+export async function POST(request: NextRequest) {
+  const body = await request.json();
+  console.info('Creating user', { email: body.email });
+  
+  try {
+    const user = await createUser(body);
+    console.log('User created successfully', { userId: user.id });
+    return NextResponse.json(user, { status: 201 });
+  } catch (error) {
+    console.error('Failed to create user', { error: error.message });
+    return NextResponse.json({ error: 'Failed' }, { status: 500 });
+  }
+}
+```
+
+**Step 6: Run**
+
+```bash
+npm run dev
+```
+
+#### Pages Router (Next.js 12 and below)
+
+**Step 1: Create `_app.js` or `_app.tsx`**
+
+```javascript
+// pages/_app.js
+if (typeof window === 'undefined') {
+  require('securenow/register');
+  require('securenow/console-instrumentation');
+}
+
+function MyApp({ Component, pageProps }) {
+  return <Component {...pageProps} />;
+}
+
+export default MyApp;
+```
+
+**Step 2: Same `.env.local` as above**
+
+**Step 3: Run**
+
+```bash
+npm run dev
+```
+
+---
+
+### Fastify
+
+**Step 1: Install**
+
+```bash
+npm install securenow fastify
+```
+
+**Step 2: Create `.env`**
+
+```env
+SECURENOW_APPID=my-fastify-app
+SECURENOW_INSTANCE=http://localhost:4318
+SECURENOW_LOGGING_ENABLED=1
+```
+
+**Step 3: Initialize at the top**
+
+```javascript
+// server.js
+require('securenow/register');
+require('securenow/console-instrumentation');
+
+const fastify = require('fastify')({ logger: false });
+
+// Logging hook
+fastify.addHook('onRequest', async (request, reply) => {
+  console.info('Request received', {
+    method: request.method,
+    url: request.url,
+  });
+});
+
+fastify.get('/', async (request, reply) => {
+  console.log('Root endpoint called');
+  return { hello: 'world' };
+});
+
+fastify.post('/users', async (request, reply) => {
+  console.info('Creating user', { body: request.body });
+  // Your logic
+  return { success: true };
+});
+
+// Error handler
+fastify.setErrorHandler((error, request, reply) => {
+  console.error('Fastify error', {
+    error: error.message,
+    stack: error.stack,
+    url: request.url,
+  });
+  reply.status(500).send({ error: 'Internal server error' });
+});
+
+const start = async () => {
+  try {
+    await fastify.listen({ port: 3000 });
+    console.log('Fastify server running on port 3000');
+  } catch (err) {
+    console.error('Server start failed', { error: err });
+    process.exit(1);
+  }
+};
+
+start();
+```
+
+**Step 4: Run**
+
+```bash
+node server.js
+```
+
+---
+
+### NestJS
+
+**Step 1: Install**
+
+```bash
+npm install securenow
+```
+
+**Step 2: Create `.env`**
+
+```env
+SECURENOW_APPID=my-nestjs-app
+SECURENOW_INSTANCE=http://localhost:4318
+SECURENOW_LOGGING_ENABLED=1
+```
+
+**Step 3: Initialize in `main.ts`**
+
+```typescript
+// src/main.ts
+require('securenow/register');
+require('securenow/console-instrumentation');
+
+import { NestFactory } from '@nestjs/core';
+import { AppModule } from './app.module';
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule);
+  
+  console.log('NestJS application starting');
+  
+  await app.listen(3000);
+  console.log('Application is running on: http://localhost:3000');
+}
+
+bootstrap();
+```
+
+**Step 4: Use in services**
+
+```typescript
+// src/users/users.service.ts
+import { Injectable } from '@nestjs/common';
+
+@Injectable()
+export class UsersService {
+  async findAll() {
+    console.log('Fetching all users');
+    const users = await this.fetchFromDatabase();
+    console.info('Users retrieved', { count: users.length });
+    return users;
+  }
+  
+  async create(userData: any) {
+    console.info('Creating user', { email: userData.email });
+    
+    try {
+      const user = await this.saveToDatabase(userData);
+      console.log('User created', { userId: user.id });
+      return user;
+    } catch (error) {
+      console.error('Failed to create user', {
+        error: error.message,
+        email: userData.email,
+      });
+      throw error;
+    }
+  }
+}
+```
+
+**Step 5: Run**
+
+```bash
+npm run start
+```
+
+---
+
+### Koa
+
+**Step 1: Install**
+
+```bash
+npm install securenow koa
+```
+
+**Step 2: Create `.env`**
+
+```env
+SECURENOW_APPID=my-koa-app
+SECURENOW_INSTANCE=http://localhost:4318
+SECURENOW_LOGGING_ENABLED=1
+```
+
+**Step 3: Initialize**
+
+```javascript
+// app.js
+require('securenow/register');
+require('securenow/console-instrumentation');
+
+const Koa = require('koa');
+const Router = require('@koa/router');
+
+const app = new Koa();
+const router = new Router();
+
+// Logging middleware
+app.use(async (ctx, next) => {
+  console.info('Request received', {
+    method: ctx.method,
+    path: ctx.path,
+  });
+  await next();
+});
+
+router.get('/', (ctx) => {
+  console.log('Home page accessed');
+  ctx.body = { message: 'Hello World' };
+});
+
+router.post('/users', (ctx) => {
+  console.info('Creating user', { body: ctx.request.body });
+  ctx.body = { success: true };
+});
+
+app.use(router.routes());
+
+const PORT = 3000;
+app.listen(PORT, () => {
+  console.log(`Koa server running on port ${PORT}`);
+});
+```
+
+**Step 4: Run**
+
+```bash
+node app.js
+```
+
+---
+
+### Hapi
+
+**Step 1: Install**
+
+```bash
+npm install securenow @hapi/hapi
+```
+
+**Step 2: Create `.env`**
+
+```env
+SECURENOW_APPID=my-hapi-app
+SECURENOW_INSTANCE=http://localhost:4318
+SECURENOW_LOGGING_ENABLED=1
+```
+
+**Step 3: Initialize**
+
+```javascript
+// server.js
+require('securenow/register');
+require('securenow/console-instrumentation');
+
+const Hapi = require('@hapi/hapi');
+
+const init = async () => {
+  const server = Hapi.server({
+    port: 3000,
+    host: 'localhost'
+  });
+
+  // Logging extension
+  server.ext('onRequest', (request, h) => {
+    console.info('Request received', {
+      method: request.method,
+      path: request.path,
+    });
+    return h.continue;
+  });
+
+  server.route({
+    method: 'GET',
+    path: '/',
+    handler: (request, h) => {
+      console.log('Home page accessed');
+      return { message: 'Hello World' };
+    }
+  });
+
+  server.route({
+    method: 'POST',
+    path: '/users',
+    handler: (request, h) => {
+      console.info('Creating user', { payload: request.payload });
+      return { success: true };
+    }
+  });
+
+  await server.start();
+  console.log('Hapi server running on:', server.info.uri);
+};
+
+init();
+```
+
+**Step 4: Run**
+
+```bash
+node server.js
+```
+
+---
+
+## Environment Variables Reference
+
+### Required Variables
+
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `SECURENOW_APPID` | Your application identifier. Used as the service name in traces. | `my-app` |
+| `SECURENOW_INSTANCE` | Base URL of your OTLP collector endpoint. | `http://localhost:4318` |
+
+### Optional Configuration
+
+#### Service Naming
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `OTEL_SERVICE_NAME` | Alternative to SECURENOW_APPID. Standard OpenTelemetry variable. | - |
+| `SECURENOW_NO_UUID` | Set to `1` to disable UUID suffix on service name. Useful for clustered apps. | `0` |
+| `SECURENOW_STRICT` | Set to `1` to exit process if SECURENOW_APPID is not set in cluster mode. | `0` |
+
+#### Connection Settings
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | Alternative to SECURENOW_INSTANCE. Standard OpenTelemetry variable. | - |
+| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` | Override traces endpoint specifically. | `{SECURENOW_INSTANCE}/v1/traces` |
+| `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` | Override logs endpoint specifically. | `{SECURENOW_INSTANCE}/v1/logs` |
+| `OTEL_EXPORTER_OTLP_HEADERS` | Headers to send with OTLP exports. Format: `key1=value1,key2=value2` | - |
+
+#### Logging
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `SECURENOW_LOGGING_ENABLED` | Enable automatic logging to OTLP backend. Set to `1` to enable, `0` to disable. | `1` |
+
+#### Request Body Capture
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `SECURENOW_CAPTURE_BODY` | Enable request body capture in traces. Set to `1` to enable. | `0` |
+| `SECURENOW_MAX_BODY_SIZE` | Maximum body size to capture in bytes. Bodies larger than this are truncated. | `10240` (10KB) |
+| `SECURENOW_SENSITIVE_FIELDS` | Comma-separated list of additional field names to redact. | - |
+
+**Default sensitive fields (auto-redacted):** `password`, `passwd`, `pwd`, `secret`, `token`, `api_key`, `apikey`, `access_token`, `auth`, `credentials`, `mysql_pwd`, `stripeToken`, `card`, `cardnumber`, `ccv`, `cvc`, `cvv`, `ssn`, `pin`
+
+#### Instrumentation Control
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `SECURENOW_DISABLE_INSTRUMENTATIONS` | Comma-separated list of instrumentation packages to disable. | - |
+
+**Example:** `SECURENOW_DISABLE_INSTRUMENTATIONS=fs,dns` disables filesystem and DNS instrumentations.
+
+#### Debugging
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `OTEL_LOG_LEVEL` | OpenTelemetry SDK log level. Options: `debug`, `info`, `warn`, `error` | `none` |
+| `SECURENOW_TEST_SPAN` | Set to `1` to emit a test span on startup. | `0` |
+
+#### Environment
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `NODE_ENV` | Deployment environment name. Sent as `deployment.environment` attribute. | `production` |
+
+---
+
+## Logging Setup
+
+### Automatic Console Logging
+
+The easiest way to send logs is to use the console instrumentation wrapper:
+
+```javascript
+// At the top of your main file
+require('securenow/register');
+require('securenow/console-instrumentation');
+
+// Now all console logs are automatically sent
+console.log('Application started');
+console.info('User action', { userId: 123, action: 'login' });
+console.warn('Deprecation warning');
+console.error('Error occurred', { error: 'Something failed' });
+console.debug('Debug info');
+```
+
+**Severity mapping:**
+- `console.log()` → INFO
+- `console.info()` → INFO
+- `console.warn()` → WARN
+- `console.error()` → ERROR
+- `console.debug()` → DEBUG
+
+**Environment variable:**
+```bash
+SECURENOW_LOGGING_ENABLED=1
+```
+
+### Direct Logger API
+
+For more control, use the OpenTelemetry logger API:
+
+```javascript
+require('securenow/register');
+const { getLogger } = require('securenow/tracing');
+
+// Get a logger instance
+const logger = getLogger('my-module', '1.0.0');
+
+// Emit structured logs
+logger.emit({
+  severityNumber: 9,      // INFO
+  severityText: 'INFO',
+  body: 'User logged in',
+  attributes: {
+    userId: 123,
+    username: 'john',
+    sessionId: 'abc123',
+  },
+});
+```
+
+**Severity numbers:**
+- `5` - DEBUG
+- `9` - INFO
+- `13` - WARN
+- `17` - ERROR
+
+### Using with NODE_OPTIONS
+
+```bash
+# Enable both tracing and logging
+NODE_OPTIONS="-r securenow/register -r securenow/console-instrumentation" \
+SECURENOW_APPID=my-app \
+SECURENOW_INSTANCE=http://localhost:4318 \
+SECURENOW_LOGGING_ENABLED=1 \
+node app.js
+```
+
+---
+
+## Request Body Capture
+
+SecureNow can capture HTTP request bodies in traces for debugging purposes. This is disabled by default.
+
+### Enable Body Capture
+
+```bash
+export SECURENOW_CAPTURE_BODY=1
+export SECURENOW_MAX_BODY_SIZE=10240  # 10KB (optional)
+```
+
+### Supported Content Types
+
+- `application/json`
+- `application/x-www-form-urlencoded`
+- `application/graphql`
+
+**Note:** Multipart form data (file uploads) are NOT captured by design.
+
+### Sensitive Data Redaction
+
+All request bodies are automatically scanned and sensitive fields are redacted:
+
+**Automatically redacted fields:** `password`, `secret`, `token`, `api_key`, `card`, `cvv`, `ssn`, and more.
+
+**Add custom fields to redact:**
+
+```bash
+export SECURENOW_SENSITIVE_FIELDS="custom_secret,internal_token"
+```
+
+### Example
+
+```javascript
+// POST /api/users with body:
+{
+  "email": "user@example.com",
+  "password": "secret123",
+  "name": "John Doe"
+}
+
+// Captured in trace as:
+{
+  "email": "user@example.com",
+  "password": "[REDACTED]",
+  "name": "John Doe"
+}
+```
+
+---
+
+## Advanced Configuration
+
+### Complete Example with All Options
+
+```bash
+# Service identification
+export SECURENOW_APPID=my-production-app
+export SECURENOW_NO_UUID=1
+export SECURENOW_STRICT=1
+
+# OTLP backend
+export SECURENOW_INSTANCE=http://collector.example.com:4318
+export OTEL_EXPORTER_OTLP_HEADERS="x-api-key=your-api-key"
+
+# Logging
+export SECURENOW_LOGGING_ENABLED=1
+
+# Request body capture
+export SECURENOW_CAPTURE_BODY=1
+export SECURENOW_MAX_BODY_SIZE=20480
+export SECURENOW_SENSITIVE_FIELDS="internal_id,session_key"
+
+# Environment
+export NODE_ENV=production
+
+# Debugging
+export OTEL_LOG_LEVEL=info
+
+# Disable specific instrumentations
+export SECURENOW_DISABLE_INSTRUMENTATIONS=fs,dns
+
+# Run application
+NODE_OPTIONS="-r securenow/register -r securenow/console-instrumentation" node app.js
+```
+
+### Using Multiple Logger Instances
+
+```javascript
+const { getLogger } = require('securenow/tracing');
+
+const authLogger = getLogger('auth-service', '1.0.0');
+const dbLogger = getLogger('database', '1.0.0');
+const apiLogger = getLogger('api-handler', '1.0.0');
+
+authLogger.emit({
+  severityNumber: 9,
+  severityText: 'INFO',
+  body: 'User authenticated',
+  attributes: { userId: 123 },
+});
+
+dbLogger.emit({
+  severityNumber: 13,
+  severityText: 'WARN',
+  body: 'Slow query detected',
+  attributes: { queryTime: 5000 },
+});
+```
+
+### Check if Logging is Enabled
+
+```javascript
+const { isLoggingEnabled } = require('securenow/tracing');
+
+if (isLoggingEnabled()) {
+  console.log('Logging is enabled');
+} else {
+  console.log('Logging is disabled');
+}
+```
+
+### Programmatic Configuration
+
+While environment variables are recommended, you can also configure programmatically:
+
+```javascript
+// Set environment variables before requiring securenow
+process.env.SECURENOW_APPID = 'my-app';
+process.env.SECURENOW_INSTANCE = 'http://localhost:4318';
+process.env.SECURENOW_LOGGING_ENABLED = '1';
+
+// Then initialize
+require('securenow/register');
+require('securenow/console-instrumentation');
+```
+
+---
+
+## TypeScript Support
+
+SecureNow includes full TypeScript definitions.
+
+### Type Definitions
+
+```typescript
+import { getLogger, isLoggingEnabled, Logger, LogRecord } from 'securenow/tracing';
+
+// Get a typed logger
+const logger: Logger | null = getLogger('my-service', '1.0.0');
+
+// Emit a log with type checking
+if (logger) {
+  const logRecord: LogRecord = {
+    severityNumber: 9,
+    severityText: 'INFO',
+    body: 'User action',
+    attributes: {
+      userId: 123,
+      action: 'login',
+    },
+  };
+  
+  logger.emit(logRecord);
+}
+
+// Check if enabled
+const enabled: boolean = isLoggingEnabled();
+```
+
+### Next.js with TypeScript
+
+```typescript
+// instrumentation.ts
+export async function register() {
+  if (process.env.NEXT_RUNTIME === 'nodejs') {
+    process.env.SECURENOW_LOGGING_ENABLED = '1';
+    
+    await import('securenow/register');
+    await import('securenow/console-instrumentation');
+  }
+}
+```
+
+### NestJS with TypeScript
+
+```typescript
+// main.ts
+require('securenow/register');
+require('securenow/console-instrumentation');
+
+import { NestFactory } from '@nestjs/core';
+import { AppModule } from './app.module';
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule);
+  await app.listen(3000);
+}
+
+bootstrap();
+```
+
+---
+
+## Troubleshooting
+
+### Traces Not Appearing
+
+**Check 1: Verify environment variables**
+
+```bash
+echo $SECURENOW_APPID
+echo $SECURENOW_INSTANCE
+```
+
+Both should output values.
+
+**Check 2: Verify OTLP collector is running**
+
+```bash
+curl http://localhost:4318/v1/traces
+# Should return 200 or 405 (method not allowed)
+```
+
+**Check 3: Enable debug logging**
+
+```bash
+export OTEL_LOG_LEVEL=debug
+node app.js
+```
+
+Look for lines like:
+```
+[securenow] OTel SDK started → http://localhost:4318/v1/traces
+```
+
+**Check 4: Verify initialization order**
+
+SecureNow must be required BEFORE any other modules:
+
+```javascript
+// ✅ Correct
+require('securenow/register');
+const express = require('express');
+
+// ❌ Wrong - too late!
+const express = require('express');
+require('securenow/register');
+```
+
+### Logs Not Appearing
+
+**Check 1: Is logging enabled?**
+
+```bash
+echo $SECURENOW_LOGGING_ENABLED
+# Should output: 1
+```
+
+**Check 2: Verify console instrumentation is loaded**
+
+```javascript
+// Must load after register
+require('securenow/register');
+require('securenow/console-instrumentation');
+```
+
+**Check 3: Check console output**
+
+You should see:
+```
+[securenow] 📋 Logging: ENABLED → http://localhost:4318/v1/logs
+[securenow] Console instrumentation installed
+```
+
+**Check 4: Verify OTLP logs endpoint**
+
+```bash
+curl http://localhost:4318/v1/logs
+# Should return 200 or 405
+```
+
+### Request Body Not Captured
+
+**Check 1: Is body capture enabled?**
+
+```bash
+export SECURENOW_CAPTURE_BODY=1
+```
+
+**Check 2: Verify content type**
+
+Body capture only works for:
+- `application/json`
+- `application/x-www-form-urlencoded`
+- `application/graphql`
+
+**Check 3: Check body size**
+
+Bodies larger than `SECURENOW_MAX_BODY_SIZE` are truncated:
+
+```bash
+export SECURENOW_MAX_BODY_SIZE=20480  # Increase to 20KB
+```
+
+### High Memory Usage
+
+**Option 1: Disable body capture**
+
+```bash
+export SECURENOW_CAPTURE_BODY=0
+```
+
+**Option 2: Reduce body size limit**
+
+```bash
+export SECURENOW_MAX_BODY_SIZE=5120  # 5KB
+```
+
+**Option 3: Disable specific instrumentations**
+
+```bash
+export SECURENOW_DISABLE_INSTRUMENTATIONS=fs,dns,net
+```
+
+### Next.js Instrumentation Not Working
+
+**Check 1: Verify instrumentation file location**
+
+`instrumentation.ts` or `instrumentation.js` must be in the project root (same level as `app/` or `pages/`).
+
+**Check 2: Enable instrumentation hook**
+
+```javascript
+// next.config.js
+module.exports = {
+  experimental: {
+    instrumentationHook: true,
+  },
+};
+```
+
+**Check 3: Restart dev server**
+
+```bash
+# Kill the server and restart
+npm run dev
+```
+
+### PM2 Cluster Issues
+
+**Problem: Different service names for each worker**
+
+**Solution: Use SECURENOW_NO_UUID**
+
+```bash
+export SECURENOW_NO_UUID=1
+```
+
+This uses the same service name for all workers.
+
+**Problem: Workers not instrumented**
+
+**Solution: Use node_args in PM2 config**
+
+```javascript
+// ecosystem.config.js
+module.exports = {
+  apps: [{
+    name: 'my-app',
+    script: './app.js',
+    instances: 4,
+    node_args: '-r securenow/register',
+    env: {
+      SECURENOW_APPID: 'my-app',
+      SECURENOW_INSTANCE: 'http://localhost:4318',
+    }
+  }]
+};
+```
+
+---
+
+## Best Practices
+
+### 1. Use Environment Variables
+
+Don't hardcode configuration. Use environment variables:
+
+```javascript
+// ❌ Bad
+process.env.SECURENOW_APPID = 'hardcoded-value';
+
+// ✅ Good - use .env file or export
+// .env
+SECURENOW_APPID=my-app
+SECURENOW_INSTANCE=http://localhost:4318
+```
+
+### 2. Use Structured Logging
+
+Pass objects to console methods for better filtering:
+
+```javascript
+// ❌ Less useful
+console.log('User 123 logged in');
+
+// ✅ Better - structured attributes
+console.log('User logged in', {
+  userId: 123,
+  email: 'user@example.com',
+  timestamp: new Date().toISOString(),
+});
+```
+
+### 3. Choose Appropriate Severity Levels
+
+```javascript
+// Normal operations
+console.log('Request processed');
+console.info('User created', { userId: 123 });
+
+// Warnings
+console.warn('API rate limit approaching', { remaining: 10 });
+
+// Errors
+console.error('Database connection failed', { error: err.message });
+
+// Debug (only in development)
+console.debug('Cache hit', { key: 'user:123' });
+```
+
+### 4. Don't Log Sensitive Data
+
+Even though SecureNow automatically redacts common sensitive fields, avoid logging:
+
+```javascript
+// ❌ Bad
+console.log('Login attempt', {
+  email: 'user@example.com',
+  password: 'secret123', // Will be redacted, but don't log it!
+});
+
+// ✅ Good
+console.log('Login attempt', {
+  email: 'user@example.com',
+  timestamp: Date.now(),
+});
+```
+
+### 5. Use Different Logger Instances for Different Modules
+
+```javascript
+// auth-service.js
+const authLogger = getLogger('auth-service', '1.0.0');
+
+// database.js
+const dbLogger = getLogger('database', '1.0.0');
+
+// api.js
+const apiLogger = getLogger('api', '1.0.0');
+```
+
+### 6. Enable Body Capture Only in Development
+
+```bash
+# .env.development
+SECURENOW_CAPTURE_BODY=1
+
+# .env.production
+SECURENOW_CAPTURE_BODY=0
+```
+
+---
+
+## Supported Runtimes
+
+- **Node.js:** 18+
+- **Frameworks:** Express, Next.js, Fastify, NestJS, Koa, Hapi, and more
+- **Databases:** PostgreSQL, MySQL, MongoDB, Redis
+- **HTTP Clients:** axios, fetch, node-fetch, got, request
+- **GraphQL:** Apollo Server, GraphQL.js
+- **Message Queues:** Redis, BullMQ
+- **And many more via OpenTelemetry auto-instrumentation**
+
+---
+
+## Automatic Instrumentations
+
+SecureNow automatically instruments:
+
+- HTTP/HTTPS (incoming and outgoing)
+- Express.js
+- Fastify
+- Koa
+- Hapi
+- Next.js
+- PostgreSQL
+- MySQL/MySQL2
+- MongoDB
+- Redis
+- GraphQL
+- gRPC
+- DNS
+- File System
+- And 50+ more libraries
+
+No code changes needed!
+
+---
+
+## Architecture
+
+```
+┌─────────────────────────────────┐
+│   Your Application              │
+│   (Express/Next.js/etc)         │
+└───────────────┬─────────────────┘
+                │
+                ▼
+┌─────────────────────────────────┐
+│   SecureNow Library             │
+│   - Auto-instrumentation        │
+│   - Console wrapper (optional)  │
+│   - Body capture (optional)     │
+└───────────────┬─────────────────┘
+                │
+                ▼
+┌─────────────────────────────────┐
+│   OpenTelemetry SDK             │
+│   - Trace/Log processors        │
+│   - OTLP exporters              │
+└───────────────┬─────────────────┘
+                │
+                ▼
+┌─────────────────────────────────┐
+│   OTLP Collector/Backend        │
+│   (Your observability platform) │
+└─────────────────────────────────┘
+```
+
+---
+
+## Performance
+
+- **Minimal overhead:** < 1% CPU and memory impact
+- **Batch export:** Traces and logs are batched before sending
+- **Async processing:** No blocking of application threads
+- **Configurable:** Disable instrumentations you don't need
+
+---
+
+## Security
+
+- **Automatic redaction** of sensitive fields (passwords, tokens, keys)
+- **Configurable** sensitive field patterns
+- **No data stored** locally - everything sent to your OTLP backend
+- **Open source** - audit the code yourself
+
+---
+
+## License
+
+ISC
+
+---
+
+## Support
+
+- **Documentation:** [GitHub Docs](https://github.com/your-repo/securenow-npm/tree/main/docs)
+- **Issues:** [GitHub Issues](https://github.com/your-repo/securenow-npm/issues)
+- **Examples:** [GitHub Examples](https://github.com/your-repo/securenow-npm/tree/main/examples)
+
+---
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for version history.
+
+---
+
+## Contributing
+
+Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+---
+
+## Related Packages
+
+- [@opentelemetry/sdk-node](https://www.npmjs.com/package/@opentelemetry/sdk-node) - Core OpenTelemetry SDK
+- [@opentelemetry/auto-instrumentations-node](https://www.npmjs.com/package/@opentelemetry/auto-instrumentations-node) - Auto-instrumentation
+- [@opentelemetry/exporter-trace-otlp-http](https://www.npmjs.com/package/@opentelemetry/exporter-trace-otlp-http) - OTLP exporter
+
+---
+
+**Made with ❤️ for the Node.js community**