securenow 6.0.2 → 6.1.0

package/docs/EXPRESS-SETUP-GUIDE.md

@@ -1,720 +1,719 @@
-# Express.js Setup Guide - SecureNow Observability
-
-Complete guide to add distributed tracing and logging to your Express.js application using SecureNow.
-
----
-
-## Prerequisites
-
-- Node.js 18 or higher
-- An existing Express.js application
-- An OTLP-compatible observability backend
-
----
-
-## Installation
-
-```bash
-npm install securenow express
-```
-
----
-
-## Quick Start (5 Minutes)
-
-### Step 1: Install Package
-
-```bash
-npm install securenow
-```
-
-### Step 2: Create Environment Variables
-
-Create a `.env` file in your project root:
-
-```env
-SECURENOW_APPID=my-express-app
-SECURENOW_INSTANCE=http://localhost:4318
-SECURENOW_LOGGING_ENABLED=1
-SECURENOW_CAPTURE_BODY=1
-```
-
-### Step 3: Initialize SecureNow
-
-Add these lines at the **very top** of your main file (before any other requires):
-
-```javascript
-// app.js or server.js
-require('securenow/register');
-require('securenow/console-instrumentation');
-
-// Now your Express app
-const express = require('express');
-const app = express();
-
-app.use(express.json());
-
-app.get('/', (req, res) => {
-  console.log('Home page accessed');
-  res.send('Hello World');
-});
-
-const PORT = process.env.PORT || 3000;
-app.listen(PORT, () => {
-  console.log(`Server running on port ${PORT}`);
-});
-```
-
-### Step 4: Run Your Application
-
-```bash
-node app.js
-```
-
-You should see:
-
-```
-[securenow] OTel SDK started → http://localhost:4318/v1/traces
-[securenow] 📋 Logging: ENABLED → http://localhost:4318/v1/logs
-[securenow] Console instrumentation installed
-Server running on port 3000
-```
-
-**Done!** Your Express app is now sending traces and logs.
-
----
-
-## Complete Example
-
-```javascript
-// app.js
-require('securenow/register');
-require('securenow/console-instrumentation');
-
-const express = require('express');
-const app = express();
-
-// Middleware
-app.use(express.json());
-app.use(express.urlencoded({ extended: true }));
-
-// Logging middleware
-app.use((req, res, next) => {
-  console.info('Incoming request', {
-    method: req.method,
-    path: req.path,
-    query: req.query,
-    ip: req.ip,
-    userAgent: req.get('user-agent'),
-  });
-  next();
-});
-
-// Routes
-app.get('/', (req, res) => {
-  console.log('Home page accessed');
-  res.json({
-    message: 'Express with SecureNow',
-    timestamp: new Date().toISOString(),
-  });
-});
-
-app.get('/api/users', async (req, res) => {
-  console.log('Fetching users');
-  
-  try {
-    // Your database logic
-    const users = await getUsersFromDatabase();
-    
-    console.info('Users fetched successfully', {
-      count: users.length,
-    });
-    
-    res.json(users);
-  } catch (error) {
-    console.error('Failed to fetch users', {
-      error: error.message,
-      stack: error.stack,
-    });
-    res.status(500).json({ error: 'Internal server error' });
-  }
-});
-
-app.post('/api/users', async (req, res) => {
-  console.info('Creating new user', {
-    email: req.body.email,
-    name: req.body.name,
-  });
-  
-  try {
-    // Validation
-    if (!req.body.email || !req.body.name) {
-      console.warn('Validation failed', {
-        body: req.body,
-      });
-      return res.status(400).json({ error: 'Email and name required' });
-    }
-    
-    // Your database logic
-    const user = await createUserInDatabase(req.body);
-    
-    console.log('User created successfully', {
-      userId: user.id,
-      email: user.email,
-    });
-    
-    res.status(201).json(user);
-  } catch (error) {
-    console.error('Failed to create user', {
-      error: error.message,
-      stack: error.stack,
-      body: req.body,
-    });
-    res.status(500).json({ error: 'Internal server error' });
-  }
-});
-
-// Error handling middleware
-app.use((err, req, res, next) => {
-  console.error('Express error handler', {
-    error: err.message,
-    stack: err.stack,
-    path: req.path,
-    method: req.method,
-  });
-  
-  res.status(500).json({
-    error: 'Internal server error',
-    message: err.message,
-  });
-});
-
-// Start server
-const PORT = process.env.PORT || 3000;
-app.listen(PORT, () => {
-  console.log('Express server started', {
-    port: PORT,
-    nodeVersion: process.version,
-    env: process.env.NODE_ENV || 'development',
-  });
-});
-```
-
----
-
-## Using NODE_OPTIONS (No Code Changes)
-
-If you don't want to modify your code, use `NODE_OPTIONS`:
-
-```bash
-NODE_OPTIONS="-r securenow/register -r securenow/console-instrumentation" \
-SECURENOW_APPID=my-express-app \
-SECURENOW_INSTANCE=http://localhost:4318 \
-SECURENOW_LOGGING_ENABLED=1 \
-node app.js
-```
-
-This works with npm scripts too:
-
-```json
-{
-  "scripts": {
-    "start": "node app.js",
-    "start:instrumented": "NODE_OPTIONS='-r securenow/register -r securenow/console-instrumentation' node app.js"
-  }
-}
-```
-
-Then run:
-
-```bash
-npm run start:instrumented
-```
-
----
-
-## Environment Variables
-
-### Required
-
-```env
-# Your application identifier
-SECURENOW_APPID=my-express-app
-
-# Your OTLP collector endpoint
-SECURENOW_INSTANCE=http://localhost:4318
-```
-
-### Recommended
-
-```env
-# Enable logging
-SECURENOW_LOGGING_ENABLED=1
-
-# Enable request body capture (for debugging)
-SECURENOW_CAPTURE_BODY=1
-
-# Max body size (default: 10KB)
-SECURENOW_MAX_BODY_SIZE=10240
-
-# Environment name
-NODE_ENV=production
-```
-
-### Optional
-
-```env
-# Authentication headers for your observability backend
-OTEL_EXPORTER_OTLP_HEADERS=x-api-key=your-key
-
-# Disable UUID suffix on service name
-SECURENOW_NO_UUID=1
-
-# Enable debug logging
-OTEL_LOG_LEVEL=debug
-
-# Additional sensitive fields to redact
-SECURENOW_SENSITIVE_FIELDS=internal_token,session_key
-```
-
----
-
-## PM2 Setup
-
-### Basic PM2 Configuration
-
-```javascript
-// ecosystem.config.js
-module.exports = {
-  apps: [{
-    name: 'my-express-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', // Same service name for all instances
-      SECURENOW_CAPTURE_BODY: '1',
-      NODE_ENV: 'production',
-    }
-  }]
-};
-```
-
-Start with PM2:
-
-```bash
-pm2 start ecosystem.config.js
-```
-
-### PM2 with Environment-Specific Config
-
-```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_development: {
-      SECURENOW_APPID: 'my-app-dev',
-      SECURENOW_INSTANCE: 'http://localhost:4318',
-      SECURENOW_LOGGING_ENABLED: '1',
-      SECURENOW_CAPTURE_BODY: '1',
-      OTEL_LOG_LEVEL: 'debug',
-      NODE_ENV: 'development',
-    },
-    env_production: {
-      SECURENOW_APPID: 'my-app-prod',
-      SECURENOW_INSTANCE: 'http://collector.prod:4318',
-      SECURENOW_LOGGING_ENABLED: '1',
-      SECURENOW_CAPTURE_BODY: '0', // Disable in production
-      SECURENOW_NO_UUID: '1',
-      NODE_ENV: 'production',
-    }
-  }]
-};
-```
-
-Run with specific environment:
-
-```bash
-# Development
-pm2 start ecosystem.config.js
-
-# Production
-pm2 start ecosystem.config.js --env production
-```
-
----
-
-## TypeScript Setup
-
-### Step 1: Install
-
-```bash
-npm install securenow typescript @types/node @types/express ts-node
-```
-
-### Step 2: Initialize SecureNow
-
-```typescript
-// app.ts
-require('securenow/register');
-require('securenow/console-instrumentation');
-
-import express, { Request, Response, NextFunction } from 'express';
-
-const app = express();
-
-app.use(express.json());
-
-app.get('/', (req: Request, res: Response) => {
-  console.log('Home page accessed');
-  res.json({ message: 'Hello World' });
-});
-
-app.post('/api/users', async (req: Request, res: Response) => {
-  console.info('Creating user', { body: req.body });
-  
-  try {
-    // Your logic
-    const user = await createUser(req.body);
-    console.log('User created', { userId: user.id });
-    res.status(201).json(user);
-  } catch (error) {
-    console.error('Failed to create user', { error });
-    res.status(500).json({ error: 'Internal server error' });
-  }
-});
-
-// Error handler
-app.use((err: Error, req: Request, res: Response, next: NextFunction) => {
-  console.error('Express error', {
-    error: err.message,
-    stack: err.stack,
-    path: req.path,
-  });
-  res.status(500).json({ error: 'Internal server error' });
-});
-
-const PORT = process.env.PORT || 3000;
-app.listen(PORT, () => {
-  console.log(`Server running on port ${PORT}`);
-});
-```
-
-### Step 3: Run with ts-node
-
-```bash
-npx ts-node app.ts
-```
-
-Or compile and run:
-
-```bash
-npx tsc
-node dist/app.js
-```
-
----
-
-## Advanced Features
-
-### Request Body Capture
-
-Enable to see request bodies in your traces:
-
-```env
-SECURENOW_CAPTURE_BODY=1
-SECURENOW_MAX_BODY_SIZE=10240
-```
-
-**Automatically redacted fields:** passwords, tokens, api_keys, card numbers, etc.
-
-**Add custom redaction:**
-
-```env
-SECURENOW_SENSITIVE_FIELDS=internal_token,session_key
-```
-
-### Custom Logger
-
-For more control, use the direct logger API:
-
-```javascript
-const { getLogger } = require('securenow/tracing');
-
-const logger = getLogger('express-app', '1.0.0');
-
-app.post('/api/users', async (req, res) => {
-  logger.emit({
-    severityNumber: 9,
-    severityText: 'INFO',
-    body: 'User creation started',
-    attributes: {
-      email: req.body.email,
-      ip: req.ip,
-      timestamp: Date.now(),
-    },
-  });
-  
-  // Your logic...
-});
-```
-
-### Disable Specific Instrumentations
-
-If you don't need certain instrumentations:
-
-```env
-SECURENOW_DISABLE_INSTRUMENTATIONS=fs,dns,net
-```
-
----
-
-## Docker Setup
-
-### Dockerfile
-
-```dockerfile
-FROM node:20-alpine
-
-WORKDIR /app
-
-# Copy package files
-COPY package*.json ./
-
-# Install dependencies
-RUN npm install
-
-# Copy application code
-COPY . .
-
-# Set environment variables
-ENV SECURENOW_APPID=my-express-app
-ENV SECURENOW_INSTANCE=http://collector:4318
-ENV SECURENOW_LOGGING_ENABLED=1
-ENV NODE_ENV=production
-
-# Expose port
-EXPOSE 3000
-
-# Start application
-CMD ["node", "app.js"]
-```
-
-### docker-compose.yml
-
-```yaml
-version: '3.8'
-
-services:
-  app:
-    build: .
-    ports:
-      - "3000:3000"
-    environment:
-      - SECURENOW_APPID=my-express-app
-      - SECURENOW_INSTANCE=http://collector:4318
-      - SECURENOW_LOGGING_ENABLED=1
-      - SECURENOW_CAPTURE_BODY=1
-      - NODE_ENV=production
-    depends_on:
-      - collector
-
-  collector:
-    image: otel/opentelemetry-collector:latest
-    ports:
-      - "4318:4318"
-    volumes:
-      - ./otel-collector-config.yaml:/etc/otel-collector-config.yaml
-    command: ["--config=/etc/otel-collector-config.yaml"]
-```
-
-Run:
-
-```bash
-docker-compose up
-```
-
----
-
-## Troubleshooting
-
-### Traces Not Appearing
-
-**Check initialization order:**
-
-```javascript
-// ✅ Correct
-require('securenow/register');
-require('securenow/console-instrumentation');
-const express = require('express');
-
-// ❌ Wrong
-const express = require('express');
-require('securenow/register');
-```
-
-**Enable debug logging:**
-
-```bash
-export OTEL_LOG_LEVEL=debug
-node app.js
-```
-
-**Verify collector is running:**
-
-```bash
-curl http://localhost:4318/v1/traces
-# Should return 200 or 405
-```
-
-### Logs Not Appearing
-
-**Check logging is enabled:**
-
-```bash
-echo $SECURENOW_LOGGING_ENABLED
-# Should output: 1
-```
-
-**Verify console instrumentation:**
-
-Look for this in the output:
-```
-[securenow] Console instrumentation installed
-```
-
-### PM2 Issues
-
-**Different service names for each worker:**
-
-```env
-# Add this to use same service name
-SECURENOW_NO_UUID=1
-```
-
-**Workers not instrumented:**
-
-Use `node_args` in PM2 config:
-
-```javascript
-{
-  node_args: '-r securenow/register -r securenow/console-instrumentation'
-}
-```
-
----
-
-## Best Practices
-
-### 1. Use Structured Logging
-
-```javascript
-// ❌ Bad
-console.log('User 123 logged in');
-
-// ✅ Good
-console.log('User logged in', {
-  userId: 123,
-  email: 'user@example.com',
-  timestamp: Date.now(),
-});
-```
-
-### 2. Log at Appropriate Levels
-
-```javascript
-// Normal operations
-console.info('Request processed', { userId: 123 });
-
-// Warnings
-console.warn('API rate limit approaching', { remaining: 10 });
-
-// Errors
-console.error('Database error', { error: err.message });
-```
-
-### 3. Use Middleware for Request Logging
-
-```javascript
-app.use((req, res, next) => {
-  console.info('Request received', {
-    method: req.method,
-    path: req.path,
-    ip: req.ip,
-  });
-  next();
-});
-```
-
-### 4. Don't Enable Body Capture in Production
-
-```env
-# .env.development
-SECURENOW_CAPTURE_BODY=1
-
-# .env.production
-SECURENOW_CAPTURE_BODY=0
-```
-
----
-
-## Complete Environment Variables Reference
-
-```env
-# === Required ===
-SECURENOW_APPID=my-express-app
-SECURENOW_INSTANCE=http://localhost:4318
-
-# === Logging ===
-SECURENOW_LOGGING_ENABLED=1
-
-# === Request Body Capture ===
-SECURENOW_CAPTURE_BODY=1
-SECURENOW_MAX_BODY_SIZE=10240
-SECURENOW_SENSITIVE_FIELDS=custom_field1,custom_field2
-
-# === Service Naming ===
-SECURENOW_NO_UUID=1
-OTEL_SERVICE_NAME=my-express-app
-
-# === Connection ===
-OTEL_EXPORTER_OTLP_HEADERS=x-api-key=your-key
-OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4318/v1/traces
-OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://localhost:4318/v1/logs
-
-# === Debugging ===
-OTEL_LOG_LEVEL=debug
-SECURENOW_TEST_SPAN=1
-
-# === Environment ===
-NODE_ENV=production
-```
-
----
-
-## Next Steps
-
-- Check your observability backend to see traces and logs
-- Set up dashboards and alerts
-- Explore the captured data to understand your application behavior
-
----
-
-## Support
-
-- **Documentation:** [Main Docs](../README.md)
-- **Examples:** [Express Examples](../examples/)
-- **Issues:** GitHub Issues
-
----
-
-**Your Express app is now fully observable!** 🎉
+# Express.js Setup Guide - SecureNow Observability
+
+Complete guide to add distributed tracing and logging to your Express.js application using SecureNow.
+This setup has been **tested end-to-end** with traces and logs flowing to the SecureNow dashboard.
+
+---
+
+## Prerequisites
+
+- Node.js 18 or higher
+- An existing Express.js application
+- A SecureNow account (or any OTLP-compatible backend)
+
+---
+
+## Installation
+
+```bash
+npm install securenow
+```
+
+---
+
+## Quick Start (5 Minutes)
+
+### Step 1: Create Environment Variables
+
+Create a `.env` file in your project root:
+
+```env
+SECURENOW_APPID=my-express-app
+SECURENOW_INSTANCE=https://freetrial.securenow.ai:4318
+SECURENOW_LOGGING_ENABLED=1
+SECURENOW_NO_UUID=1
+```
+
+> Get your `SECURENOW_APPID` by running `npx securenow apps create my-express-app`.
+
+### Step 2: Initialize SecureNow
+
+Add `require('securenow/register')` at the **very top** of your main file (before any other requires):
+
+```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) => {
+  const { title } = req.body;
+  if (!title) return res.status(400).json({ error: 'title is required' });
+  console.log('Created task:', title);
+  res.status(201).json({ id: '1', title });
+});
+
+const PORT = process.env.PORT || 3000;
+app.listen(PORT, () => {
+  console.log(`Server running on port ${PORT}`);
+});
+```
+
+### Step 3: Run Your Application
+
+```bash
+node app.js
+```
+
+You should see:
+
+```
+[securenow] OTel SDK started → https://freetrial.securenow.ai:4318/v1/traces
+[securenow] 📋 Logging: ENABLED → https://freetrial.securenow.ai:4318/v1/logs
+Server running on port 3000
+```
+
+**Done!** Your Express app is now sending traces and logs.
+
+Since **v5.6.0**, when `SECURENOW_LOGGING_ENABLED=1`, all `console.log`/`warn`/`error` calls are **automatically** forwarded as OTLP log records — no separate `require('securenow/console-instrumentation')` needed.
+
+---
+
+## Complete Example
+
+```javascript
+// app.js
+require('securenow/register');
+
+const express = require('express');
+const app = express();
+
+// Middleware
+app.use(express.json());
+app.use(express.urlencoded({ extended: true }));
+
+// Logging middleware
+app.use((req, res, next) => {
+  console.info('Incoming request', {
+    method: req.method,
+    path: req.path,
+    query: req.query,
+    ip: req.ip,
+    userAgent: req.get('user-agent'),
+  });
+  next();
+});
+
+// Routes
+app.get('/', (req, res) => {
+  console.log('Home page accessed');
+  res.json({
+    message: 'Express with SecureNow',
+    timestamp: new Date().toISOString(),
+  });
+});
+
+app.get('/api/users', async (req, res) => {
+  console.log('Fetching users');
+  
+  try {
+    // Your database logic
+    const users = await getUsersFromDatabase();
+    
+    console.info('Users fetched successfully', {
+      count: users.length,
+    });
+    
+    res.json(users);
+  } catch (error) {
+    console.error('Failed to fetch users', {
+      error: error.message,
+      stack: error.stack,
+    });
+    res.status(500).json({ error: 'Internal server error' });
+  }
+});
+
+app.post('/api/users', async (req, res) => {
+  console.info('Creating new user', {
+    email: req.body.email,
+    name: req.body.name,
+  });
+  
+  try {
+    // Validation
+    if (!req.body.email || !req.body.name) {
+      console.warn('Validation failed', {
+        body: req.body,
+      });
+      return res.status(400).json({ error: 'Email and name required' });
+    }
+    
+    // Your database logic
+    const user = await createUserInDatabase(req.body);
+    
+    console.log('User created successfully', {
+      userId: user.id,
+      email: user.email,
+    });
+    
+    res.status(201).json(user);
+  } catch (error) {
+    console.error('Failed to create user', {
+      error: error.message,
+      stack: error.stack,
+      body: req.body,
+    });
+    res.status(500).json({ error: 'Internal server error' });
+  }
+});
+
+// Error handling middleware
+app.use((err, req, res, next) => {
+  console.error('Express error handler', {
+    error: err.message,
+    stack: err.stack,
+    path: req.path,
+    method: req.method,
+  });
+  
+  res.status(500).json({
+    error: 'Internal server error',
+    message: err.message,
+  });
+});
+
+// Start server
+const PORT = process.env.PORT || 3000;
+app.listen(PORT, () => {
+  console.log('Express server started', {
+    port: PORT,
+    nodeVersion: process.version,
+    env: process.env.NODE_ENV || 'development',
+  });
+});
+```
+
+---
+
+## Using NODE_OPTIONS (No Code Changes)
+
+If you don't want to modify your code, use `NODE_OPTIONS`:
+
+```bash
+NODE_OPTIONS="-r securenow/register" \
+SECURENOW_APPID=my-express-app \
+SECURENOW_INSTANCE=https://freetrial.securenow.ai:4318 \
+SECURENOW_LOGGING_ENABLED=1 \
+node app.js
+```
+
+This works with npm scripts too:
+
+```json
+{
+  "scripts": {
+    "start": "node app.js",
+    "start:instrumented": "NODE_OPTIONS='-r securenow/register' node app.js"
+  }
+}
+```
+
+Then run:
+
+```bash
+npm run start:instrumented
+```
+
+---
+
+## Environment Variables
+
+### Required
+
+```env
+# Your application identifier
+SECURENOW_APPID=my-express-app
+
+# Your OTLP collector endpoint
+SECURENOW_INSTANCE=http://localhost:4318
+```
+
+### Recommended
+
+```env
+# Enable logging
+SECURENOW_LOGGING_ENABLED=1
+
+# Enable request body capture (for debugging)
+SECURENOW_CAPTURE_BODY=1
+
+# Max body size (default: 10KB)
+SECURENOW_MAX_BODY_SIZE=10240
+
+# Environment name
+NODE_ENV=production
+```
+
+### Optional
+
+```env
+# Authentication headers for your observability backend
+OTEL_EXPORTER_OTLP_HEADERS=x-api-key=your-key
+
+# Disable UUID suffix on service name
+SECURENOW_NO_UUID=1
+
+# Enable debug logging
+OTEL_LOG_LEVEL=debug
+
+# Additional sensitive fields to redact
+SECURENOW_SENSITIVE_FIELDS=internal_token,session_key
+```
+
+---
+
+## PM2 Setup
+
+### Basic PM2 Configuration
+
+```javascript
+// ecosystem.config.js
+module.exports = {
+  apps: [{
+    name: 'my-express-app',
+    script: './app.js',
+    instances: 4,
+    exec_mode: 'cluster',
+    node_args: '-r securenow/register',
+    env: {
+      SECURENOW_APPID: 'my-express-app',
+      SECURENOW_INSTANCE: 'http://localhost:4318',
+      SECURENOW_LOGGING_ENABLED: '1',
+      SECURENOW_NO_UUID: '1', // Same service name for all instances
+      SECURENOW_CAPTURE_BODY: '1',
+      NODE_ENV: 'production',
+    }
+  }]
+};
+```
+
+Start with PM2:
+
+```bash
+pm2 start ecosystem.config.js
+```
+
+### PM2 with Environment-Specific Config
+
+```javascript
+// ecosystem.config.js
+module.exports = {
+  apps: [{
+    name: 'my-app',
+    script: './app.js',
+    instances: 4,
+    exec_mode: 'cluster',
+    node_args: '-r securenow/register',
+    env_development: {
+      SECURENOW_APPID: 'my-app-dev',
+      SECURENOW_INSTANCE: 'http://localhost:4318',
+      SECURENOW_LOGGING_ENABLED: '1',
+      SECURENOW_CAPTURE_BODY: '1',
+      OTEL_LOG_LEVEL: 'debug',
+      NODE_ENV: 'development',
+    },
+    env_production: {
+      SECURENOW_APPID: 'my-app-prod',
+      SECURENOW_INSTANCE: 'http://collector.prod:4318',
+      SECURENOW_LOGGING_ENABLED: '1',
+      SECURENOW_CAPTURE_BODY: '0', // Disable in production
+      SECURENOW_NO_UUID: '1',
+      NODE_ENV: 'production',
+    }
+  }]
+};
+```
+
+Run with specific environment:
+
+```bash
+# Development
+pm2 start ecosystem.config.js
+
+# Production
+pm2 start ecosystem.config.js --env production
+```
+
+---
+
+## TypeScript Setup
+
+### Step 1: Install
+
+```bash
+npm install securenow typescript @types/node @types/express ts-node
+```
+
+### Step 2: Initialize SecureNow
+
+```typescript
+// app.ts
+require('securenow/register');
+
+import express, { Request, Response, NextFunction } from 'express';
+
+const app = express();
+
+app.use(express.json());
+
+app.get('/', (req: Request, res: Response) => {
+  console.log('Home page accessed');
+  res.json({ message: 'Hello World' });
+});
+
+app.post('/api/users', async (req: Request, res: Response) => {
+  console.info('Creating user', { body: req.body });
+  
+  try {
+    // Your logic
+    const user = await createUser(req.body);
+    console.log('User created', { userId: user.id });
+    res.status(201).json(user);
+  } catch (error) {
+    console.error('Failed to create user', { error });
+    res.status(500).json({ error: 'Internal server error' });
+  }
+});
+
+// Error handler
+app.use((err: Error, req: Request, res: Response, next: NextFunction) => {
+  console.error('Express error', {
+    error: err.message,
+    stack: err.stack,
+    path: req.path,
+  });
+  res.status(500).json({ error: 'Internal server error' });
+});
+
+const PORT = process.env.PORT || 3000;
+app.listen(PORT, () => {
+  console.log(`Server running on port ${PORT}`);
+});
+```
+
+### Step 3: Run with ts-node
+
+```bash
+npx ts-node app.ts
+```
+
+Or compile and run:
+
+```bash
+npx tsc
+node dist/app.js
+```
+
+---
+
+## Advanced Features
+
+### Request Body Capture
+
+Enable to see request bodies in your traces:
+
+```env
+SECURENOW_CAPTURE_BODY=1
+SECURENOW_MAX_BODY_SIZE=10240
+```
+
+**Automatically redacted fields:** passwords, tokens, api_keys, card numbers, etc.
+
+**Add custom redaction:**
+
+```env
+SECURENOW_SENSITIVE_FIELDS=internal_token,session_key
+```
+
+### Custom Logger
+
+For more control, use the direct logger API:
+
+```javascript
+const { getLogger } = require('securenow/tracing');
+
+const logger = getLogger('express-app', '1.0.0');
+
+app.post('/api/users', async (req, res) => {
+  logger.emit({
+    severityNumber: 9,
+    severityText: 'INFO',
+    body: 'User creation started',
+    attributes: {
+      email: req.body.email,
+      ip: req.ip,
+      timestamp: Date.now(),
+    },
+  });
+  
+  // Your logic...
+});
+```
+
+### Disable Specific Instrumentations
+
+If you don't need certain instrumentations:
+
+```env
+SECURENOW_DISABLE_INSTRUMENTATIONS=fs,dns,net
+```
+
+---
+
+## Docker Setup
+
+### Dockerfile
+
+```dockerfile
+FROM node:20-alpine
+
+WORKDIR /app
+
+# Copy package files
+COPY package*.json ./
+
+# Install dependencies
+RUN npm install
+
+# Copy application code
+COPY . .
+
+# Set environment variables
+ENV SECURENOW_APPID=my-express-app
+ENV SECURENOW_INSTANCE=http://collector:4318
+ENV SECURENOW_LOGGING_ENABLED=1
+ENV NODE_ENV=production
+
+# Expose port
+EXPOSE 3000
+
+# Start application
+CMD ["node", "app.js"]
+```
+
+### docker-compose.yml
+
+```yaml
+version: '3.8'
+
+services:
+  app:
+    build: .
+    ports:
+      - "3000:3000"
+    environment:
+      - SECURENOW_APPID=my-express-app
+      - SECURENOW_INSTANCE=http://collector:4318
+      - SECURENOW_LOGGING_ENABLED=1
+      - SECURENOW_CAPTURE_BODY=1
+      - NODE_ENV=production
+    depends_on:
+      - collector
+
+  collector:
+    image: otel/opentelemetry-collector:latest
+    ports:
+      - "4318:4318"
+    volumes:
+      - ./otel-collector-config.yaml:/etc/otel-collector-config.yaml
+    command: ["--config=/etc/otel-collector-config.yaml"]
+```
+
+Run:
+
+```bash
+docker-compose up
+```
+
+---
+
+## Troubleshooting
+
+### Traces Not Appearing
+
+**Check initialization order:**
+
+```javascript
+// ✅ Correct
+require('securenow/register');
+const express = require('express');
+
+// ❌ Wrong
+const express = require('express');
+require('securenow/register');
+```
+
+**Enable debug logging:**
+
+```bash
+export OTEL_LOG_LEVEL=debug
+node app.js
+```
+
+**Verify collector is running:**
+
+```bash
+curl http://localhost:4318/v1/traces
+# Should return 200 or 405
+```
+
+### Logs Not Appearing
+
+**Check logging is enabled:**
+
+```bash
+echo $SECURENOW_LOGGING_ENABLED
+# Should output: 1
+```
+
+**Verify console instrumentation:**
+
+Look for this in the output:
+```
+[securenow] Console instrumentation installed
+```
+
+### PM2 Issues
+
+**Different service names for each worker:**
+
+```env
+# Add this to use same service name
+SECURENOW_NO_UUID=1
+```
+
+**Workers not instrumented:**
+
+Use `node_args` in PM2 config:
+
+```javascript
+{
+  node_args: '-r securenow/register'
+}
+```
+
+---
+
+## Best Practices
+
+### 1. Use Structured Logging
+
+```javascript
+// ❌ Bad
+console.log('User 123 logged in');
+
+// ✅ Good
+console.log('User logged in', {
+  userId: 123,
+  email: 'user@example.com',
+  timestamp: Date.now(),
+});
+```
+
+### 2. Log at Appropriate Levels
+
+```javascript
+// Normal operations
+console.info('Request processed', { userId: 123 });
+
+// Warnings
+console.warn('API rate limit approaching', { remaining: 10 });
+
+// Errors
+console.error('Database error', { error: err.message });
+```
+
+### 3. Use Middleware for Request Logging
+
+```javascript
+app.use((req, res, next) => {
+  console.info('Request received', {
+    method: req.method,
+    path: req.path,
+    ip: req.ip,
+  });
+  next();
+});
+```
+
+### 4. Don't Enable Body Capture in Production
+
+```env
+# .env.development
+SECURENOW_CAPTURE_BODY=1
+
+# .env.production
+SECURENOW_CAPTURE_BODY=0
+```
+
+---
+
+## Complete Environment Variables Reference
+
+```env
+# === Required ===
+SECURENOW_APPID=my-express-app
+SECURENOW_INSTANCE=http://localhost:4318
+
+# === Logging ===
+SECURENOW_LOGGING_ENABLED=1
+
+# === Request Body Capture ===
+SECURENOW_CAPTURE_BODY=1
+SECURENOW_MAX_BODY_SIZE=10240
+SECURENOW_SENSITIVE_FIELDS=custom_field1,custom_field2
+
+# === Service Naming ===
+SECURENOW_NO_UUID=1
+OTEL_SERVICE_NAME=my-express-app
+
+# === Connection ===
+OTEL_EXPORTER_OTLP_HEADERS=x-api-key=your-key
+OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4318/v1/traces
+OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://localhost:4318/v1/logs
+
+# === Debugging ===
+OTEL_LOG_LEVEL=debug
+SECURENOW_TEST_SPAN=1
+
+# === Environment ===
+NODE_ENV=production
+```
+
+---
+
+## Next Steps
+
+- Check your observability backend to see traces and logs
+- Set up dashboards and alerts
+- Explore the captured data to understand your application behavior
+
+---
+
+## Support
+
+- **Documentation:** [Main Docs](../README.md)
+- **Examples:** [Express Examples](../examples/)
+- **Issues:** GitHub Issues
+
+---
+
+**Your Express app is now fully observable!** 🎉