securenow 5.6.0 → 5.7.0

package/NPM_README.md

@@ -1,1609 +1,1594 @@
-# 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)
-- [CLI — Command Line Interface](#cli--command-line-interface)
-- [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
-```
-
----
-
-## CLI — Command Line Interface
-
-The `securenow` CLI gives you full access to the SecureNow platform from the terminal — no browser required for day-to-day workflows. Zero additional dependencies.
-
-### Getting Started
-
-```bash
-# Log in (opens browser for OAuth)
-npx securenow login
-
-# Or use a token for CI/headless environments
-npx securenow login --token <YOUR_JWT>
-
-# Check who you're logged in as
-npx securenow whoami
-```
-
-### Managing Applications
-
-```bash
-# List all applications
-npx securenow apps
-
-# Create a new application
-npx securenow apps create my-production-app --hosts api.example.com,app.example.com
-
-# Get application details (including the app key)
-npx securenow apps info <app-id>
-
-# Set a default app so you don't need --app on every command
-npx securenow apps default <app-key>
-
-# Delete an application
-npx securenow apps delete <app-id> --force
-```
-
-### Viewing Traces
-
-```bash
-# List recent traces (uses default app, or specify --app)
-npx securenow traces
-npx securenow traces --app <key> --limit 50
-
-# Show detailed spans for a trace
-npx securenow traces show <traceId>
-
-# AI-powered security analysis of a trace
-npx securenow traces analyze <traceId>
-```
-
-### Viewing Logs
-
-```bash
-# List recent logs
-npx securenow logs
-npx securenow logs --app <key> --minutes 30 --level error
-
-# Show logs for a specific trace
-npx securenow logs trace <traceId>
-```
-
-### Security Issues
-
-```bash
-# List all issues
-npx securenow issues
-npx securenow issues --status open
-
-# Show issue details with AI analysis
-npx securenow issues show <issue-id>
-
-# Resolve an issue
-npx securenow issues resolve <issue-id>
-```
-
-### Notifications
-
-```bash
-# List notifications
-npx securenow notifications
-
-# Check unread count
-npx securenow notifications unread
-
-# Mark as read
-npx securenow notifications read <id>
-npx securenow notifications read-all
-```
-
-### Alerting
-
-```bash
-# View alert rules, channels, and history
-npx securenow alerts rules
-npx securenow alerts channels
-npx securenow alerts history --limit 20
-```
-
-### IP Intelligence & Blocklist
-
-```bash
-# Look up any IP — geo, abuse score, verdict, risk factors
-npx securenow ip 203.0.113.42
-
-# Show traces from a specific IP
-npx securenow ip traces 203.0.113.42
-
-# Manage the blocklist
-npx securenow blocklist
-npx securenow blocklist add 203.0.113.42 --reason "Brute force scanner"
-npx securenow blocklist remove <id>
-npx securenow blocklist stats
-
-# Manage trusted IPs
-npx securenow trusted
-npx securenow trusted add 10.0.0.1 --label "Office VPN"
-npx securenow trusted remove <id>
-```
-
-### Forensic Queries
-
-Ask questions in plain English — the AI translates them to SQL and runs them against your data.
-
-```bash
-# Run a forensic query
-npx securenow forensics "show top 10 attacking IPs in the last hour"
-npx securenow forensics "which endpoints had 5xx errors today"
-
-# Browse the saved query library
-npx securenow forensics library
-```
-
-### API Map
-
-```bash
-# View all discovered API endpoints
-npx securenow api-map
-
-# API map statistics
-npx securenow api-map stats
-```
-
-### Analytics & Dashboard
-
-```bash
-# Response code analytics
-npx securenow analytics --app <key>
-
-# Full dashboard overview (apps, protection status, unread alerts)
-npx securenow status
-```
-
-### Instances
-
-```bash
-# List ClickHouse instances
-npx securenow instances
-
-# Test an instance connection
-npx securenow instances test <id>
-```
-
-### Configuration
-
-```bash
-# View all config
-npx securenow config get
-
-# Set values
-npx securenow config set apiUrl https://custom-api.example.com
-npx securenow config set defaultApp <app-key>
-npx securenow config set format json
-
-# Show config file paths
-npx securenow config path
-```
-
-Config files are stored in `~/.securenow/`:
-
-| File | Description |
-|------|-------------|
-| `config.json` | API URL, default app, output format |
-| `credentials.json` | Auth token (file permissions: 0600) |
-
-### Initialize Instrumentation
-
-```bash
-# Interactive setup — creates instrumentation files for Next.js
-npx securenow init
-npx securenow init --ts --src --force
-```
-
-### Global Flags
-
-Every command supports these flags:
-
-| Flag | Short | Description |
-|------|-------|-------------|
-| `--json` | `-j` | Output as JSON for scripting and CI/CD |
-| `--help` | | Show help for the command |
-| `--app <key>` | | Override the default application key |
-
-### Environment Variables
-
-| Variable | Description |
-|----------|-------------|
-| `SECURENOW_API_URL` | Override the API base URL |
-| `SECURENOW_DEBUG` | Show stack traces on errors |
-| `NO_COLOR` | Disable colored output |
-
-### CI/CD Integration
-
-```bash
-# Authenticate with a token in CI
-npx securenow login --token $SECURENOW_TOKEN
-
-# Use --json for machine-readable output
-npx securenow issues --json | jq '.[] | select(.severity == "critical")'
-
-# Check for critical issues in a pipeline
-ISSUES=$(npx securenow issues --json --status open)
-CRITICAL=$(echo "$ISSUES" | jq '[.[] | select(.severity == "critical")] | length')
-if [ "$CRITICAL" -gt "0" ]; then
-  echo "Found $CRITICAL critical issues!"
-  exit 1
-fi
-```
-
-### Complete Command Reference
-
-| Category | Command | Description |
-|----------|---------|-------------|
-| **Auth** | `login` | Authenticate via browser or `--token` |
-| | `logout` | Clear credentials |
-| | `whoami` | Show session info |
-| **Apps** | `apps` | List applications |
-| | `apps create <name>` | Create application |
-| | `apps info <id>` | Application details |
-| | `apps delete <id>` | Delete application |
-| | `apps default <key>` | Set default app |
-| **Observe** | `traces` | List traces |
-| | `traces show <id>` | Trace details |
-| | `traces analyze <id>` | AI trace analysis |
-| | `logs` | List logs |
-| | `logs trace <id>` | Logs for a trace |
-| | `analytics` | Response analytics |
-| | `status` | Dashboard overview |
-| **Detect** | `issues` | List issues |
-| | `issues show <id>` | Issue details |
-| | `issues resolve <id>` | Resolve issue |
-| | `notifications` | List notifications |
-| | `notifications unread` | Unread count |
-| | `notifications read <id>` | Mark read |
-| | `notifications read-all` | Mark all read |
-| | `alerts rules` | Alert rules |
-| | `alerts channels` | Alert channels |
-| | `alerts history` | Alert history |
-| **Investigate** | `ip <addr>` | IP intelligence |
-| | `ip traces <addr>` | Traces from IP |
-| | `forensics "<query>"` | NL forensic query |
-| | `forensics library` | Saved queries |
-| | `api-map` | API endpoints |
-| | `api-map stats` | API stats |
-| **Remediate** | `blocklist` | Blocked IPs |
-| | `blocklist add <ip>` | Block IP |
-| | `blocklist remove <id>` | Unblock IP |
-| | `blocklist stats` | Block stats |
-| | `trusted` | Trusted IPs |
-| | `trusted add <ip>` | Add trusted IP |
-| | `trusted remove <id>` | Remove trusted |
-| **Settings** | `instances` | List instances |
-| | `instances test <id>` | Test connection |
-| | `config get` | Show config |
-| | `config set <k> <v>` | Set config value |
-| | `config path` | Config file paths |
-| | `init` | Setup instrumentation |
-| | `version` | Show version |
-
----
-
-## 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**
+# SecureNow - Complete OpenTelemetry Observability for Node.js
+
+OpenTelemetry instrumentation library for Node.js, Next.js, and Nuxt 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
+- 🖥️ Single `-r securenow/register` flag — works for both CJS and ESM apps
+- 🟢 Native Nuxt 3 module (`securenow/nuxt`)
+
+---
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [CLI — Command Line Interface](#cli--command-line-interface)
+- [Framework-Specific Setup](#framework-specific-setup)
+  - [Express.js](#expressjs)
+  - [Next.js](#nextjs)
+  - [Nuxt 3](#nuxt-3)
+  - [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. Run Your Application
+
+Add `-r securenow/register` to your start command — that's the only change:
+
+```bash
+node -r securenow/register app.js
+```
+
+ESM and CJS apps are both handled automatically (Node >=20.6 auto-registers the ESM loader hook via `module.register()`).
+
+**package.json** example:
+
+```json
+"scripts": {
+  "start": "node -r securenow/register app.js",
+  "dev": "node -r securenow/register --watch app.js"
+}
+```
+
+**Alternative: Use NODE_OPTIONS** so your existing scripts stay unchanged:
+
+```bash
+NODE_OPTIONS="-r securenow/register" npm start
+```
+
+**CJS only: Code-based initialization**
+
+```javascript
+// At the very top of your main file, before any other require
+require('securenow/register');
+
+const express = require('express');
+const app = express();
+// ...
+```
+
+You'll see confirmation in the console:
+
+```
+[securenow] OTel SDK started → http://your-otlp-collector:4318/v1/traces
+[securenow] 📝 Request body capture: ENABLED
+```
+
+---
+
+## CLI — Command Line Interface
+
+The `securenow` CLI gives you full access to the SecureNow platform from the terminal — no browser required for day-to-day workflows. Zero additional dependencies.
+
+### Getting Started
+
+```bash
+# Log in (opens browser for OAuth)
+npx securenow login
+
+# Or use a token for CI/headless environments
+npx securenow login --token <YOUR_JWT>
+
+# Check who you're logged in as
+npx securenow whoami
+```
+
+### Managing Applications
+
+```bash
+# List all applications
+npx securenow apps
+
+# Create a new application
+npx securenow apps create my-production-app --hosts api.example.com,app.example.com
+
+# Get application details (including the app key)
+npx securenow apps info <app-id>
+
+# Set a default app so you don't need --app on every command
+npx securenow apps default <app-key>
+
+# Delete an application
+npx securenow apps delete <app-id> --force
+```
+
+### Viewing Traces
+
+```bash
+# List recent traces (uses default app, or specify --app)
+npx securenow traces
+npx securenow traces --app <key> --limit 50
+
+# Show detailed spans for a trace
+npx securenow traces show <traceId>
+
+# AI-powered security analysis of a trace
+npx securenow traces analyze <traceId>
+```
+
+### Viewing Logs
+
+```bash
+# List recent logs
+npx securenow logs
+npx securenow logs --app <key> --minutes 30 --level error
+
+# Show logs for a specific trace
+npx securenow logs trace <traceId>
+```
+
+### Security Issues
+
+```bash
+# List all issues
+npx securenow issues
+npx securenow issues --status open
+
+# Show issue details with AI analysis
+npx securenow issues show <issue-id>
+
+# Resolve an issue
+npx securenow issues resolve <issue-id>
+```
+
+### Notifications
+
+```bash
+# List notifications
+npx securenow notifications
+
+# Check unread count
+npx securenow notifications unread
+
+# Mark as read
+npx securenow notifications read <id>
+npx securenow notifications read-all
+```
+
+### Alerting
+
+```bash
+# View alert rules, channels, and history
+npx securenow alerts rules
+npx securenow alerts channels
+npx securenow alerts history --limit 20
+```
+
+### IP Intelligence & Blocklist
+
+```bash
+# Look up any IP — geo, abuse score, verdict, risk factors
+npx securenow ip 203.0.113.42
+
+# Show traces from a specific IP
+npx securenow ip traces 203.0.113.42
+
+# Manage the blocklist
+npx securenow blocklist
+npx securenow blocklist add 203.0.113.42 --reason "Brute force scanner"
+npx securenow blocklist remove <id>
+npx securenow blocklist stats
+
+# Manage trusted IPs
+npx securenow trusted
+npx securenow trusted add 10.0.0.1 --label "Office VPN"
+npx securenow trusted remove <id>
+```
+
+### Forensic Queries
+
+Ask questions in plain English — the AI translates them to SQL and runs them against your data.
+
+```bash
+# Run a forensic query
+npx securenow forensics "show top 10 attacking IPs in the last hour"
+npx securenow forensics "which endpoints had 5xx errors today"
+
+# Browse the saved query library
+npx securenow forensics library
+```
+
+### API Map
+
+```bash
+# View all discovered API endpoints
+npx securenow api-map
+
+# API map statistics
+npx securenow api-map stats
+```
+
+### Analytics & Dashboard
+
+```bash
+# Response code analytics
+npx securenow analytics --app <key>
+
+# Full dashboard overview (apps, protection status, unread alerts)
+npx securenow status
+```
+
+### Instances
+
+```bash
+# List ClickHouse instances
+npx securenow instances
+
+# Test an instance connection
+npx securenow instances test <id>
+```
+
+### Configuration
+
+```bash
+# View all config
+npx securenow config get
+
+# Set values
+npx securenow config set apiUrl https://custom-api.example.com
+npx securenow config set defaultApp <app-key>
+npx securenow config set format json
+
+# Show config file paths
+npx securenow config path
+```
+
+Config files are stored in `~/.securenow/`:
+
+| File | Description |
+|------|-------------|
+| `config.json` | API URL, default app, output format |
+| `credentials.json` | Auth token (file permissions: 0600) |
+
+### Initialize Instrumentation
+
+```bash
+# Interactive setup — creates instrumentation files for Next.js
+npx securenow init
+npx securenow init --ts --src --force
+```
+
+### Global Flags
+
+Every command supports these flags:
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--json` | `-j` | Output as JSON for scripting and CI/CD |
+| `--help` | | Show help for the command |
+| `--app <key>` | | Override the default application key |
+
+### Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `SECURENOW_API_URL` | Override the API base URL |
+| `SECURENOW_DEBUG` | Show stack traces on errors |
+| `NO_COLOR` | Disable colored output |
+
+### CI/CD Integration
+
+```bash
+# Authenticate with a token in CI
+npx securenow login --token $SECURENOW_TOKEN
+
+# Use --json for machine-readable output
+npx securenow issues --json | jq '.[] | select(.severity == "critical")'
+
+# Check for critical issues in a pipeline
+ISSUES=$(npx securenow issues --json --status open)
+CRITICAL=$(echo "$ISSUES" | jq '[.[] | select(.severity == "critical")] | length')
+if [ "$CRITICAL" -gt "0" ]; then
+  echo "Found $CRITICAL critical issues!"
+  exit 1
+fi
+```
+
+### Complete Command Reference
+
+| Category | Command | Description |
+|----------|---------|-------------|
+| **Auth** | `login` | Authenticate via browser or `--token` |
+| | `logout` | Clear credentials |
+| | `whoami` | Show session info |
+| **Apps** | `apps` | List applications |
+| | `apps create <name>` | Create application |
+| | `apps info <id>` | Application details |
+| | `apps delete <id>` | Delete application |
+| | `apps default <key>` | Set default app |
+| **Observe** | `traces` | List traces |
+| | `traces show <id>` | Trace details |
+| | `traces analyze <id>` | AI trace analysis |
+| | `logs` | List logs |
+| | `logs trace <id>` | Logs for a trace |
+| | `analytics` | Response analytics |
+| | `status` | Dashboard overview |
+| **Detect** | `issues` | List issues |
+| | `issues show <id>` | Issue details |
+| | `issues resolve <id>` | Resolve issue |
+| | `notifications` | List notifications |
+| | `notifications unread` | Unread count |
+| | `notifications read <id>` | Mark read |
+| | `notifications read-all` | Mark all read |
+| | `alerts rules` | Alert rules |
+| | `alerts channels` | Alert channels |
+| | `alerts history` | Alert history |
+| **Investigate** | `ip <addr>` | IP intelligence |
+| | `ip traces <addr>` | Traces from IP |
+| | `forensics "<query>"` | NL forensic query |
+| | `forensics library` | Saved queries |
+| | `api-map` | API endpoints |
+| | `api-map stats` | API stats |
+| **Remediate** | `blocklist` | Blocked IPs |
+| | `blocklist add <ip>` | Block IP |
+| | `blocklist remove <id>` | Unblock IP |
+| | `blocklist stats` | Block stats |
+| | `trusted` | Trusted IPs |
+| | `trusted add <ip>` | Add trusted IP |
+| | `trusted remove <id>` | Remove trusted |
+| **Settings** | `instances` | List instances |
+| | `instances test <id>` | Test connection |
+| | `config get` | Show config |
+| | `config set <k> <v>` | Set config value |
+| | `config path` | Config file paths |
+| | `init` | Setup instrumentation |
+| | `version` | Show version |
+
+---
+
+## Framework-Specific Setup
+
+> **v5.6.0+:** When `SECURENOW_LOGGING_ENABLED=1`, all `console.log`/`warn`/`error`/`info`/`debug` calls
+> are **automatically** forwarded as OTLP log records. The separate `require('securenow/console-instrumentation')` is no longer needed (but still available for backward compat).
+
+### Express.js
+
+```bash
+npm install securenow express
+```
+
+```javascript
+// app.js
+require('securenow/register');
+const express = require('express');
+
+const app = express();
+app.use(express.json());
+
+app.get('/health', (req, res) => res.json({ status: 'ok' }));
+
+app.post('/tasks', (req, res) => {
+  console.log('Created task:', req.body.title);
+  res.status(201).json({ id: '1', title: req.body.title });
+});
+
+app.listen(3000, () => console.log('Express running on port 3000'));
+```
+
+```bash
+node app.js
+```
+
+#### With PM2
+
+```javascript
+// ecosystem.config.cjs
+module.exports = {
+  apps: [{
+    name: 'my-app',
+    script: './app.js',
+    node_args: '-r securenow/register',
+    env: {
+      SECURENOW_APPID: 'your-app-key',
+      SECURENOW_INSTANCE: 'https://freetrial.securenow.ai:4318',
+      SECURENOW_LOGGING_ENABLED: '1',
+      SECURENOW_NO_UUID: '1',
+      SECURENOW_CAPTURE_BODY: '1',
+    }
+  }]
+};
+```
+
+---
+
+### Fastify
+
+```bash
+npm install securenow fastify
+```
+
+```javascript
+// app.js
+require('securenow/register');
+const Fastify = require('fastify');
+const fastify = Fastify({ logger: true });
+
+fastify.get('/health', async () => ({ status: 'ok' }));
+
+fastify.post('/tasks', {
+  schema: { body: { type: 'object', required: ['title'], properties: { title: { type: 'string' } } } }
+}, async (request) => {
+  console.log('Created task:', request.body.title);
+  return { id: '1', title: request.body.title };
+});
+
+fastify.listen({ port: 3000 }, (err) => {
+  if (err) { fastify.log.error(err); process.exit(1); }
+  console.log('Fastify running on port 3000');
+});
+```
+
+> **Important:** Set `SECURENOW_CAPTURE_BODY=0` with Fastify — the body capture hook conflicts with Fastify's internal stream handling.
+
+---
+
+### Koa
+
+```bash
+npm install securenow koa @koa/router koa-bodyparser
+```
+
+```javascript
+// app.js
+require('securenow/register');
+const Koa = require('koa');
+const Router = require('@koa/router');
+const bodyParser = require('koa-bodyparser');
+
+const app = new Koa();
+const router = new Router();
+
+router.get('/health', (ctx) => { ctx.body = { status: 'ok' }; });
+
+router.post('/tasks', (ctx) => {
+  console.log('Created task:', ctx.request.body.title);
+  ctx.status = 201;
+  ctx.body = { id: '1', title: ctx.request.body.title };
+});
+
+app.use(bodyParser());
+app.use(router.routes());
+app.use(router.allowedMethods());
+
+app.listen(3000, () => console.log('Koa running on port 3000'));
+```
+
+---
+
+### NestJS
+
+```bash
+npm install securenow @nestjs/core @nestjs/common reflect-metadata ts-node typescript
+```
+
+NestJS uses TypeScript — securenow is loaded via `-r` flags instead of in-code `require()`:
+
+```typescript
+// app.ts
+import 'reflect-metadata';
+import { NestFactory } from '@nestjs/core';
+import { Module, Controller, Get, Post, Body } from '@nestjs/common';
+
+@Controller()
+class AppController {
+  @Get('health')
+  health() { return { status: 'ok' }; }
+
+  @Post('tasks')
+  create(@Body() body: { title: string }) {
+    console.log('Created task:', body.title);
+    return { id: '1', title: body.title };
+  }
+}
+
+@Module({ controllers: [AppController] })
+class AppModule {}
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule);
+  await app.listen(3000);
+  console.log('NestJS running on port 3000');
+}
+bootstrap();
+```
+
+```bash
+node -r securenow/register -r ts-node/register app.ts
+```
+
+PM2 config:
+
+```javascript
+{
+  name: 'my-nestjs-app',
+  script: 'app.ts',
+  interpreter: 'node',
+  node_args: '-r securenow/register -r ts-node/register',
+}
+```
+
+---
+
+### Hapi
+
+```bash
+npm install securenow @hapi/hapi
+```
+
+```javascript
+// app.js
+require('securenow/register');
+const Hapi = require('@hapi/hapi');
+
+const init = async () => {
+  const server = Hapi.server({ port: 3000, host: '0.0.0.0' });
+
+  server.route({ method: 'GET', path: '/health', handler: () => ({ status: 'ok' }) });
+
+  server.route({
+    method: 'POST', path: '/tasks',
+    options: { payload: { parse: true, allow: 'application/json' } },
+    handler: (request, h) => {
+      console.log('Created task:', request.payload.title);
+      return h.response({ id: '1', title: request.payload.title }).code(201);
+    }
+  });
+
+  await server.start();
+  console.log('Hapi running on port 3000');
+};
+
+init().catch((err) => { console.error(err); process.exit(1); });
+```
+
+> **Important:** Set `SECURENOW_CAPTURE_BODY=0` with Hapi — the body capture hook consumes the request stream before Hapi's payload parser.
+
+---
+
+### h3 (UnJS / Nitro)
+
+```bash
+npm install securenow h3
+```
+
+```javascript
+// app.js
+require('securenow/register');
+const { createApp, createRouter, defineEventHandler, readBody, setResponseStatus, toNodeListener } = require('h3');
+const http = require('http');
+
+const app = createApp();
+const router = createRouter();
+
+router.get('/health', defineEventHandler(() => ({ status: 'ok' })));
+
+router.post('/tasks', defineEventHandler(async (event) => {
+  const body = await readBody(event);
+  console.log('Created task:', body.title);
+  setResponseStatus(event, 201);
+  return { id: '1', title: body.title };
+}));
+
+app.use(router);
+
+http.createServer(toNodeListener(app)).listen(3000, () => {
+  console.log('h3 running on port 3000');
+});
+```
+
+---
+
+### Polka
+
+```bash
+npm install securenow polka
+```
+
+Polka is minimalist — no built-in body parser:
+
+```javascript
+// app.js
+require('securenow/register');
+const polka = require('polka');
+
+function jsonBody(req, res, next) {
+  if (req.method === 'GET' || req.method === 'DELETE') return next();
+  let data = '';
+  req.on('data', chunk => { data += chunk; });
+  req.on('end', () => { try { req.body = JSON.parse(data); } catch { req.body = {}; } next(); });
+}
+
+function sendJson(res, status, body) {
+  res.writeHead(status, { 'Content-Type': 'application/json' });
+  res.end(JSON.stringify(body));
+}
+
+polka()
+  .use(jsonBody)
+  .get('/health', (req, res) => sendJson(res, 200, { status: 'ok' }))
+  .post('/tasks', (req, res) => {
+    console.log('Created task:', req.body.title);
+    sendJson(res, 201, { id: '1', title: req.body.title });
+  })
+  .listen(3000, () => console.log('Polka running on port 3000'));
+```
+
+---
+
+### Micro / Raw HTTP
+
+For apps using Node's bare `http` module:
+
+```bash
+npm install securenow
+```
+
+```javascript
+// app.js
+require('securenow/register');
+const http = require('http');
+
+function sendJson(res, status, body) {
+  res.writeHead(status, { 'Content-Type': 'application/json' });
+  res.end(JSON.stringify(body));
+}
+
+function readBody(req) {
+  return new Promise((resolve) => {
+    let d = ''; req.on('data', c => { d += c; }); req.on('end', () => { try { resolve(JSON.parse(d)); } catch { resolve({}); } });
+  });
+}
+
+async function handler(req, res) {
+  const url = new URL(req.url, `http://${req.headers.host}`);
+  if (url.pathname === '/health') return sendJson(res, 200, { status: 'ok' });
+  if (url.pathname === '/tasks' && req.method === 'POST') {
+    const body = await readBody(req);
+    console.log('Created task:', body.title);
+    return sendJson(res, 201, { id: '1', title: body.title });
+  }
+  sendJson(res, 404, { error: 'Not found' });
+}
+
+http.createServer(handler).listen(3000, () => console.log('HTTP running on port 3000'));
+```
+
+---
+
+### Hono (ESM)
+
+```bash
+npm install securenow hono @hono/node-server
+```
+
+Hono uses ESM — preload via `-r` flag (the ESM hook is auto-registered on Node >=20.6):
+
+```javascript
+// app.mjs
+import { serve } from '@hono/node-server';
+import { Hono } from 'hono';
+
+const app = new Hono();
+
+app.get('/health', (c) => c.json({ status: 'ok' }));
+
+app.post('/tasks', async (c) => {
+  const body = await c.req.json();
+  console.log('Created task:', body.title);
+  return c.json({ id: '1', title: body.title }, 201);
+});
+
+serve({ fetch: app.fetch, port: 3000 }, () => console.log('Hono running on port 3000'));
+```
+
+```bash
+node -r securenow/register app.mjs
+```
+
+> **Important:** Set `SECURENOW_CAPTURE_BODY=0` with Hono. Do **not** add `require('securenow/register')` inside `.mjs` files.
+
+---
+
+### Feathers
+
+```bash
+npm install securenow @feathersjs/feathers @feathersjs/express @feathersjs/errors
+```
+
+Feathers uses Express transport — same setup as Express:
+
+```javascript
+// app.js
+require('securenow/register');
+const feathers = require('@feathersjs/feathers');
+const express = require('@feathersjs/express');
+const errors = require('@feathersjs/errors');
+
+class TaskService {
+  constructor() { this.tasks = []; this.nextId = 1; }
+  async find() { return this.tasks; }
+  async create(data) {
+    if (!data.title) throw new errors.BadRequest('title is required');
+    const task = { id: String(this.nextId++), title: data.title };
+    this.tasks.push(task);
+    console.log('Created task:', task.id);
+    return task;
+  }
+}
+
+const app = express(feathers());
+app.use(express.json());
+app.configure(express.rest());
+app.get('/health', (req, res) => res.json({ status: 'ok' }));
+app.use('/tasks', new TaskService());
+app.use(express.errorHandler());
+
+app.listen(3000, () => console.log('Feathers running on port 3000'));
+```
+
+---
+
+### Next.js
+
+See [Next.js Complete Guide →](./docs/NEXTJS-SETUP-COMPLETE.md)
+
+Create `instrumentation.ts` in your project root:
+
+```typescript
+export async function register() {
+  if (process.env.NEXT_RUNTIME === 'nodejs') {
+    await import('securenow/register');
+  }
+}
+```
+
+`.env.local`:
+
+```env
+SECURENOW_APPID=my-nextjs-app
+SECURENOW_INSTANCE=https://freetrial.securenow.ai:4318
+SECURENOW_LOGGING_ENABLED=1
+SECURENOW_NO_UUID=1
+```
+
+---
+
+### Nuxt 3
+
+```bash
+npm install securenow
+```
+
+Add the module to `nuxt.config.ts`:
+
+```typescript
+export default defineNuxtConfig({
+  modules: ['securenow/nuxt'],
+});
+```
+
+`.env`:
+
+```env
+SECURENOW_APPID=my-nuxt-app
+SECURENOW_INSTANCE=https://freetrial.securenow.ai:4318
+```
+
+That's it — the Nuxt module handles OTel SDK initialization, Nitro externalization, and request tracing automatically. Optional config:
+
+```typescript
+export default defineNuxtConfig({
+  modules: ['securenow/nuxt'],
+  securenow: {
+    captureBody: true,
+    logging: true,
+    noUuid: true,
+  },
+});
+```
+
+---
+
+### Compatibility Matrix
+
+| Framework | Traces | Logs | Body Capture | Notes |
+|-----------|--------|------|--------------|-------|
+| Express | Yes | Yes | Yes | Fully compatible |
+| Fastify | Yes | Yes | **No** | `SECURENOW_CAPTURE_BODY=0` required |
+| Koa | Yes | Yes | Yes | Needs `koa-bodyparser` |
+| NestJS | Yes | Yes | Yes | Use `-r ts-node/register` |
+| Hapi | Yes | Yes | **No** | `SECURENOW_CAPTURE_BODY=0` required |
+| h3 | Yes | Yes | Yes | Uses `toNodeListener()` |
+| Polka | Yes | Yes | Yes | Needs manual body parser |
+| Micro/HTTP | Yes | Yes | Yes | Full control |
+| Hono | Yes | Yes | **No** | `SECURENOW_CAPTURE_BODY=0`; ESM `-r` flag |
+| Feathers | Yes | Yes | Yes | Uses Express transport |
+| Next.js | Yes | Yes | Yes | Use `instrumentation.ts` |
+| Nuxt 3 | Yes | Yes | Yes | Use `securenow/nuxt` module |
+
+---
+
+## 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
+
+Since **v5.6.0**, when `SECURENOW_LOGGING_ENABLED=1`, all console calls are automatically forwarded as OTLP log records:
+
+```javascript
+// At the top of your main file
+require('securenow/register');
+
+// With SECURENOW_LOGGING_ENABLED=1, 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 tracing + logging (console auto-forwarding is built-in since v5.6.0)
+NODE_OPTIONS="-r securenow/register" \
+SECURENOW_APPID=my-app \
+SECURENOW_INSTANCE=https://freetrial.securenow.ai: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" 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 (console log forwarding is automatic since v5.6.0)
+require('securenow/register');
+```
+
+---
+
+## 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');
+  }
+}
+```
+
+### NestJS with TypeScript
+
+Use `-r securenow/register -r ts-node/register` flags instead of in-code require:
+
+```typescript
+// main.ts (run with: node -r securenow/register -r ts-node/register main.ts)
+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
+require('securenow/register');
+```
+
+**Check 3: Check console output**
+
+You should see:
+```
+[securenow] 📋 Logging: ENABLED → http://localhost:4318/v1/logs
+```
+
+**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, Nuxt 3, 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**