securenow 7.6.7 → 7.6.9

package/CONSUMING-APPS-GUIDE.md

@@ -1,463 +0,0 @@
-# How to Use SecureNow Logging in Your App
-
-**Current setup model:** Logging, body capture, multipart capture, and firewall setup are driven by `.securenow/credentials.json` written by `npx securenow login` and completed by `npx securenow init`. For production, generate a tokenless file with `npx securenow credentials runtime --env production` and mount/copy it as `.securenow/credentials.json`. Older env-var snippets in this guide are legacy fallbacks only.
-
-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 v7.0.0:** Logging, body capture, and multipart capture are **on by default**. Credentials come from `.securenow/credentials.json` written by `npx securenow login` — no env vars required for local dev. Set `SECURENOW_LOGGING_ENABLED=0` to disable logging if you don't want it.
-
----
-
-## Installation
-
-```bash
-npm install securenow
-npx securenow login   # pick/create your app in the browser
-```
-
-That's it for local dev. The `login` step writes `.securenow/credentials.json` (gitignored automatically) and the SDK reads it at boot.
-
-For CI / Docker / production where you can't run the browser flow, set env vars — see "Step 1 (alternative)" below.
-
----
-
-## Setup Steps
-
-### Step 1 (alternative) — Environment variables for CI / Docker / prod
-
-If `npx securenow login` isn't an option on the target machine, set:
-
-```bash
-# App routing key (UUID) — from `npx securenow apps`
-SECURENOW_APPID=your-app-key-uuid
-
-# OTLP collector (defaults to https://freetrial.securenow.ai:4318)
-SECURENOW_INSTANCE=https://freetrial.securenow.ai:4318
-
-# Optional — defaults are already on:
-# SECURENOW_LOGGING_ENABLED=0      # to disable console-log forwarding
-# SECURENOW_CAPTURE_BODY=0         # to disable body capture (required for Fastify/Hapi/Hono)
-# OTEL_EXPORTER_OTLP_HEADERS="x-api-key=your-key"
-```
-
-Env vars always take precedence over the credentials file.
-
----
-
-### 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). 🎉