securenow 6.0.2 → 6.1.0

package/CONSUMING-APPS-GUIDE.md

@@ -0,0 +1,455 @@
+# How to Use SecureNow Logging in Your App
+
+This guide is for developers who want to add the `securenow` package to their applications to enable logging to SecureNow or any OTLP-compatible backend.
+
+**Since v5.6.0:** When `SECURENOW_LOGGING_ENABLED=1`, `console.log`, `console.warn`, `console.error`, `console.info`, and `console.debug` are **automatically** forwarded as OTLP log records after you load `securenow/register`. A separate `require('securenow/console-instrumentation')` is no longer required (the module remains for backward compatibility).
+
+---
+
+## Installation
+
+```bash
+npm install securenow
+```
+
+---
+
+## Setup Steps
+
+### Step 1: Configure Environment Variables
+
+Add these to your `.env` file or export them:
+
+```bash
+# Required: Enable logging
+SECURENOW_LOGGING_ENABLED=1
+
+# Required: Your app name
+SECURENOW_APPID=my-app-name
+
+# Required: Your OTLP endpoint
+SECURENOW_INSTANCE=http://your-otlp-collector:4318
+
+# For managed OTLP / authentication (optional):
+# OTEL_EXPORTER_OTLP_HEADERS="x-api-key=your-key"
+```
+
+---
+
+### Step 2: Choose Your Integration Method
+
+You have **three options** to integrate logging:
+
+#### **Option A: Automatic Console Instrumentation** (Recommended - Easiest)
+
+Since **v5.6.0**, when `SECURENOW_LOGGING_ENABLED=1`, all `console.log()`, `console.info()`, `console.warn()`, `console.error()`, and `console.debug()` calls are **automatically** captured and sent as OTLP log records. No extra require is needed.
+
+**Add to your main application file:**
+
+```javascript
+// At the very top of your app.js, index.js, server.js, or main.ts
+require('securenow/register');
+
+// That's it! With SECURENOW_LOGGING_ENABLED=1, all console calls become OTLP logs.
+console.log('Application started');
+console.error('An error occurred', { userId: 123, details: 'Something went wrong' });
+console.warn('Warning message');
+```
+
+**Or using NODE_OPTIONS (no code changes needed):**
+
+```bash
+NODE_OPTIONS="-r securenow/register" node app.js
+```
+
+---
+
+#### **Option B: Direct Logger API**
+
+For more control over logging, use the OpenTelemetry logger API directly:
+
+```javascript
+require('securenow/register');
+const { getLogger } = require('securenow/tracing');
+
+// Get a logger instance
+const logger = getLogger('my-service', '1.0.0');
+
+// Emit structured logs
+logger.emit({
+  severityNumber: 9,      // INFO level
+  severityText: 'INFO',
+  body: 'User logged in',
+  attributes: {
+    userId: 123,
+    username: 'john',
+    ip: '192.168.1.1',
+  },
+});
+```
+
+**Severity Levels:**
+- `5` = DEBUG
+- `9` = INFO
+- `13` = WARN
+- `17` = ERROR
+
+---
+
+#### **Option C: Custom Logger Wrapper**
+
+Create your own logger wrapper for cleaner API:
+
+```javascript
+// logger.js
+require('securenow/register');
+const { getLogger } = require('securenow/tracing');
+
+const logger = getLogger('app-logger', '1.0.0');
+
+const SeverityNumber = {
+  DEBUG: 5,
+  INFO: 9,
+  WARN: 13,
+  ERROR: 17,
+};
+
+function log(level, message, attributes = {}) {
+  if (logger) {
+    logger.emit({
+      severityNumber: SeverityNumber[level],
+      severityText: level,
+      body: message,
+      attributes,
+    });
+  }
+  console.log(`[${level}] ${message}`, attributes);
+}
+
+module.exports = {
+  debug: (msg, attrs) => log('DEBUG', msg, attrs),
+  info: (msg, attrs) => log('INFO', msg, attrs),
+  warn: (msg, attrs) => log('WARN', msg, attrs),
+  error: (msg, attrs) => log('ERROR', msg, attrs),
+};
+```
+
+**Usage:**
+
+```javascript
+const logger = require('./logger');
+
+logger.info('User signed up', { userId: 456, email: 'user@example.com' });
+logger.error('Payment failed', { orderId: 789, amount: 99.99 });
+```
+
+---
+
+## Framework-Specific Setup
+
+### Express.js
+
+```javascript
+// app.js
+require('securenow/register');
+
+const express = require('express');
+const app = express();
+
+app.get('/', (req, res) => {
+  console.log('Home page accessed');
+  res.send('Hello World');
+});
+
+app.listen(3000, () => {
+  console.log('Server running on port 3000');
+});
+```
+
+**Run:**
+```bash
+SECURENOW_LOGGING_ENABLED=1 SECURENOW_APPID=express-app node app.js
+```
+
+---
+
+### Next.js (App Router)
+
+**1. Run `npx securenow init`** or create `instrumentation.ts` in your project root:
+
+```typescript
+// instrumentation.ts
+export async function register() {
+  if (process.env.NEXT_RUNTIME === 'nodejs') {
+    const { registerSecureNow } = require('securenow/nextjs');
+    registerSecureNow();
+  }
+}
+```
+
+**2. Update `next.config.js` with `withSecureNow()`:**
+
+```javascript
+const { withSecureNow } = require('securenow/nextjs-webpack-config');
+
+module.exports = withSecureNow({
+  // your existing config
+});
+```
+
+This auto-detects Next.js 14 vs 15 and sets the correct `serverExternalPackages` / `experimental.serverComponentsExternalPackages` config.
+
+**3. Add to `.env.local`:**
+
+```bash
+SECURENOW_LOGGING_ENABLED=1
+SECURENOW_APPID=my-nextjs-app
+SECURENOW_INSTANCE=http://localhost:4318
+SECURENOW_API_KEY=snk_live_abc123...
+```
+
+**4. Use in API routes:**
+
+```typescript
+// app/api/users/route.ts
+export async function GET() {
+  console.log('GET /api/users called');
+  const users = await fetchUsers();
+  console.info('Users fetched', { count: users.length });
+  return Response.json(users);
+}
+```
+
+---
+
+### Fastify
+
+```javascript
+// server.js
+require('securenow/register');
+
+const fastify = require('fastify')();
+
+fastify.get('/', async () => {
+  console.log('Root endpoint called');
+  return { hello: 'world' };
+});
+
+fastify.listen({ port: 3000 });
+```
+
+---
+
+### NestJS
+
+```typescript
+// main.ts
+require('securenow/register');
+
+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);
+}
+
+bootstrap();
+```
+
+---
+
+## Verification
+
+After starting your app, you should see:
+
+```
+[securenow] OTel SDK started → http://your-otlp-collector:4318/v1/traces
+[securenow] 📋 Logging: ENABLED → http://your-otlp-collector:4318/v1/logs
+[securenow] Console instrumentation installed
+```
+
+---
+
+## View Logs in SecureNow
+
+1. Open your SecureNow dashboard
+2. Go to **Logs** section
+3. Filter by `service.name = my-app-name`
+4. See all your logs with:
+   - Automatic severity levels
+   - Structured attributes
+   - Trace correlation
+
+---
+
+## Common Issues
+
+### Logs Not Appearing
+
+**Check 1:** Verify `SECURENOW_LOGGING_ENABLED=1` is set
+
+```bash
+echo $SECURENOW_LOGGING_ENABLED  # Should output: 1
+```
+
+**Check 2:** Verify endpoint is correct
+
+```bash
+# Self-hosted OTLP collector
+export SECURENOW_INSTANCE=http://localhost:4318
+
+# Managed OTLP (example)
+export SECURENOW_INSTANCE=https://ingest.<region>.securenow.ai:443
+export OTEL_EXPORTER_OTLP_HEADERS="x-api-key=<your-key>"
+```
+
+**Check 3:** Enable debug logging
+
+```bash
+export OTEL_LOG_LEVEL=debug
+node app.js
+```
+
+---
+
+### Console Instrumentation Not Working
+
+Make sure the load order is correct:
+
+```javascript
+// ✅ Correct — register must be first
+require('securenow/register');
+const express = require('express');
+
+// ❌ Wrong
+const express = require('express');
+require('securenow/register');
+```
+
+---
+
+### Logger Returns Null
+
+This happens when logging is disabled:
+
+```javascript
+const { getLogger } = require('securenow/tracing');
+const logger = getLogger('test');
+
+if (!logger) {
+  console.log('Set SECURENOW_LOGGING_ENABLED=1 to enable logging');
+}
+```
+
+---
+
+## Environment Variables Reference
+
+```bash
+# Logging
+SECURENOW_LOGGING_ENABLED=1              # Enable/disable logging (default: 1)
+
+# Connection
+SECURENOW_INSTANCE=http://localhost:4318 # OTLP endpoint
+OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=...     # Override logs endpoint
+
+# Authentication
+OTEL_EXPORTER_OTLP_HEADERS="x-api-key=KEY"
+
+# Service Info
+SECURENOW_APPID=my-app                   # Your app name
+OTEL_SERVICE_NAME=my-app                 # Alternative
+
+# Request Body Capture
+SECURENOW_CAPTURE_BODY=1                 # Capture JSON/form/GraphQL request bodies
+SECURENOW_MAX_BODY_SIZE=10240            # Max body size in bytes (default: 10KB)
+SECURENOW_SENSITIVE_FIELDS="field1,field2" # Additional fields to redact
+
+# Multipart Body Capture (v5.8.0+)
+SECURENOW_CAPTURE_MULTIPART=1            # Capture multipart field values & file metadata (streaming)
+
+# Debugging
+OTEL_LOG_LEVEL=debug                     # Enable debug output
+```
+
+---
+
+## Best Practices
+
+1. **Use Structured Logging** - Pass objects with meaningful attributes
+   ```javascript
+   console.log('User action', { userId: 123, action: 'login' });
+   ```
+
+2. **Choose Appropriate Severity Levels**
+   - `console.log()` / `console.info()` - Normal operations
+   - `console.warn()` - Warnings, deprecations
+   - `console.error()` - Errors, exceptions
+
+3. **Include Context** - Add userId, requestId, etc. to log attributes
+
+4. **Don't Log Sensitive Data** - SecureNow automatically redacts passwords, tokens, etc.
+
+5. **Use Different Loggers for Different Modules**
+   ```javascript
+   const authLogger = getLogger('auth-service');
+   const dbLogger = getLogger('database');
+   ```
+
+---
+
+---
+
+## Firewall — Automatic IP Blocking
+
+If you use the SecureNow blocklist to block malicious IPs, the firewall module can enforce that blocklist directly in your app with zero code changes.
+
+### Enable It
+
+Add your API key to `.env`:
+
+```bash
+SECURENOW_API_KEY=snk_live_abc123...
+```
+
+The firewall activates automatically on startup and syncs the blocklist using a version-based protocol:
+
+```
+[securenow] Firewall: ENABLED
+[securenow] Firewall: Layer 1 (HTTP 403)      active
+[securenow] Firewall: synced 142 blocked IPs (138 exact + 4 CIDR ranges)
+```
+
+Blocked IPs get a 403 Forbidden with a full security alert page. Changes propagate in 10-15 seconds. No code changes needed -- works with Express, Next.js, Nuxt, Fastify, and all Node.js frameworks.
+
+**Firewall-only mode** (no tracing overhead):
+
+```bash
+node -r securenow/firewall-only app.js
+```
+
+See the [Firewall Guide](./docs/FIREWALL-GUIDE.md) for advanced layers (TCP blocking, iptables, Cloud WAF).
+
+---
+
+## Complete Documentation
+
+- [Firewall Guide](./docs/FIREWALL-GUIDE.md)
+- [API Keys Guide](./docs/API-KEYS-GUIDE.md)
+- [Logging Quick Start](./docs/LOGGING-QUICKSTART.md)
+- [Logging Complete Guide](./docs/LOGGING-GUIDE.md)
+- [All Examples](./examples/)
+
+---
+
+## Support
+
+- **Documentation**: [Full Docs](./docs/INDEX.md)
+- **Website**: [securenow.ai](http://securenow.ai/)
+- **Issues**: GitHub Issues
+
+---
+
+**That's it!** Your app is now sending logs to your OTLP backend (for example SecureNow). 🎉