securenow 5.0.0 → 5.0.2

package/docs/EXPRESS-SETUP-GUIDE.md

@@ -0,0 +1,720 @@
+# 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!** 🎉