securenow 5.10.2 → 5.11.0

package/docs/ENVIRONMENT-VARIABLES.md

@@ -1,697 +1,880 @@
-# SecureNow Environment Variables Reference
-
-Complete reference for all environment variables supported by SecureNow.
-
----
-
-## Quick Reference Table
-
-| Variable | Type | Default | Description |
-|----------|------|---------|-------------|
-| **SECURENOW_APPID** | Required | - | Application identifier / service name |
-| **SECURENOW_INSTANCE** | Required | `https://freetrial.securenow.ai:4318` | OTLP collector base URL |
-| **SECURENOW_LOGGING_ENABLED** | Optional | `1` | Enable/disable logging |
-| **SECURENOW_NO_UUID** | Optional | `0` | Disable UUID suffix on service name |
-| **SECURENOW_STRICT** | Optional | `0` | Exit if APPID missing in cluster mode |
-| **SECURENOW_CAPTURE_BODY** | Optional | `0` | Enable request body capture |
-| **SECURENOW_MAX_BODY_SIZE** | Optional | `10240` | Max body size in bytes |
-| **SECURENOW_SENSITIVE_FIELDS** | Optional | - | Comma-separated list of fields to redact |
-| **SECURENOW_CAPTURE_MULTIPART** | Optional | `0` | Enable multipart/form-data streaming capture |
-| **SECURENOW_DISABLE_INSTRUMENTATIONS** | Optional | - | Comma-separated list of packages to disable |
-| **SECURENOW_TEST_SPAN** | Optional | `0` | Emit test span on startup |
-| **OTEL_SERVICE_NAME** | Optional | - | Alternative to SECURENOW_APPID |
-| **OTEL_EXPORTER_OTLP_ENDPOINT** | Optional | - | Alternative to SECURENOW_INSTANCE |
-| **OTEL_EXPORTER_OTLP_HEADERS** | Optional | - | Headers for OTLP requests |
-| **OTEL_EXPORTER_OTLP_TRACES_ENDPOINT** | Optional | - | Override traces endpoint |
-| **OTEL_EXPORTER_OTLP_LOGS_ENDPOINT** | Optional | - | Override logs endpoint |
-| **OTEL_LOG_LEVEL** | Optional | `none` | SDK log level |
-| **NODE_ENV** | Optional | `production` | Environment name |
-
----
-
-## Required Variables
-
-### SECURENOW_APPID
-
-**Description:** Your application identifier. Used as the service name in traces and logs.
-
-**Format:** String (alphanumeric, hyphens, underscores)
-
-**Examples:**
-```bash
-export SECURENOW_APPID=my-express-app
-export SECURENOW_APPID=api-gateway
-export SECURENOW_APPID=user-service
-```
-
-**Notes:**
-- If not set, SecureNow will use a fallback name with UUID
-- In cluster mode with `SECURENOW_STRICT=1`, missing APPID will cause process exit
-- Alternative: Use `OTEL_SERVICE_NAME` (OpenTelemetry standard)
-
-**Behavior:**
-- Without `SECURENOW_NO_UUID=1`: Service name becomes `{APPID}-{UUID}`
-- With `SECURENOW_NO_UUID=1`: Service name is exactly `{APPID}`
-
----
-
-### SECURENOW_INSTANCE
-
-**Description:** Base URL of your OTLP collector endpoint.
-
-**Format:** URL (http/https)
-
-**Examples:**
-```bash
-# Local collector
-export SECURENOW_INSTANCE=http://localhost:4318
-
-# Remote collector
-export SECURENOW_INSTANCE=http://collector.example.com:4318
-
-# HTTPS
-export SECURENOW_INSTANCE=https://collector.example.com:4318
-```
-
-**Default:** `https://freetrial.securenow.ai:4318` (if not set)
-
-**Notes:**
-- Used to construct traces and logs endpoints
-- Traces sent to: `{SECURENOW_INSTANCE}/v1/traces`
-- Logs sent to: `{SECURENOW_INSTANCE}/v1/logs`
-- Alternative: Use `OTEL_EXPORTER_OTLP_ENDPOINT`
-
----
-
-## Service Naming
-
-### OTEL_SERVICE_NAME
-
-**Description:** Standard OpenTelemetry variable for service name. Alternative to `SECURENOW_APPID`.
-
-**Format:** String
-
-**Example:**
-```bash
-export OTEL_SERVICE_NAME=my-app
-```
-
-**Priority:** If both are set, `OTEL_SERVICE_NAME` takes precedence.
-
----
-
-### SECURENOW_NO_UUID
-
-**Description:** Disable automatic UUID suffix on service name.
-
-**Format:** `1` (enabled) or `0` (disabled)
-
-**Default:** `0`
-
-**Example:**
-```bash
-export SECURENOW_NO_UUID=1
-```
-
-**Use case:**
-- PM2 cluster mode - use same service name for all workers
-- Docker containers with replica sets
-- Kubernetes pods in a deployment
-
-**Behavior:**
-- `0`: Service name = `my-app-a1b2c3d4`
-- `1`: Service name = `my-app`
-
----
-
-### SECURENOW_STRICT
-
-**Description:** Exit process if `SECURENOW_APPID` is not set in cluster mode.
-
-**Format:** `1` (enabled) or `0` (disabled)
-
-**Default:** `0`
-
-**Example:**
-```bash
-export SECURENOW_STRICT=1
-```
-
-**Use case:**
-- Production environments where service name must be explicit
-- Prevent "free" or auto-generated service names
-- Ensure proper configuration before starting
-
-**Detection:**
-Cluster mode is detected when any of these exist:
-- `NODE_APP_INSTANCE` (PM2)
-- `pm_id` (PM2)
-
----
-
-## Connection Settings
-
-### OTEL_EXPORTER_OTLP_ENDPOINT
-
-**Description:** Standard OpenTelemetry variable for OTLP endpoint. Alternative to `SECURENOW_INSTANCE`.
-
-**Format:** URL
-
-**Example:**
-```bash
-export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
-```
-
-**Priority:** If both are set, `OTEL_EXPORTER_OTLP_ENDPOINT` takes precedence.
-
----
-
-### OTEL_EXPORTER_OTLP_TRACES_ENDPOINT
-
-**Description:** Override the traces endpoint specifically.
-
-**Format:** Full URL including `/v1/traces`
-
-**Example:**
-```bash
-export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://traces-collector:4318/v1/traces
-```
-
-**Use case:**
-- Separate collectors for traces and logs
-- Different routing for traces
-
----
-
-### OTEL_EXPORTER_OTLP_LOGS_ENDPOINT
-
-**Description:** Override the logs endpoint specifically.
-
-**Format:** Full URL including `/v1/logs`
-
-**Example:**
-```bash
-export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://logs-collector:4318/v1/logs
-```
-
-**Use case:**
-- Separate collectors for traces and logs
-- Different routing for logs
-
----
-
-### OTEL_EXPORTER_OTLP_HEADERS
-
-**Description:** Headers to include in OTLP export requests.
-
-**Format:** Comma-separated `key=value` pairs
-
-**Examples:**
-```bash
-# Single header
-export OTEL_EXPORTER_OTLP_HEADERS="x-api-key=your-api-key"
-
-# Multiple headers
-export OTEL_EXPORTER_OTLP_HEADERS="x-api-key=key123,x-tenant-id=tenant456"
-
-# Authentication
-export OTEL_EXPORTER_OTLP_HEADERS="authorization=Bearer token123"
-```
-
-**Use case:**
-- API authentication
-- Multi-tenancy headers
-- Custom routing headers
-
-**Notes:**
-- Header names are case-insensitive
-- Trailing/leading spaces are trimmed
-
----
-
-## Logging
-
-### SECURENOW_LOGGING_ENABLED
-
-**Description:** Enable or disable automatic logging to OTLP backend.
-
-**Format:** `1` (enabled) or `0` (disabled)
-
-**Default:** `1` (enabled by default)
-
-**Examples:**
-```bash
-# Enable logging
-export SECURENOW_LOGGING_ENABLED=1
-
-# Disable logging
-export SECURENOW_LOGGING_ENABLED=0
-```
-
-**When enabled:**
-- Logs are sent to `{SECURENOW_INSTANCE}/v1/logs`
-- Console instrumentation can capture logs
-- Direct logger API is available
-
-**When disabled:**
-- No logs sent to backend
-- `getLogger()` returns `null`
-- Console instrumentation shows warning
-
----
-
-## Request Body Capture
-
-### SECURENOW_CAPTURE_BODY
-
-**Description:** Enable capture of HTTP request bodies in traces.
-
-**Format:** `1` (enabled) or `0` (disabled)
-
-**Default:** `0` (disabled)
-
-**Example:**
-```bash
-export SECURENOW_CAPTURE_BODY=1
-```
-
-**Supported content types:**
-- `application/json`
-- `application/x-www-form-urlencoded`
-- `application/graphql`
-
-**Not captured (unless separately enabled):**
-- `multipart/form-data` — requires `SECURENOW_CAPTURE_MULTIPART=1` (see below)
-- Bodies larger than `SECURENOW_MAX_BODY_SIZE`
-
-**Security:**
-All captured bodies are automatically scanned for sensitive fields and redacted.
-
----
-
-### SECURENOW_MAX_BODY_SIZE
-
-**Description:** Maximum request body size to capture (in bytes).
-
-**Format:** Number (bytes)
-
-**Default:** `10240` (10 KB)
-
-**Examples:**
-```bash
-# 10 KB (default)
-export SECURENOW_MAX_BODY_SIZE=10240
-
-# 20 KB
-export SECURENOW_MAX_BODY_SIZE=20480
-
-# 5 KB
-export SECURENOW_MAX_BODY_SIZE=5120
-```
-
-**Behavior:**
-- Bodies larger than this are not captured
-- Span attribute shows: `[TOO LARGE: {size} bytes]`
-
----
-
-### SECURENOW_SENSITIVE_FIELDS
-
-**Description:** Additional field names to redact from request bodies (comma-separated).
-
-**Format:** Comma-separated list of field names
-
-**Default:** (see below for auto-redacted fields)
-
-**Examples:**
-```bash
-# Additional custom fields
-export SECURENOW_SENSITIVE_FIELDS="internal_token,session_key"
-
-# Multiple fields
-export SECURENOW_SENSITIVE_FIELDS="custom_secret,private_data,internal_id"
-```
-
-**Auto-redacted fields (built-in):**
-- `password`, `passwd`, `pwd`
-- `secret`, `token`, `api_key`, `apikey`, `access_token`
-- `auth`, `credentials`, `mysql_pwd`
-- `stripeToken`, `card`, `cardnumber`
-- `ccv`, `cvc`, `cvv`
-- `ssn`, `pin`
-
-**Matching:**
-- Case-insensitive
-- Substring match (e.g., `password` matches `user_password`, `PASSWORD`, `passwordField`)
-- Works recursively in nested objects
-
----
-
-### SECURENOW_CAPTURE_MULTIPART
-
-**Description:** Enable capture of `multipart/form-data` request bodies (file upload metadata and text fields). Uses a streaming parser that processes boundary markers on the fly — file binary content is never buffered or stored.
-
-**Format:** `1` (enabled) or `0` (disabled)
-
-**Default:** `0` (disabled)
-
-**Example:**
-```bash
-export SECURENOW_CAPTURE_MULTIPART=1
-```
-
-**What gets captured:**
-- **Text fields** — field name and value (up to 1000 characters), with sensitive fields auto-redacted
-- **File fields** — metadata only: field name, filename, content-type, and size in bytes (no binary content)
-
-**Example span attribute (`http.request.body`):**
-```json
-{
-  "fields": { "description": "My upload", "token": "[REDACTED]" },
-  "files": [
-    { "field": "avatar", "filename": "photo.jpg", "contentType": "image/jpeg", "size": 524288 },
-    { "field": "document", "filename": "report.pdf", "contentType": "application/pdf", "size": 1048576 }
-  ]
-}
-```
-
-**Additional span attributes set:**
-- `http.request.body.type` = `"multipart"`
-- `http.request.body.size` — total raw request body size in bytes
-- `http.request.body.fields_count` — number of text fields
-- `http.request.body.files_count` — number of file fields
-
-**Memory:** Bounded at ~few KB regardless of upload size (streaming parser discards file content as it passes through).
-
-**Parts limit:** 100 parts maximum per request (safety guard).
-
-**Requires:** `SECURENOW_CAPTURE_BODY=1` must also be set (multipart capture is gated behind general body capture).
-
-**Since:** v5.8.0
-
----
-
-## Instrumentation Control
-
-### SECURENOW_DISABLE_INSTRUMENTATIONS
-
-**Description:** Disable specific OpenTelemetry instrumentations.
-
-**Format:** Comma-separated list of package names
-
-**Example:**
-```bash
-# Disable file system and DNS instrumentations
-export SECURENOW_DISABLE_INSTRUMENTATIONS=fs,dns
-
-# Disable multiple
-export SECURENOW_DISABLE_INSTRUMENTATIONS=fs,dns,net,http2
-```
-
-**Common packages you might disable:**
-- `fs` - File system operations
-- `dns` - DNS lookups
-- `net` - Network operations
-- `http2` - HTTP/2 client/server
-- `grpc` - gRPC client/server
-
-**Use case:**
-- Reduce overhead by disabling unused instrumentations
-- Avoid noisy traces from certain operations
-- Debug issues with specific instrumentations
-
----
-
-## Debugging
-
-### OTEL_LOG_LEVEL
-
-**Description:** OpenTelemetry SDK internal log level.
-
-**Format:** `none`, `error`, `warn`, `info`, `debug`
-
-**Default:** `none`
-
-**Examples:**
-```bash
-# See all debug information
-export OTEL_LOG_LEVEL=debug
-
-# Only errors
-export OTEL_LOG_LEVEL=error
-
-# No SDK logs
-export OTEL_LOG_LEVEL=none
-```
-
-**Use case:**
-- Troubleshooting setup issues
-- Understanding trace/log export behavior
-- Debugging connection problems
-
-**Output:**
-- Goes to console (stderr)
-- Prefixed with `[securenow]`
-
----
-
-### SECURENOW_TEST_SPAN
-
-**Description:** Emit a test span on startup to verify tracing is working.
-
-**Format:** `1` (enabled) or `0` (disabled)
-
-**Default:** `0`
-
-**Example:**
-```bash
-export SECURENOW_TEST_SPAN=1
-```
-
-**Behavior:**
-- Creates a span named `securenow.startup.smoke`
-- Span is immediately ended
-- Useful for testing collector connectivity
-
----
-
-## Environment
-
-### NODE_ENV
-
-**Description:** Standard Node.js environment variable. Sent as `deployment.environment` attribute.
-
-**Format:** String (typically: `development`, `production`, `test`, `staging`)
-
-**Default:** `production`
-
-**Examples:**
-```bash
-export NODE_ENV=development
-export NODE_ENV=production
-export NODE_ENV=staging
-export NODE_ENV=test
-```
-
-**Use case:**
-- Filter traces/logs by environment
-- Different configurations per environment
-- Standard Node.js convention
-
----
-
-## Configuration Examples
-
-### Development Environment
-
-```bash
-# .env.development
-SECURENOW_APPID=my-app-dev
-SECURENOW_INSTANCE=http://localhost:4318
-SECURENOW_LOGGING_ENABLED=1
-SECURENOW_CAPTURE_BODY=1
-SECURENOW_MAX_BODY_SIZE=20480
-OTEL_LOG_LEVEL=debug
-SECURENOW_TEST_SPAN=1
-NODE_ENV=development
-```
-
-### Production Environment
-
-```bash
-# .env.production
-SECURENOW_APPID=my-app-prod
-SECURENOW_INSTANCE=https://collector.prod.example.com:4318
-OTEL_EXPORTER_OTLP_HEADERS=x-api-key=prod-key-12345
-SECURENOW_LOGGING_ENABLED=1
-SECURENOW_CAPTURE_BODY=0
-SECURENOW_NO_UUID=1
-SECURENOW_STRICT=1
-SECURENOW_SENSITIVE_FIELDS=internal_id,session_token
-OTEL_LOG_LEVEL=error
-NODE_ENV=production
-```
-
-### PM2 Cluster
-
-```bash
-# ecosystem.config.js environment
-SECURENOW_APPID=my-app
-SECURENOW_INSTANCE=http://localhost:4318
-SECURENOW_LOGGING_ENABLED=1
-SECURENOW_NO_UUID=1
-SECURENOW_STRICT=1
-SECURENOW_CAPTURE_BODY=1
-NODE_ENV=production
-```
-
-### Docker / Kubernetes
-
-```bash
-# Docker environment or K8s ConfigMap
-SECURENOW_APPID=my-service
-SECURENOW_INSTANCE=http://otel-collector:4318
-SECURENOW_LOGGING_ENABLED=1
-SECURENOW_NO_UUID=1
-SECURENOW_CAPTURE_BODY=0
-NODE_ENV=production
-```
-
-### Separate Collectors for Traces and Logs
-
-```bash
-# Different backends for traces and logs
-SECURENOW_APPID=my-app
-OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://traces-collector:4318/v1/traces
-OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://logs-collector:4318/v1/logs
-SECURENOW_LOGGING_ENABLED=1
-```
-
----
-
-## Priority and Overrides
-
-When multiple variables are set, this is the priority order:
-
-### Service Name
-
-1. `OTEL_SERVICE_NAME` (highest priority)
-2. `SECURENOW_APPID`
-3. Auto-generated fallback (lowest priority)
-
-### OTLP Endpoint
-
-1. `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` (for traces)
-2. `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` (for logs)
-3. `OTEL_EXPORTER_OTLP_ENDPOINT`
-4. `SECURENOW_INSTANCE`
-5. Default: `https://freetrial.securenow.ai:4318` (lowest priority)
-
----
-
-## Validation
-
-SecureNow validates environment variables on startup. Check console output:
-
-```bash
-[securenow] pid=12345 SECURENOW_APPID="my-app" OTEL_SERVICE_NAME=null → service.name=my-app-uuid123
-[securenow] OTel SDK started → http://localhost:4318/v1/traces
-[securenow] 📋 Logging: ENABLED → http://localhost:4318/v1/logs
-[securenow] 📝 Request body capture: ENABLED (max: 10240 bytes)
-```
-
----
-
-## Best Practices
-
-### 1. Use .env Files
-
-Don't hardcode in your application:
-
-```bash
-# .env
-SECURENOW_APPID=my-app
-SECURENOW_INSTANCE=http://localhost:4318
-```
-
-### 2. Different Configs per Environment
-
-```bash
-# .env.development
-SECURENOW_CAPTURE_BODY=1
-OTEL_LOG_LEVEL=debug
-
-# .env.production
-SECURENOW_CAPTURE_BODY=0
-OTEL_LOG_LEVEL=error
-```
-
-### 3. Use SECURENOW_NO_UUID in Clusters
-
-```bash
-# PM2 cluster with 4 workers
-SECURENOW_NO_UUID=1
-```
-
-### 4. Enable SECURENOW_STRICT in Production
-
-```bash
-# Fail fast if misconfigured
-SECURENOW_STRICT=1
-```
-
-### 5. Disable Body Capture in Production
-
-```bash
-# Development
-SECURENOW_CAPTURE_BODY=1
-
-# Production
-SECURENOW_CAPTURE_BODY=0
-```
-
----
-
-## Troubleshooting
-
-### Check Current Values
-
-```bash
-# Print all SECURENOW variables
-env | grep SECURENOW
-
-# Print all OTEL variables
-env | grep OTEL
-
-# Check specific variable
-echo $SECURENOW_APPID
-```
-
-### Verify in Application
-
-SecureNow logs current configuration on startup. Look for lines like:
-
-```
-[securenow] pid=12345 SECURENOW_APPID="my-app" → service.name=my-app
-[securenow] OTel SDK started → http://localhost:4318/v1/traces
-```
-
-### Enable Debug Mode
-
-```bash
-export OTEL_LOG_LEVEL=debug
-node app.js
-```
-
----
-
-## Related Documentation
-
-- [Express Setup Guide](./EXPRESS-SETUP-GUIDE.md)
-- [Next.js Setup Guide](./NEXTJS-SETUP-COMPLETE.md)
-- [Logging Guide](./LOGGING-GUIDE.md)
-- [NPM README](../NPM_README.md)
-
----
-
-**Complete reference for all SecureNow environment variables.** 🎯
+# SecureNow Environment Variables Reference
+
+Complete reference for all environment variables supported by SecureNow.
+
+---
+
+## Quick Reference Table
+
+| Variable | Type | Default | Description |
+|----------|------|---------|-------------|
+| **SECURENOW_APPID** | Required | - | Application identifier / service name |
+| **SECURENOW_INSTANCE** | Required | `https://freetrial.securenow.ai:4318` | OTLP collector base URL |
+| **SECURENOW_LOGGING_ENABLED** | Optional | `1` | Enable/disable logging |
+| **SECURENOW_NO_UUID** | Optional | `0` | Disable UUID suffix on service name |
+| **SECURENOW_STRICT** | Optional | `0` | Exit if APPID missing in cluster mode |
+| **SECURENOW_CAPTURE_BODY** | Optional | `0` | Enable request body capture |
+| **SECURENOW_MAX_BODY_SIZE** | Optional | `10240` | Max body size in bytes |
+| **SECURENOW_SENSITIVE_FIELDS** | Optional | - | Comma-separated list of fields to redact |
+| **SECURENOW_CAPTURE_MULTIPART** | Optional | `0` | Enable multipart/form-data streaming capture |
+| **SECURENOW_DISABLE_INSTRUMENTATIONS** | Optional | - | Comma-separated list of packages to disable |
+| **SECURENOW_TEST_SPAN** | Optional | `0` | Emit test span on startup |
+| **OTEL_SERVICE_NAME** | Optional | - | Alternative to SECURENOW_APPID |
+| **OTEL_EXPORTER_OTLP_ENDPOINT** | Optional | - | Alternative to SECURENOW_INSTANCE |
+| **OTEL_EXPORTER_OTLP_HEADERS** | Optional | - | Headers for OTLP requests |
+| **OTEL_EXPORTER_OTLP_TRACES_ENDPOINT** | Optional | - | Override traces endpoint |
+| **OTEL_EXPORTER_OTLP_LOGS_ENDPOINT** | Optional | - | Override logs endpoint |
+| **OTEL_LOG_LEVEL** | Optional | `none` | SDK log level |
+| **NODE_ENV** | Optional | `production` | Environment name |
+| **SECURENOW_API_KEY** | Optional | - | API key for firewall (auto-activates when set) |
+| **SECURENOW_API_URL** | Optional | `https://api.securenow.ai` | API base URL |
+| **SECURENOW_FIREWALL_ENABLED** | Optional | `1` | Firewall master kill-switch |
+| **SECURENOW_FIREWALL_SYNC_INTERVAL** | Optional | `60` | Blocklist refresh interval (seconds) |
+| **SECURENOW_FIREWALL_FAIL_MODE** | Optional | `open` | Behavior when API unreachable: open/closed |
+| **SECURENOW_FIREWALL_STATUS_CODE** | Optional | `403` | HTTP status for blocked requests |
+| **SECURENOW_FIREWALL_LOG** | Optional | `1` | Log blocked requests |
+| **SECURENOW_FIREWALL_TCP** | Optional | `0` | Enable Layer 2 TCP blocking |
+| **SECURENOW_FIREWALL_IPTABLES** | Optional | `0` | Enable Layer 3 iptables blocking |
+| **SECURENOW_FIREWALL_CLOUD** | Optional | - | Cloud WAF provider (cloudflare/aws/gcp) |
+| **SECURENOW_TRUSTED_PROXIES** | Optional | - | Trusted proxy IPs for X-Forwarded-For |
+
+---
+
+## Required Variables
+
+### SECURENOW_APPID
+
+**Description:** Your application identifier. Used as the service name in traces and logs.
+
+**Format:** String (alphanumeric, hyphens, underscores)
+
+**Examples:**
+```bash
+export SECURENOW_APPID=my-express-app
+export SECURENOW_APPID=api-gateway
+export SECURENOW_APPID=user-service
+```
+
+**Notes:**
+- If not set, SecureNow will use a fallback name with UUID
+- In cluster mode with `SECURENOW_STRICT=1`, missing APPID will cause process exit
+- Alternative: Use `OTEL_SERVICE_NAME` (OpenTelemetry standard)
+
+**Behavior:**
+- Without `SECURENOW_NO_UUID=1`: Service name becomes `{APPID}-{UUID}`
+- With `SECURENOW_NO_UUID=1`: Service name is exactly `{APPID}`
+
+---
+
+### SECURENOW_INSTANCE
+
+**Description:** Base URL of your OTLP collector endpoint.
+
+**Format:** URL (http/https)
+
+**Examples:**
+```bash
+# Local collector
+export SECURENOW_INSTANCE=http://localhost:4318
+
+# Remote collector
+export SECURENOW_INSTANCE=http://collector.example.com:4318
+
+# HTTPS
+export SECURENOW_INSTANCE=https://collector.example.com:4318
+```
+
+**Default:** `https://freetrial.securenow.ai:4318` (if not set)
+
+**Notes:**
+- Used to construct traces and logs endpoints
+- Traces sent to: `{SECURENOW_INSTANCE}/v1/traces`
+- Logs sent to: `{SECURENOW_INSTANCE}/v1/logs`
+- Alternative: Use `OTEL_EXPORTER_OTLP_ENDPOINT`
+
+---
+
+## Service Naming
+
+### OTEL_SERVICE_NAME
+
+**Description:** Standard OpenTelemetry variable for service name. Alternative to `SECURENOW_APPID`.
+
+**Format:** String
+
+**Example:**
+```bash
+export OTEL_SERVICE_NAME=my-app
+```
+
+**Priority:** If both are set, `OTEL_SERVICE_NAME` takes precedence.
+
+---
+
+### SECURENOW_NO_UUID
+
+**Description:** Disable automatic UUID suffix on service name.
+
+**Format:** `1` (enabled) or `0` (disabled)
+
+**Default:** `0`
+
+**Example:**
+```bash
+export SECURENOW_NO_UUID=1
+```
+
+**Use case:**
+- PM2 cluster mode - use same service name for all workers
+- Docker containers with replica sets
+- Kubernetes pods in a deployment
+
+**Behavior:**
+- `0`: Service name = `my-app-a1b2c3d4`
+- `1`: Service name = `my-app`
+
+---
+
+### SECURENOW_STRICT
+
+**Description:** Exit process if `SECURENOW_APPID` is not set in cluster mode.
+
+**Format:** `1` (enabled) or `0` (disabled)
+
+**Default:** `0`
+
+**Example:**
+```bash
+export SECURENOW_STRICT=1
+```
+
+**Use case:**
+- Production environments where service name must be explicit
+- Prevent "free" or auto-generated service names
+- Ensure proper configuration before starting
+
+**Detection:**
+Cluster mode is detected when any of these exist:
+- `NODE_APP_INSTANCE` (PM2)
+- `pm_id` (PM2)
+
+---
+
+## Connection Settings
+
+### OTEL_EXPORTER_OTLP_ENDPOINT
+
+**Description:** Standard OpenTelemetry variable for OTLP endpoint. Alternative to `SECURENOW_INSTANCE`.
+
+**Format:** URL
+
+**Example:**
+```bash
+export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
+```
+
+**Priority:** If both are set, `OTEL_EXPORTER_OTLP_ENDPOINT` takes precedence.
+
+---
+
+### OTEL_EXPORTER_OTLP_TRACES_ENDPOINT
+
+**Description:** Override the traces endpoint specifically.
+
+**Format:** Full URL including `/v1/traces`
+
+**Example:**
+```bash
+export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://traces-collector:4318/v1/traces
+```
+
+**Use case:**
+- Separate collectors for traces and logs
+- Different routing for traces
+
+---
+
+### OTEL_EXPORTER_OTLP_LOGS_ENDPOINT
+
+**Description:** Override the logs endpoint specifically.
+
+**Format:** Full URL including `/v1/logs`
+
+**Example:**
+```bash
+export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://logs-collector:4318/v1/logs
+```
+
+**Use case:**
+- Separate collectors for traces and logs
+- Different routing for logs
+
+---
+
+### OTEL_EXPORTER_OTLP_HEADERS
+
+**Description:** Headers to include in OTLP export requests.
+
+**Format:** Comma-separated `key=value` pairs
+
+**Examples:**
+```bash
+# Single header
+export OTEL_EXPORTER_OTLP_HEADERS="x-api-key=your-api-key"
+
+# Multiple headers
+export OTEL_EXPORTER_OTLP_HEADERS="x-api-key=key123,x-tenant-id=tenant456"
+
+# Authentication
+export OTEL_EXPORTER_OTLP_HEADERS="authorization=Bearer token123"
+```
+
+**Use case:**
+- API authentication
+- Multi-tenancy headers
+- Custom routing headers
+
+**Notes:**
+- Header names are case-insensitive
+- Trailing/leading spaces are trimmed
+
+---
+
+## Logging
+
+### SECURENOW_LOGGING_ENABLED
+
+**Description:** Enable or disable automatic logging to OTLP backend.
+
+**Format:** `1` (enabled) or `0` (disabled)
+
+**Default:** `1` (enabled by default)
+
+**Examples:**
+```bash
+# Enable logging
+export SECURENOW_LOGGING_ENABLED=1
+
+# Disable logging
+export SECURENOW_LOGGING_ENABLED=0
+```
+
+**When enabled:**
+- Logs are sent to `{SECURENOW_INSTANCE}/v1/logs`
+- Console instrumentation can capture logs
+- Direct logger API is available
+
+**When disabled:**
+- No logs sent to backend
+- `getLogger()` returns `null`
+- Console instrumentation shows warning
+
+---
+
+## Request Body Capture
+
+### SECURENOW_CAPTURE_BODY
+
+**Description:** Enable capture of HTTP request bodies in traces.
+
+**Format:** `1` (enabled) or `0` (disabled)
+
+**Default:** `0` (disabled)
+
+**Example:**
+```bash
+export SECURENOW_CAPTURE_BODY=1
+```
+
+**Supported content types:**
+- `application/json`
+- `application/x-www-form-urlencoded`
+- `application/graphql`
+
+**Not captured (unless separately enabled):**
+- `multipart/form-data` — requires `SECURENOW_CAPTURE_MULTIPART=1` (see below)
+- Bodies larger than `SECURENOW_MAX_BODY_SIZE`
+
+**Security:**
+All captured bodies are automatically scanned for sensitive fields and redacted.
+
+---
+
+### SECURENOW_MAX_BODY_SIZE
+
+**Description:** Maximum request body size to capture (in bytes).
+
+**Format:** Number (bytes)
+
+**Default:** `10240` (10 KB)
+
+**Examples:**
+```bash
+# 10 KB (default)
+export SECURENOW_MAX_BODY_SIZE=10240
+
+# 20 KB
+export SECURENOW_MAX_BODY_SIZE=20480
+
+# 5 KB
+export SECURENOW_MAX_BODY_SIZE=5120
+```
+
+**Behavior:**
+- Bodies larger than this are not captured
+- Span attribute shows: `[TOO LARGE: {size} bytes]`
+
+---
+
+### SECURENOW_SENSITIVE_FIELDS
+
+**Description:** Additional field names to redact from request bodies (comma-separated).
+
+**Format:** Comma-separated list of field names
+
+**Default:** (see below for auto-redacted fields)
+
+**Examples:**
+```bash
+# Additional custom fields
+export SECURENOW_SENSITIVE_FIELDS="internal_token,session_key"
+
+# Multiple fields
+export SECURENOW_SENSITIVE_FIELDS="custom_secret,private_data,internal_id"
+```
+
+**Auto-redacted fields (built-in):**
+- `password`, `passwd`, `pwd`
+- `secret`, `token`, `api_key`, `apikey`, `access_token`
+- `auth`, `credentials`, `mysql_pwd`
+- `stripeToken`, `card`, `cardnumber`
+- `ccv`, `cvc`, `cvv`
+- `ssn`, `pin`
+
+**Matching:**
+- Case-insensitive
+- Substring match (e.g., `password` matches `user_password`, `PASSWORD`, `passwordField`)
+- Works recursively in nested objects
+
+---
+
+### SECURENOW_CAPTURE_MULTIPART
+
+**Description:** Enable capture of `multipart/form-data` request bodies (file upload metadata and text fields). Uses a streaming parser that processes boundary markers on the fly — file binary content is never buffered or stored.
+
+**Format:** `1` (enabled) or `0` (disabled)
+
+**Default:** `0` (disabled)
+
+**Example:**
+```bash
+export SECURENOW_CAPTURE_MULTIPART=1
+```
+
+**What gets captured:**
+- **Text fields** — field name and value (up to 1000 characters), with sensitive fields auto-redacted
+- **File fields** — metadata only: field name, filename, content-type, and size in bytes (no binary content)
+
+**Example span attribute (`http.request.body`):**
+```json
+{
+  "fields": { "description": "My upload", "token": "[REDACTED]" },
+  "files": [
+    { "field": "avatar", "filename": "photo.jpg", "contentType": "image/jpeg", "size": 524288 },
+    { "field": "document", "filename": "report.pdf", "contentType": "application/pdf", "size": 1048576 }
+  ]
+}
+```
+
+**Additional span attributes set:**
+- `http.request.body.type` = `"multipart"`
+- `http.request.body.size` — total raw request body size in bytes
+- `http.request.body.fields_count` — number of text fields
+- `http.request.body.files_count` — number of file fields
+
+**Memory:** Bounded at ~few KB regardless of upload size (streaming parser discards file content as it passes through).
+
+**Parts limit:** 100 parts maximum per request (safety guard).
+
+**Requires:** `SECURENOW_CAPTURE_BODY=1` must also be set (multipart capture is gated behind general body capture).
+
+**Since:** v5.8.0
+
+---
+
+## Instrumentation Control
+
+### SECURENOW_DISABLE_INSTRUMENTATIONS
+
+**Description:** Disable specific OpenTelemetry instrumentations.
+
+**Format:** Comma-separated list of package names
+
+**Example:**
+```bash
+# Disable file system and DNS instrumentations
+export SECURENOW_DISABLE_INSTRUMENTATIONS=fs,dns
+
+# Disable multiple
+export SECURENOW_DISABLE_INSTRUMENTATIONS=fs,dns,net,http2
+```
+
+**Common packages you might disable:**
+- `fs` - File system operations
+- `dns` - DNS lookups
+- `net` - Network operations
+- `http2` - HTTP/2 client/server
+- `grpc` - gRPC client/server
+
+**Use case:**
+- Reduce overhead by disabling unused instrumentations
+- Avoid noisy traces from certain operations
+- Debug issues with specific instrumentations
+
+---
+
+## Debugging
+
+### OTEL_LOG_LEVEL
+
+**Description:** OpenTelemetry SDK internal log level.
+
+**Format:** `none`, `error`, `warn`, `info`, `debug`
+
+**Default:** `none`
+
+**Examples:**
+```bash
+# See all debug information
+export OTEL_LOG_LEVEL=debug
+
+# Only errors
+export OTEL_LOG_LEVEL=error
+
+# No SDK logs
+export OTEL_LOG_LEVEL=none
+```
+
+**Use case:**
+- Troubleshooting setup issues
+- Understanding trace/log export behavior
+- Debugging connection problems
+
+**Output:**
+- Goes to console (stderr)
+- Prefixed with `[securenow]`
+
+---
+
+### SECURENOW_TEST_SPAN
+
+**Description:** Emit a test span on startup to verify tracing is working.
+
+**Format:** `1` (enabled) or `0` (disabled)
+
+**Default:** `0`
+
+**Example:**
+```bash
+export SECURENOW_TEST_SPAN=1
+```
+
+**Behavior:**
+- Creates a span named `securenow.startup.smoke`
+- Span is immediately ended
+- Useful for testing collector connectivity
+
+---
+
+## Environment
+
+### NODE_ENV
+
+**Description:** Standard Node.js environment variable. Sent as `deployment.environment` attribute.
+
+**Format:** String (typically: `development`, `production`, `test`, `staging`)
+
+**Default:** `production`
+
+**Examples:**
+```bash
+export NODE_ENV=development
+export NODE_ENV=production
+export NODE_ENV=staging
+export NODE_ENV=test
+```
+
+**Use case:**
+- Filter traces/logs by environment
+- Different configurations per environment
+- Standard Node.js convention
+
+---
+
+## Firewall (IP Blocking)
+
+### SECURENOW_API_KEY
+
+**Description:** API key for the SecureNow firewall. When set, the firewall auto-activates and syncs your blocklist. Must have the `firewall:read` scope.
+
+**Format:** String (`snk_live_` prefix + 64 hex characters)
+
+**Example:**
+```bash
+export SECURENOW_API_KEY=snk_live_a1b2c3d4e5f6...
+```
+
+---
+
+### SECURENOW_API_URL
+
+**Description:** Base URL for the SecureNow API.
+
+**Format:** URL
+
+**Default:** `https://api.securenow.ai`
+
+**Example:**
+```bash
+export SECURENOW_API_URL=https://api.securenow.ai
+```
+
+---
+
+### SECURENOW_FIREWALL_ENABLED
+
+**Description:** Master kill-switch for the firewall. Set to `0` to disable even when `SECURENOW_API_KEY` is set.
+
+**Format:** `1` (enabled) or `0` (disabled)
+
+**Default:** `1`
+
+---
+
+### SECURENOW_FIREWALL_SYNC_INTERVAL
+
+**Description:** How often (in seconds) to refresh the blocklist from the API.
+
+**Format:** Number (seconds)
+
+**Default:** `60`
+
+**Example:**
+```bash
+export SECURENOW_FIREWALL_SYNC_INTERVAL=30
+```
+
+---
+
+### SECURENOW_FIREWALL_FAIL_MODE
+
+**Description:** Behavior when the blocklist cannot be fetched from the API.
+
+**Format:** `open` or `closed`
+
+**Default:** `open`
+
+- `open` — Allow all traffic when list is unavailable (recommended for most apps)
+- `closed` — Block all traffic when list is unavailable (high-security environments)
+
+---
+
+### SECURENOW_FIREWALL_STATUS_CODE
+
+**Description:** HTTP status code returned to blocked requests (Layer 1 only).
+
+**Format:** Number
+
+**Default:** `403`
+
+**Example:**
+```bash
+export SECURENOW_FIREWALL_STATUS_CODE=429
+```
+
+---
+
+### SECURENOW_FIREWALL_LOG
+
+**Description:** Log blocked requests to the console.
+
+**Format:** `1` (enabled) or `0` (disabled)
+
+**Default:** `1`
+
+---
+
+### SECURENOW_FIREWALL_TCP
+
+**Description:** Enable Layer 2 TCP-level blocking. Destroys sockets from blocked IPs before HTTP parsing starts.
+
+**Format:** `1` (enabled) or `0` (disabled)
+
+**Default:** `0`
+
+**Notes:**
+- Only sees direct connection IP (no proxy headers)
+- Connections from trusted proxies are passed to Layer 1
+- Most effective for direct-to-server deployments
+
+---
+
+### SECURENOW_FIREWALL_IPTABLES
+
+**Description:** Enable Layer 3 OS firewall blocking via iptables/nftables. Kernel-level DROP — packets never reach Node.js.
+
+**Format:** `1` (enabled) or `0` (disabled)
+
+**Default:** `0`
+
+**Notes:**
+- Linux only (skips gracefully on macOS/Windows)
+- Requires root or CAP_NET_ADMIN
+- Auto-detects nftables vs iptables
+- Dedicated chain: `SECURENOW_BLOCK`
+
+---
+
+### SECURENOW_FIREWALL_CLOUD
+
+**Description:** Enable Layer 4 cloud/edge WAF blocking. Pushes the blocklist to your cloud provider's WAF.
+
+**Format:** `cloudflare`, `aws`, or `gcp`
+
+**Default:** *(none — disabled)*
+
+**Provider-specific variables:**
+
+| Provider | Required Variables |
+|----------|-------------------|
+| `cloudflare` | `CLOUDFLARE_API_TOKEN`, `CLOUDFLARE_ACCOUNT_ID` |
+| `aws` | `AWS_WAF_IP_SET_ID`, standard AWS credentials |
+| `gcp` | `GCP_PROJECT_ID`, `GCP_SECURITY_POLICY` |
+
+---
+
+### SECURENOW_FIREWALL_CLOUD_DRY_RUN
+
+**Description:** Log cloud WAF pushes without actually applying them. Useful for testing.
+
+**Format:** `1` (enabled) or `0` (disabled)
+
+**Default:** `0`
+
+---
+
+### SECURENOW_TRUSTED_PROXIES
+
+**Description:** Comma-separated list of additional trusted proxy IPs. The firewall only reads `X-Forwarded-For` from trusted proxies. Private/loopback IPs are always trusted.
+
+**Format:** Comma-separated IPs
+
+**Example:**
+```bash
+export SECURENOW_TRUSTED_PROXIES=34.120.0.1,34.120.0.2
+```
+
+---
+
+## Configuration Examples
+
+### Development Environment
+
+```bash
+# .env.development
+SECURENOW_APPID=my-app-dev
+SECURENOW_INSTANCE=http://localhost:4318
+SECURENOW_LOGGING_ENABLED=1
+SECURENOW_CAPTURE_BODY=1
+SECURENOW_MAX_BODY_SIZE=20480
+OTEL_LOG_LEVEL=debug
+SECURENOW_TEST_SPAN=1
+NODE_ENV=development
+```
+
+### Production Environment
+
+```bash
+# .env.production
+SECURENOW_APPID=my-app-prod
+SECURENOW_INSTANCE=https://collector.prod.example.com:4318
+OTEL_EXPORTER_OTLP_HEADERS=x-api-key=prod-key-12345
+SECURENOW_LOGGING_ENABLED=1
+SECURENOW_CAPTURE_BODY=0
+SECURENOW_NO_UUID=1
+SECURENOW_STRICT=1
+SECURENOW_SENSITIVE_FIELDS=internal_id,session_token
+OTEL_LOG_LEVEL=error
+NODE_ENV=production
+
+# Firewall (optional — auto-activates when API key is set)
+SECURENOW_API_KEY=snk_live_abc123...
+SECURENOW_FIREWALL_TCP=1
+SECURENOW_FIREWALL_SYNC_INTERVAL=30
+```
+
+### PM2 Cluster
+
+```bash
+# ecosystem.config.js environment
+SECURENOW_APPID=my-app
+SECURENOW_INSTANCE=http://localhost:4318
+SECURENOW_LOGGING_ENABLED=1
+SECURENOW_NO_UUID=1
+SECURENOW_STRICT=1
+SECURENOW_CAPTURE_BODY=1
+NODE_ENV=production
+```
+
+### Docker / Kubernetes
+
+```bash
+# Docker environment or K8s ConfigMap
+SECURENOW_APPID=my-service
+SECURENOW_INSTANCE=http://otel-collector:4318
+SECURENOW_LOGGING_ENABLED=1
+SECURENOW_NO_UUID=1
+SECURENOW_CAPTURE_BODY=0
+NODE_ENV=production
+```
+
+### Separate Collectors for Traces and Logs
+
+```bash
+# Different backends for traces and logs
+SECURENOW_APPID=my-app
+OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://traces-collector:4318/v1/traces
+OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://logs-collector:4318/v1/logs
+SECURENOW_LOGGING_ENABLED=1
+```
+
+---
+
+## Priority and Overrides
+
+When multiple variables are set, this is the priority order:
+
+### Service Name
+
+1. `OTEL_SERVICE_NAME` (highest priority)
+2. `SECURENOW_APPID`
+3. Auto-generated fallback (lowest priority)
+
+### OTLP Endpoint
+
+1. `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` (for traces)
+2. `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` (for logs)
+3. `OTEL_EXPORTER_OTLP_ENDPOINT`
+4. `SECURENOW_INSTANCE`
+5. Default: `https://freetrial.securenow.ai:4318` (lowest priority)
+
+---
+
+## Validation
+
+SecureNow validates environment variables on startup. Check console output:
+
+```bash
+[securenow] pid=12345 SECURENOW_APPID="my-app" OTEL_SERVICE_NAME=null → service.name=my-app-uuid123
+[securenow] OTel SDK started → http://localhost:4318/v1/traces
+[securenow] 📋 Logging: ENABLED → http://localhost:4318/v1/logs
+[securenow] 📝 Request body capture: ENABLED (max: 10240 bytes)
+```
+
+---
+
+## Best Practices
+
+### 1. Use .env Files
+
+Don't hardcode in your application:
+
+```bash
+# .env
+SECURENOW_APPID=my-app
+SECURENOW_INSTANCE=http://localhost:4318
+```
+
+### 2. Different Configs per Environment
+
+```bash
+# .env.development
+SECURENOW_CAPTURE_BODY=1
+OTEL_LOG_LEVEL=debug
+
+# .env.production
+SECURENOW_CAPTURE_BODY=0
+OTEL_LOG_LEVEL=error
+```
+
+### 3. Use SECURENOW_NO_UUID in Clusters
+
+```bash
+# PM2 cluster with 4 workers
+SECURENOW_NO_UUID=1
+```
+
+### 4. Enable SECURENOW_STRICT in Production
+
+```bash
+# Fail fast if misconfigured
+SECURENOW_STRICT=1
+```
+
+### 5. Disable Body Capture in Production
+
+```bash
+# Development
+SECURENOW_CAPTURE_BODY=1
+
+# Production
+SECURENOW_CAPTURE_BODY=0
+```
+
+---
+
+## Troubleshooting
+
+### Check Current Values
+
+```bash
+# Print all SECURENOW variables
+env | grep SECURENOW
+
+# Print all OTEL variables
+env | grep OTEL
+
+# Check specific variable
+echo $SECURENOW_APPID
+```
+
+### Verify in Application
+
+SecureNow logs current configuration on startup. Look for lines like:
+
+```
+[securenow] pid=12345 SECURENOW_APPID="my-app" → service.name=my-app
+[securenow] OTel SDK started → http://localhost:4318/v1/traces
+```
+
+### Enable Debug Mode
+
+```bash
+export OTEL_LOG_LEVEL=debug
+node app.js
+```
+
+---
+
+## Related Documentation
+
+- [Firewall Guide](./FIREWALL-GUIDE.md)
+- [API Keys Guide](./API-KEYS-GUIDE.md)
+- [Express Setup Guide](./EXPRESS-SETUP-GUIDE.md)
+- [Next.js Setup Guide](./NEXTJS-SETUP-COMPLETE.md)
+- [Logging Guide](./LOGGING-GUIDE.md)
+- [NPM README](../NPM_README.md)
+
+---
+
+**Complete reference for all SecureNow environment variables.** 🎯