securenow 7.6.6 → 7.6.8

package/docs/LOGGING-GUIDE.md

@@ -1,704 +0,0 @@
-# SecureNow Logging Guide
-
-Complete guide for sending logs from your Node.js applications to SecureNow using the SecureNow library.
-
-**Since securenow v5.6.0:** When `SECURENOW_LOGGING_ENABLED=1` is set, all `console.log`, `console.warn`, `console.error`, `console.info`, and `console.debug` calls are automatically forwarded as OTLP log records. You only need `require('securenow/register')` — a separate `securenow/console-instrumentation` preload is no longer required.
-
-## Table of Contents
-
-- [Quick Start](#quick-start)
-- [Configuration](#configuration)
-- [Usage Methods](#usage-methods)
-  - [Method 1: Automatic Console Instrumentation](#method-1-automatic-console-instrumentation-easiest)
-  - [Method 2: Direct Logger API](#method-2-direct-logger-api)
-  - [Method 3: Custom Logger Integration](#method-3-custom-logger-integration)
-- [Framework-Specific Examples](#framework-specific-examples)
-  - [Express.js](#expressjs)
-  - [Next.js](#nextjs)
-  - [Fastify](#fastify)
-  - [NestJS](#nestjs)
-- [Advanced Configuration](#advanced-configuration)
-- [Troubleshooting](#troubleshooting)
-
----
-
-## Quick Start
-
-### 1. Install SecureNow
-
-```bash
-npm install securenow
-```
-
-### 2. Enable Logging
-
-Set environment variables:
-
-```bash
-# Required: Enable logging
-export SECURENOW_LOGGING_ENABLED=1
-
-# Required: Your app identifier
-export SECURENOW_APPID=my-app
-
-# Optional: Your OTLP endpoint (defaults to https://freetrial.securenow.ai:4318)
-export SECURENOW_INSTANCE=http://your-otlp-backend:4318
-
-# Optional: Authentication for hosted OTLP / SecureNow
-export OTEL_EXPORTER_OTLP_HEADERS="x-api-key=your-key-here"
-```
-
-### 3. Choose Your Usage Method
-
-**Option A: Automatic Console Logging (Easiest)**
-
-```javascript
-// At the top of your main file (app.js, index.js, server.js)
-require('securenow/register');
-
-// With SECURENOW_LOGGING_ENABLED=1, all console logs are automatically sent to SecureNow
-console.log('Application started');
-console.error('An error occurred', { userId: 123 });
-console.warn('Warning message');
-```
-
-**Option B: Direct Logger API**
-
-```javascript
-require('securenow/register');
-const { getLogger } = require('securenow/tracing');
-
-const logger = getLogger('my-module', '1.0.0');
-
-logger.emit({
-  severityNumber: 9,  // INFO
-  severityText: 'INFO',
-  body: 'User logged in',
-  attributes: {
-    userId: 123,
-    username: 'john',
-  },
-});
-```
-
----
-
-## Configuration
-
-### Environment Variables
-
-```bash
-# Logging Control
-SECURENOW_LOGGING_ENABLED=1              # Enable logging (default: 1)
-
-# Connection Settings
-SECURENOW_INSTANCE=http://localhost:4318 # Base OTLP endpoint
-OTEL_EXPORTER_OTLP_ENDPOINT=...          # Alternative to SECURENOW_INSTANCE
-OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=...     # Specific logs endpoint (overrides base)
-
-# Authentication (for hosted OTLP / SecureNow)
-OTEL_EXPORTER_OTLP_HEADERS="x-api-key=YOUR_KEY"
-
-# Service Identification
-SECURENOW_APPID=my-app                   # Your application name
-OTEL_SERVICE_NAME=my-app                 # Alternative to SECURENOW_APPID
-
-# Additional Options
-OTEL_LOG_LEVEL=info                      # debug|info|warn|error
-NODE_ENV=production                      # Environment name
-```
-
-### Hosted OTLP / SecureNow configuration
-
-For SecureNow or another hosted OTLP endpoint:
-
-```bash
-export SECURENOW_LOGGING_ENABLED=1
-export SECURENOW_APPID=my-app
-export SECURENOW_INSTANCE=https://freetrial.securenow.ai:4318
-export OTEL_EXPORTER_OTLP_HEADERS="x-api-key=<your-api-key>"
-```
-
-Replace:
-- `SECURENOW_INSTANCE`: Use the OTLP base URL from your SecureNow dashboard (defaults to the freetrial endpoint above)
-- `<your-api-key>`: Your API key or other credentials as required by your backend
-
----
-
-## Usage Methods
-
-### Method 1: Automatic Console Instrumentation (Easiest)
-
-With `SECURENOW_LOGGING_ENABLED=1`, SecureNow wraps the default `console` methods to automatically send logs to SecureNow while still printing to the console.
-
-**Setup:**
-
-```javascript
-// app.js or index.js
-require('securenow/register');
-
-const express = require('express');
-const app = express();
-
-// Use console as normal - all logs are captured
-console.log('Server starting...');
-
-app.get('/', (req, res) => {
-  console.info('Request received', { path: req.path });
-  res.send('Hello World');
-});
-
-app.listen(3000, () => {
-  console.log('Server running on port 3000');
-});
-```
-
-**Supported Methods:**
-- `console.log()` → INFO level
-- `console.info()` → INFO level
-- `console.warn()` → WARN level
-- `console.error()` → ERROR level
-- `console.debug()` → DEBUG level
-
-**Benefits:**
-- ✅ Zero code changes needed
-- ✅ Works with existing console logging
-- ✅ Automatic severity mapping
-- ✅ Works with all frameworks
-
----
-
-### Method 2: Direct Logger API
-
-Use the OpenTelemetry logger API directly for more control.
-
-```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,      // OpenTelemetry severity number
-  severityText: 'INFO',   // Human-readable severity
-  body: 'User login',     // Log message
-  attributes: {           // Structured attributes
-    userId: 123,
-    username: 'john',
-    ip: '192.168.1.1',
-  },
-});
-```
-
-**Severity Numbers:**
-- `5` - DEBUG
-- `9` - INFO
-- `13` - WARN
-- `17` - ERROR
-
-**Example with Error:**
-
-```javascript
-try {
-  // Some operation
-} catch (error) {
-  logger.emit({
-    severityNumber: 17,
-    severityText: 'ERROR',
-    body: 'Database connection failed',
-    attributes: {
-      error: error.message,
-      stack: error.stack,
-      database: 'postgres',
-    },
-  });
-}
-```
-
----
-
-### Method 3: Custom Logger Integration
-
-Create a wrapper for your preferred logging style.
-
-```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) {
-    console.log(message, attributes);
-    return;
-  }
-  
-  logger.emit({
-    severityNumber: SeverityNumber[level],
-    severityText: level,
-    body: message,
-    attributes,
-  });
-  
-  // Also log to console
-  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 Examples
-
-### Express.js
-
-```javascript
-// app.js
-require('securenow/register');
-
-const express = require('express');
-const app = express();
-
-app.use(express.json());
-
-// Logging middleware
-app.use((req, res, next) => {
-  console.info('Request received', {
-    method: req.method,
-    path: req.path,
-    ip: req.ip,
-  });
-  next();
-});
-
-app.get('/', (req, res) => {
-  console.log('Home page accessed');
-  res.send('Hello World');
-});
-
-app.post('/api/users', (req, res) => {
-  console.info('User created', { userData: req.body });
-  res.json({ success: true });
-});
-
-// Error handler with logging
-app.use((err, req, res, next) => {
-  console.error('Express error', {
-    error: err.message,
-    stack: err.stack,
-    path: req.path,
-  });
-  res.status(500).json({ error: 'Internal server error' });
-});
-
-app.listen(3000, () => {
-  console.log('Express server running on port 3000');
-});
-```
-
-**Run with:**
-
-```bash
-SECURENOW_LOGGING_ENABLED=1 \
-SECURENOW_APPID=express-app \
-NODE_OPTIONS="-r securenow/register" \
-node app.js
-```
-
----
-
-### Next.js
-
-#### App Router (Next.js 13+)
-
-**instrumentation.ts:**
-
-```typescript
-// instrumentation.ts (in root directory)
-export async function register() {
-  if (process.env.NEXT_RUNTIME === 'nodejs') {
-    // Enable tracing and logging
-    process.env.SECURENOW_LOGGING_ENABLED = '1';
-    
-    await import('securenow/register');
-  }
-}
-```
-
-**Environment Variables (.env.local):**
-
-```bash
-SECURENOW_LOGGING_ENABLED=1
-SECURENOW_APPID=nextjs-app
-SECURENOW_INSTANCE=http://your-otlp-backend:4318
-```
-
-**Usage in API Routes:**
-
-```typescript
-// app/api/users/route.ts
-import { NextRequest, NextResponse } from 'next/server';
-
-export async function GET(request: NextRequest) {
-  console.log('GET /api/users called');
-  
-  const users = await fetchUsers();
-  console.info('Users fetched', { count: users.length });
-  
-  return NextResponse.json(users);
-}
-
-export async function POST(request: NextRequest) {
-  const data = await request.json();
-  console.info('Creating user', { email: data.email });
-  
-  try {
-    const user = await createUser(data);
-    console.log('User created successfully', { userId: user.id });
-    return NextResponse.json(user);
-  } catch (error) {
-    console.error('Failed to create user', { error: error.message });
-    return NextResponse.json({ error: 'Failed' }, { status: 500 });
-  }
-}
-```
-
-**Usage in Server Components:**
-
-```typescript
-// app/dashboard/page.tsx
-export default async function DashboardPage() {
-  console.log('Dashboard page rendering');
-  
-  const data = await fetchDashboardData();
-  console.info('Dashboard data loaded', { items: data.length });
-  
-  return <div>{/* your component */}</div>;
-}
-```
-
----
-
-### Fastify
-
-```javascript
-// server.js
-require('securenow/register');
-
-const fastify = require('fastify')({ logger: false });
-
-// Logging hook
-fastify.addHook('onRequest', async (request, reply) => {
-  console.info('Request received', {
-    method: request.method,
-    url: request.url,
-  });
-});
-
-fastify.get('/', async (request, reply) => {
-  console.log('Root endpoint called');
-  return { hello: 'world' };
-});
-
-fastify.post('/users', async (request, reply) => {
-  console.info('Creating user', { body: request.body });
-  return { success: true };
-});
-
-// Error handler
-fastify.setErrorHandler((error, request, reply) => {
-  console.error('Fastify error', {
-    error: error.message,
-    stack: error.stack,
-    url: request.url,
-  });
-  reply.status(500).send({ error: 'Internal server error' });
-});
-
-const start = async () => {
-  try {
-    await fastify.listen({ port: 3000 });
-    console.log('Fastify server running on port 3000');
-  } catch (err) {
-    console.error('Server start failed', { error: err });
-    process.exit(1);
-  }
-};
-
-start();
-```
-
----
-
-### NestJS
-
-**main.ts:**
-
-```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);
-  console.log('NestJS application running on port 3000');
-}
-
-bootstrap();
-```
-
-**Service with logging:**
-
-```typescript
-// users.service.ts
-import { Injectable } from '@nestjs/common';
-
-@Injectable()
-export class UsersService {
-  async findAll() {
-    console.log('Fetching all users');
-    const users = await this.fetchFromDatabase();
-    console.info('Users retrieved', { count: users.length });
-    return users;
-  }
-  
-  async create(userData: any) {
-    console.info('Creating user', { email: userData.email });
-    
-    try {
-      const user = await this.saveToDatabase(userData);
-      console.log('User created', { userId: user.id });
-      return user;
-    } catch (error) {
-      console.error('Failed to create user', {
-        error: error.message,
-        email: userData.email,
-      });
-      throw error;
-    }
-  }
-}
-```
-
-**Run with environment variables:**
-
-```bash
-SECURENOW_LOGGING_ENABLED=1 \
-SECURENOW_APPID=nestjs-app \
-npm run start
-```
-
----
-
-## Advanced Configuration
-
-### Disable Logging Temporarily
-
-```bash
-SECURENOW_LOGGING_ENABLED=0 node app.js
-```
-
-### Custom Logs Endpoint
-
-```bash
-export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://custom-collector:4318/v1/logs
-```
-
-### Check if Logging is Enabled
-
-```javascript
-const { isLoggingEnabled } = require('securenow/tracing');
-
-if (isLoggingEnabled()) {
-  console.log('Logging is enabled');
-}
-```
-
-### Multiple Logger Instances
-
-```javascript
-const { getLogger } = require('securenow/tracing');
-
-const authLogger = getLogger('auth-service', '1.0.0');
-const dbLogger = getLogger('database', '2.0.0');
-const apiLogger = getLogger('api', '1.0.0');
-
-authLogger.emit({
-  severityNumber: 9,
-  severityText: 'INFO',
-  body: 'User logged in',
-  attributes: { userId: 123 },
-});
-
-dbLogger.emit({
-  severityNumber: 13,
-  severityText: 'WARN',
-  body: 'Slow query detected',
-  attributes: { queryTime: 5000, query: 'SELECT ...' },
-});
-```
-
----
-
-## Troubleshooting
-
-### Logs not appearing in SecureNow
-
-**Check 1: Is logging enabled?**
-
-```bash
-SECURENOW_LOGGING_ENABLED=1
-```
-
-**Check 2: Verify endpoint**
-
-```bash
-# For self-hosted OTLP collector
-export SECURENOW_INSTANCE=http://your-otlp-backend:4318
-
-# For SecureNow / hosted OTLP
-export SECURENOW_INSTANCE=https://freetrial.securenow.ai:4318
-export OTEL_EXPORTER_OTLP_HEADERS="x-api-key=<your-key>"
-```
-
-**Check 3: Enable debug logging**
-
-```bash
-export OTEL_LOG_LEVEL=debug
-node app.js
-```
-
-Look for messages like:
-```
-[securenow] 📋 Logging: ENABLED → http://localhost:4318/v1/logs
-```
-
-**Check 4: Verify initialization order**
-
-Make sure `securenow/register` is required BEFORE any other code:
-
-```javascript
-// ✅ Correct
-require('securenow/register');
-const express = require('express');
-
-// ❌ Wrong
-const express = require('express');
-require('securenow/register');
-```
-
-### Console logs not forwarded
-
-**Check load order:** `require('securenow/register')` must run before your app code so console forwarding can be installed.
-
-```javascript
-require('securenow/register');
-// ... rest of your app
-```
-
-**Verify in output:**
-
-You should see messages indicating logging is enabled, for example:
-```
-[securenow] 📋 Logging: ENABLED → http://localhost:4318/v1/logs
-```
-
-### Logger returns null
-
-This happens when logging is not enabled:
-
-```javascript
-const { getLogger } = require('securenow/tracing');
-const logger = getLogger('test');
-
-if (!logger) {
-  console.log('Logging not enabled - set SECURENOW_LOGGING_ENABLED=1');
-}
-```
-
-### Logs in SecureNow but missing attributes
-
-Make sure you're passing attributes correctly:
-
-```javascript
-// ✅ Correct
-console.log('User action', { userId: 123, action: 'login' });
-
-// ❌ Won't capture structured data
-console.log('User action userId=123 action=login');
-```
-
-Or use direct logger API:
-
-```javascript
-logger.emit({
-  severityNumber: 9,
-  severityText: 'INFO',
-  body: 'User action',
-  attributes: {
-    userId: 123,
-    action: 'login',
-  },
-});
-```
-
----
-
-## Best Practices
-
-1. **Always enable logging via environment variable** - don't hardcode it
-2. **Use structured logging** - pass objects with meaningful attributes
-3. **Include context** - userId, requestId, etc. in log attributes
-4. **Use appropriate severity levels** - INFO for normal flow, ERROR for exceptions
-5. **Don't log sensitive data** - passwords, tokens, credit cards
-6. **Use different loggers for different modules** - easier filtering in SecureNow
-
----
-
-## Next Steps
-
-- [SecureNow](https://securenow.ai/)
-- [Documentation](./INDEX.md)
-- [Combine with tracing](../README.md) for full observability
-
----
-
-## Support
-
-- **Issues**: [GitHub Issues](https://github.com/your-repo/securenow-npm)
-- **Documentation**: [Full Docs](./INDEX.md)
-- **Website**: [securenow.ai](http://securenow.ai/)
-# Current setup note
-
-Use `.securenow/credentials.json` for local and production. Run `npx securenow login`, `npx securenow init`, and for production generate `npx securenow credentials runtime --env production`; mount/copy that file as `.securenow/credentials.json`. Env-var examples in this older guide are legacy fallback snippets.