securenow 5.0.0 → 5.0.2

package/docs/ENVIRONMENT-VARIABLES.md

@@ -0,0 +1,652 @@
+# 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 | `http://46.62.173.237: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_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:** `http://46.62.173.237: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:**
+- `multipart/form-data` (file uploads)
+- 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
+
+---
+
+## 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: `http://46.62.173.237: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.** 🎯