securenow 5.6.0 → 5.7.0

package/docs/LOGGING-QUICKSTART.md

@@ -1,239 +1,234 @@
-# SecureNow Logging - Quick Start
-
-Get logging set up in your Node.js app in under 2 minutes!
-
----
-
-## 1. Install
-
-```bash
-npm install securenow
-```
-
----
-
-## 2. Configure Environment
-
-Create `.env` file or export variables:
-
-```bash
-SECURENOW_LOGGING_ENABLED=1
-SECURENOW_APPID=my-app
-SECURENOW_INSTANCE=http://your-otlp-backend:4318
-
-# For SecureNow / hosted OTLP (example):
-# SECURENOW_INSTANCE=https://freetrial.securenow.ai:4318
-# OTEL_EXPORTER_OTLP_HEADERS="x-api-key=<your-key>"
-```
-
----
-
-## 3. Add to Your App
-
-**Option A: Automatic Console Logging (Easiest)**
-
-Add these two lines at the top of your main file:
-
-```javascript
-// app.js, index.js, server.js, or main.ts
-require('securenow/register');
-require('securenow/console-instrumentation');
-
-// That's it! Now use console normally
-console.log('App started');
-console.error('An error occurred', { userId: 123 });
-```
-
-**Option B: Use NODE_OPTIONS (No code changes)**
-
-```bash
-NODE_OPTIONS="-r securenow/register -r securenow/console-instrumentation" node app.js
-```
-
----
-
-## 4. Run Your App
-
-```bash
-node app.js
-# or
-npm start
-```
-
-You should see:
-
-```
-[securenow] OTel SDK started → http://your-otlp-backend:4318/v1/traces
-[securenow] 📋 Logging: ENABLED → http://your-otlp-backend:4318/v1/logs
-[securenow] Console instrumentation installed
-```
-
----
-
-## 5. View Logs in SecureNow
-
-1. Open your SecureNow dashboard
-2. Go to **Logs** section
-3. Filter by `service.name = my-app`
-4. See all your logs with automatic trace correlation!
-
----
-
-## Framework-Specific Examples
-
-### 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);
-```
-
-### Next.js
-
-```typescript
-// instrumentation.ts (in project root)
-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');
-  }
-}
-```
-
-```bash
-# .env.local
-SECURENOW_LOGGING_ENABLED=1
-SECURENOW_APPID=my-nextjs-app
-SECURENOW_INSTANCE=http://localhost:4318
-```
-
-### 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 });
-```
-
-### NestJS
-
-```typescript
-// 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);
-  console.log('App starting');
-  await app.listen(3000);
-}
-
-bootstrap();
-```
-
----
-
-## Troubleshooting
-
-**Logs not appearing?**
-
-1. Check `SECURENOW_LOGGING_ENABLED=1` is set
-2. Verify your OTLP / SecureNow endpoint is correct
-3. Enable debug: `OTEL_LOG_LEVEL=debug`
-
-**Console instrumentation not working?**
-
-Make sure require order is correct:
-
-```javascript
-// ✅ Correct
-require('securenow/register');           // First
-require('securenow/console-instrumentation');  // Second
-
-// ❌ Wrong
-require('express');
-require('securenow/register');  // Too late!
-```
-
----
-
-## What Gets Logged?
-
-All standard console methods:
-
-- `console.log()` → INFO
-- `console.info()` → INFO
-- `console.warn()` → WARN
-- `console.error()` → ERROR
-- `console.debug()` → DEBUG
-
-**Structured logging example:**
-
-```javascript
-console.log('User logged in', {
-  userId: 123,
-  email: 'user@example.com',
-  ip: '192.168.1.1'
-});
-```
-
-This creates a log with attributes you can filter/search in SecureNow!
-
----
-
-## Advanced Usage
-
-**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: {
-    customField: 'value',
-  },
-});
-```
-
----
-
-## Next Steps
-
-- [Complete Logging Guide](./LOGGING-GUIDE.md) - All features and options
-- [SecureNow](https://securenow.ai/)
-- [Documentation](./INDEX.md)
-- [Combine with Tracing](../README.md) - Full observability
-
----
-
-**That's it!** 🎉 Your app is now sending logs to SecureNow.
-
-Need help? Check the [full documentation](./LOGGING-GUIDE.md) or open an issue.
+# SecureNow Logging - Quick Start
+
+Get logging set up in your Node.js app in under 2 minutes!
+
+**Since v5.6.0:** When `SECURENOW_LOGGING_ENABLED=1` is set, all `console.log` / `warn` / `error` / `info` / `debug` calls are automatically forwarded as OTLP log records. You only need `require('securenow/register')`—a separate `console-instrumentation` preload is no longer required.
+
+---
+
+## 1. Install
+
+```bash
+npm install securenow
+```
+
+---
+
+## 2. Configure Environment
+
+Create `.env` file or export variables:
+
+```bash
+SECURENOW_LOGGING_ENABLED=1
+SECURENOW_APPID=my-app
+SECURENOW_INSTANCE=http://your-otlp-backend:4318
+
+# For SecureNow / hosted OTLP (example):
+# SECURENOW_INSTANCE=https://freetrial.securenow.ai:4318
+# OTEL_EXPORTER_OTLP_HEADERS="x-api-key=<your-key>"
+```
+
+---
+
+## 3. Add to Your App
+
+**Option A: Automatic Console Logging (Easiest)**
+
+Add this line at the top of your main file:
+
+```javascript
+// app.js, index.js, server.js, or main.ts
+require('securenow/register');
+
+// That's it! Now use console normally
+console.log('App started');
+console.error('An error occurred', { userId: 123 });
+```
+
+**Option B: Use NODE_OPTIONS (No code changes)**
+
+```bash
+NODE_OPTIONS="-r securenow/register" node app.js
+```
+
+---
+
+## 4. Run Your App
+
+```bash
+node app.js
+# or
+npm start
+```
+
+You should see:
+
+```
+[securenow] OTel SDK started → http://your-otlp-backend:4318/v1/traces
+[securenow] 📋 Logging: ENABLED → http://your-otlp-backend:4318/v1/logs
+```
+
+---
+
+## 5. View Logs in SecureNow
+
+1. Open your SecureNow dashboard
+2. Go to **Logs** section
+3. Filter by `service.name = my-app`
+4. See all your logs with automatic trace correlation!
+
+---
+
+## Framework-Specific Examples
+
+### Express.js
+
+```javascript
+// app.js
+require('securenow/register');
+
+const express = require('express');
+const app = express();
+
+app.get('/', (req, res) => {
+  console.log('Request received');
+  res.send('Hello World');
+});
+
+app.listen(3000);
+```
+
+### Next.js
+
+```typescript
+// instrumentation.ts (in project root)
+export async function register() {
+  if (process.env.NEXT_RUNTIME === 'nodejs') {
+    process.env.SECURENOW_LOGGING_ENABLED = '1';
+    await import('securenow/register');
+  }
+}
+```
+
+```bash
+# .env.local
+SECURENOW_LOGGING_ENABLED=1
+SECURENOW_APPID=my-nextjs-app
+SECURENOW_INSTANCE=http://localhost:4318
+```
+
+### Fastify
+
+```javascript
+// server.js
+require('securenow/register');
+
+const fastify = require('fastify')();
+
+fastify.get('/', async () => {
+  console.log('Route 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('App starting');
+  await app.listen(3000);
+}
+
+bootstrap();
+```
+
+---
+
+## Troubleshooting
+
+**Logs not appearing?**
+
+1. Check `SECURENOW_LOGGING_ENABLED=1` is set
+2. Verify your OTLP / SecureNow endpoint is correct
+3. Enable debug: `OTEL_LOG_LEVEL=debug`
+
+**Console logs not forwarding?**
+
+Load `securenow/register` before other app code so logging hooks run first:
+
+```javascript
+// ✅ Correct
+require('securenow/register');  // First
+
+// ❌ Wrong
+require('express');
+require('securenow/register');  // Too late!
+```
+
+---
+
+## What Gets Logged?
+
+All standard console methods:
+
+- `console.log()` → INFO
+- `console.info()` → INFO
+- `console.warn()` → WARN
+- `console.error()` → ERROR
+- `console.debug()` → DEBUG
+
+**Structured logging example:**
+
+```javascript
+console.log('User logged in', {
+  userId: 123,
+  email: 'user@example.com',
+  ip: '192.168.1.1'
+});
+```
+
+This creates a log with attributes you can filter/search in SecureNow!
+
+---
+
+## Advanced Usage
+
+**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: {
+    customField: 'value',
+  },
+});
+```
+
+---
+
+## Next Steps
+
+- [Complete Logging Guide](./LOGGING-GUIDE.md) - All features and options
+- [SecureNow](https://securenow.ai/)
+- [Documentation](./INDEX.md)
+- [Combine with Tracing](../README.md) - Full observability
+
+---
+
+**That's it!** 🎉 Your app is now sending logs to SecureNow.
+
+Need help? Check the [full documentation](./LOGGING-GUIDE.md) or open an issue.

package/docs/NUXT-GUIDE.md

@@ -0,0 +1,166 @@
+# SecureNow — Nuxt 3 Setup Guide
+
+## Quick Start (1 minute)
+
+### 1. Install
+
+```bash
+npm install securenow
+```
+
+### 2. Add the module to `nuxt.config.ts`
+
+```ts
+export default defineNuxtConfig({
+  modules: ['securenow/nuxt'],
+});
+```
+
+### 3. Set environment variables
+
+Create a `.env` file in your project root:
+
+```env
+SECURENOW_APPID=my-nuxt-app
+SECURENOW_INSTANCE=https://freetrial.securenow.ai:4318
+```
+
+### 4. Start your app
+
+```bash
+nuxt dev
+```
+
+You should see in the console:
+
+```
+[securenow] Nuxt module loaded — server plugin registered
+[securenow] 🚀 Nuxt OTel SDK started → https://freetrial.securenow.ai:4318/v1/traces
+[securenow] service.name=my-nuxt-app instance.id=my-nuxt-app-...
+```
+
+That's it — all server-side requests are now traced.
+
+---
+
+## Configuration
+
+### Module options in `nuxt.config.ts`
+
+```ts
+export default defineNuxtConfig({
+  modules: ['securenow/nuxt'],
+  securenow: {
+    serviceName: 'my-nuxt-app',     // overrides SECURENOW_APPID
+    endpoint: 'http://host:4318',   // overrides SECURENOW_INSTANCE
+    noUuid: true,                   // single service.name (no UUID suffix)
+    captureBody: true,              // capture POST/PUT/PATCH bodies
+    logging: true,                  // forward console.* as OTLP logs
+  },
+});
+```
+
+### Environment variables
+
+All standard SecureNow env vars are supported:
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `SECURENOW_APPID` | Service name | `nuxt-app-<uuid>` |
+| `SECURENOW_INSTANCE` | OTLP base URL | `https://freetrial.securenow.ai:4318` |
+| `SECURENOW_NO_UUID` | Don't append UUID to service name | `false` |
+| `SECURENOW_LOGGING_ENABLED` | Forward console logs as OTLP | `false` |
+| `SECURENOW_CAPTURE_BODY` | Capture request bodies | `false` |
+| `SECURENOW_MAX_BODY_SIZE` | Max body size to capture (bytes) | `10240` |
+| `SECURENOW_SENSITIVE_FIELDS` | Extra fields to redact (CSV) | _(built-in list)_ |
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | Alternative OTLP base URL | — |
+| `OTEL_EXPORTER_OTLP_HEADERS` | OTLP headers (k=v,k2=v2) | — |
+
+---
+
+## What gets traced
+
+### Automatic (out of the box)
+
+- All Nitro server handler requests (API routes, SSR pages, middleware)
+- HTTP method, path, status code, duration
+- Client IP address (with proxy-aware resolution)
+- User-Agent, Referer, Origin, Host
+- Security header presence (auth, cookies, CSRF)
+- Request IDs and correlation headers
+
+### With `captureBody: true`
+
+- POST/PUT/PATCH request bodies (JSON, form-urlencoded, GraphQL)
+- Sensitive fields auto-redacted (passwords, tokens, etc.)
+- Bodies larger than `SECURENOW_MAX_BODY_SIZE` are skipped
+
+### With `logging: true`
+
+- All `console.log/info/warn/error/debug` calls forwarded as OTLP log records
+- Logs correlated with active trace spans
+
+---
+
+## Comparison with Next.js integration
+
+| Feature | Nuxt (`securenow/nuxt`) | Next.js (`securenow/nextjs`) |
+|---------|-------------------------|------------------------------|
+| Setup | Add to `modules` array | Create `instrumentation.ts` |
+| Config | `nuxt.config.ts` | `.env.local` + `next.config.js` |
+| Server tracing | Nitro hooks | HTTP instrumentation |
+| Edge runtime | Not supported | Skipped gracefully |
+| Vercel support | Via env vars | `@vercel/otel` integration |
+| Body capture | HTTP instrumentation | Middleware + `Request.clone()` |
+| Logging | Console patching | Console patching |
+
+---
+
+## Deployment
+
+### Node.js server (PM2, Docker, etc.)
+
+Works out of the box with `nuxt build && node .output/server/index.mjs`.
+
+### Vercel / Netlify / Cloudflare
+
+Set env vars in the platform dashboard:
+
+```
+SECURENOW_APPID=my-nuxt-app
+SECURENOW_INSTANCE=https://your-otlp-backend:4318
+```
+
+> Note: On edge runtimes (Cloudflare Workers, Vercel Edge), some Node.js-specific
+> instrumentations may not be available. Server-handler tracing via Nitro hooks
+> still works.
+
+---
+
+## Troubleshooting
+
+### No traces appearing
+
+1. Check that `SECURENOW_APPID` and `SECURENOW_INSTANCE` are set
+2. Look for `[securenow] 🚀 Nuxt OTel SDK started` in the console
+3. Verify the OTLP endpoint is reachable from your server
+
+### Module not loading
+
+Make sure you're using Nuxt 3 (`nuxt: ">=3.0.0"`) and the module is listed
+in the `modules` array (not `buildModules`).
+
+### OpenTelemetry packages bundled by Nitro
+
+The module automatically externalizes OTel packages. If you see bundling errors,
+manually add to `nuxt.config.ts`:
+
+```ts
+export default defineNuxtConfig({
+  nitro: {
+    externals: {
+      external: ['securenow', '@opentelemetry/api', '@opentelemetry/sdk-node'],
+    },
+  },
+});
+```