securenow 5.0.0 → 5.0.2

package/docs/ALL-FRAMEWORKS-QUICKSTART.md

@@ -0,0 +1,455 @@
+# Quick Start Guide - All Frameworks
+
+Fast setup guide for SecureNow with any Node.js framework in under 5 minutes.
+
+---
+
+## Universal Setup (Works with Any Framework)
+
+### Step 1: Install
+
+```bash
+npm install securenow
+```
+
+### Step 2: Set Environment Variables
+
+```bash
+export SECURENOW_APPID=my-app
+export SECURENOW_INSTANCE=http://localhost:4318
+export SECURENOW_LOGGING_ENABLED=1
+```
+
+### Step 3: Initialize
+
+**Option A: Using NODE_OPTIONS (No code changes)**
+
+```bash
+NODE_OPTIONS="-r securenow/register -r securenow/console-instrumentation" node app.js
+```
+
+**Option B: Add to your code**
+
+```javascript
+// At the very top of your main file
+require('securenow/register');
+require('securenow/console-instrumentation');
+
+// Rest of your application
+```
+
+**Done!** Your app is now sending traces and logs.
+
+---
+
+## Framework-Specific Quick Starts
+
+### Express.js
+
+```javascript
+// app.js
+require('securenow/register');
+require('securenow/console-instrumentation');
+
+const express = require('express');
+const app = express();
+
+app.get('/', (req, res) => {
+  console.log('Request received');
+  res.send('Hello World');
+});
+
+app.listen(3000);
+```
+
+**Run:**
+```bash
+SECURENOW_APPID=express-app \
+SECURENOW_INSTANCE=http://localhost:4318 \
+node app.js
+```
+
+[Full Express Guide →](./EXPRESS-SETUP-GUIDE.md)
+
+---
+
+### Next.js (App Router)
+
+**1. Create `instrumentation.ts` in project root:**
+
+```typescript
+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');
+  }
+}
+```
+
+**2. Enable in `next.config.js`:**
+
+```javascript
+module.exports = {
+  experimental: {
+    instrumentationHook: true,
+  },
+};
+```
+
+**3. Create `.env.local`:**
+
+```env
+SECURENOW_APPID=nextjs-app
+SECURENOW_INSTANCE=http://localhost:4318
+```
+
+**4. Run:**
+
+```bash
+npm run dev
+```
+
+[Full Next.js Guide →](./NEXTJS-SETUP-COMPLETE.md)
+
+---
+
+### Fastify
+
+```javascript
+// server.js
+require('securenow/register');
+require('securenow/console-instrumentation');
+
+const fastify = require('fastify')();
+
+fastify.get('/', async () => {
+  console.log('Route called');
+  return { hello: 'world' };
+});
+
+fastify.listen({ port: 3000 });
+```
+
+**Run:**
+```bash
+SECURENOW_APPID=fastify-app node server.js
+```
+
+---
+
+### NestJS
+
+```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);
+  await app.listen(3000);
+}
+
+bootstrap();
+```
+
+**Run:**
+```bash
+npm run start
+```
+
+---
+
+### Koa
+
+```javascript
+// app.js
+require('securenow/register');
+require('securenow/console-instrumentation');
+
+const Koa = require('koa');
+const app = new Koa();
+
+app.use(async ctx => {
+  console.log('Request received');
+  ctx.body = 'Hello World';
+});
+
+app.listen(3000);
+```
+
+---
+
+### Hapi
+
+```javascript
+// server.js
+require('securenow/register');
+require('securenow/console-instrumentation');
+
+const Hapi = require('@hapi/hapi');
+
+const init = async () => {
+  const server = Hapi.server({ port: 3000 });
+  
+  server.route({
+    method: 'GET',
+    path: '/',
+    handler: () => {
+      console.log('Route called');
+      return 'Hello World';
+    }
+  });
+  
+  await server.start();
+};
+
+init();
+```
+
+---
+
+## Environment Variables
+
+### Minimal Setup
+
+```bash
+SECURENOW_APPID=my-app
+SECURENOW_INSTANCE=http://localhost:4318
+```
+
+### Recommended Setup
+
+```bash
+SECURENOW_APPID=my-app
+SECURENOW_INSTANCE=http://localhost:4318
+SECURENOW_LOGGING_ENABLED=1
+SECURENOW_CAPTURE_BODY=1
+NODE_ENV=development
+```
+
+### Production Setup
+
+```bash
+SECURENOW_APPID=my-app-prod
+SECURENOW_INSTANCE=http://collector.prod:4318
+OTEL_EXPORTER_OTLP_HEADERS=x-api-key=your-key
+SECURENOW_LOGGING_ENABLED=1
+SECURENOW_NO_UUID=1
+SECURENOW_CAPTURE_BODY=0
+NODE_ENV=production
+```
+
+[Complete Environment Variables Reference →](./ENVIRONMENT-VARIABLES.md)
+
+---
+
+## Logging Examples
+
+### Automatic Console Logging
+
+```javascript
+// All console methods are automatically captured
+console.log('Application started');
+console.info('User action', { userId: 123 });
+console.warn('Warning message');
+console.error('Error occurred', { error: 'details' });
+```
+
+### Direct Logger API
+
+```javascript
+const { getLogger } = require('securenow/tracing');
+const logger = getLogger('my-module', '1.0.0');
+
+logger.emit({
+  severityNumber: 9,
+  severityText: 'INFO',
+  body: 'Custom log message',
+  attributes: {
+    userId: 123,
+    action: 'login',
+  },
+});
+```
+
+[Complete Logging Guide →](./LOGGING-GUIDE.md)
+
+---
+
+## Request Body Capture
+
+Enable request body capture for debugging:
+
+```bash
+export SECURENOW_CAPTURE_BODY=1
+export SECURENOW_MAX_BODY_SIZE=10240  # 10KB
+```
+
+**Automatically redacted:** passwords, tokens, API keys, card numbers, etc.
+
+---
+
+## PM2 Setup
+
+```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-app',
+      SECURENOW_INSTANCE: 'http://localhost:4318',
+      SECURENOW_LOGGING_ENABLED: '1',
+      SECURENOW_NO_UUID: '1',
+    }
+  }]
+};
+```
+
+```bash
+pm2 start ecosystem.config.js
+```
+
+---
+
+## Docker Setup
+
+```dockerfile
+FROM node:20-alpine
+
+WORKDIR /app
+
+COPY package*.json ./
+RUN npm install
+
+COPY . .
+
+ENV SECURENOW_APPID=my-app
+ENV SECURENOW_INSTANCE=http://collector:4318
+ENV SECURENOW_LOGGING_ENABLED=1
+
+EXPOSE 3000
+CMD ["node", "app.js"]
+```
+
+---
+
+## Verification
+
+After starting your app, you should see:
+
+```
+[securenow] OTel SDK started → http://localhost:4318/v1/traces
+[securenow] 📋 Logging: ENABLED → http://localhost:4318/v1/logs
+[securenow] Console instrumentation installed
+```
+
+Check your observability backend - traces and logs should appear within seconds.
+
+---
+
+## Troubleshooting
+
+### Traces Not Appearing
+
+1. Check environment variables:
+   ```bash
+   echo $SECURENOW_APPID
+   echo $SECURENOW_INSTANCE
+   ```
+
+2. Enable debug logging:
+   ```bash
+   export OTEL_LOG_LEVEL=debug
+   node app.js
+   ```
+
+3. Verify collector is running:
+   ```bash
+   curl http://localhost:4318/v1/traces
+   ```
+
+### Logs Not Appearing
+
+1. Check logging is enabled:
+   ```bash
+   echo $SECURENOW_LOGGING_ENABLED  # Should be: 1
+   ```
+
+2. Verify console instrumentation loaded:
+   ```
+   [securenow] Console instrumentation installed
+   ```
+
+3. Check initialization order:
+   ```javascript
+   // ✅ Correct
+   require('securenow/register');
+   require('securenow/console-instrumentation');
+   const express = require('express');
+   
+   // ❌ Wrong
+   const express = require('express');
+   require('securenow/register');
+   ```
+
+---
+
+## Complete Documentation
+
+- **[NPM README](../NPM_README.md)** - Full npm package documentation
+- **[Express Guide](./EXPRESS-SETUP-GUIDE.md)** - Complete Express.js setup
+- **[Next.js Guide](./NEXTJS-SETUP-COMPLETE.md)** - Complete Next.js setup
+- **[Logging Guide](./LOGGING-GUIDE.md)** - Complete logging reference
+- **[Environment Variables](./ENVIRONMENT-VARIABLES.md)** - All variables explained
+
+---
+
+## What Gets Instrumented Automatically
+
+- HTTP/HTTPS (incoming and outgoing)
+- Express.js, Fastify, Koa, Hapi, Next.js
+- PostgreSQL, MySQL, MongoDB, Redis
+- GraphQL, gRPC
+- axios, fetch, node-fetch, got
+- And 50+ more libraries
+
+**No code changes needed!**
+
+---
+
+## Performance
+
+- **< 1% overhead:** Minimal CPU and memory impact
+- **Async processing:** No blocking of requests
+- **Batch export:** Efficient data transmission
+- **Production-ready:** Battle-tested in high-traffic applications
+
+---
+
+## Security
+
+- **Automatic redaction** of sensitive fields
+- **Configurable** field patterns
+- **No local storage** - data goes directly to your backend
+- **Open source** - audit the code yourself
+
+---
+
+## 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)
+
+---
+
+**Get your app observable in under 5 minutes!** 🚀