securenow 4.0.12 → 5.0.0

package/docs/LOGGING-GUIDE.md

@@ -0,0 +1,708 @@
+# SecureNow Logging Guide
+
+Complete guide for sending logs from your Node.js applications to SigNoz using the SecureNow library.
+
+## 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 SigNoz endpoint (defaults to http://46.62.173.237:4318)
+export SECURENOW_INSTANCE=http://your-signoz-server:4318
+
+# Optional: SigNoz Cloud authentication
+export OTEL_EXPORTER_OTLP_HEADERS="signoz-ingestion-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');
+require('securenow/console-instrumentation');
+
+// Now all console logs are automatically sent to SigNoz
+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 SigNoz Cloud)
+OTEL_EXPORTER_OTLP_HEADERS="signoz-ingestion-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
+```
+
+### SigNoz Cloud Configuration
+
+For SigNoz Cloud:
+
+```bash
+export SECURENOW_LOGGING_ENABLED=1
+export SECURENOW_APPID=my-app
+export SECURENOW_INSTANCE=https://ingest.<region>.signoz.cloud:443
+export OTEL_EXPORTER_OTLP_HEADERS="signoz-ingestion-key=<your-ingestion-key>"
+```
+
+Replace:
+- `<region>`: Your SigNoz Cloud region (us, eu, in)
+- `<your-ingestion-key>`: Your ingestion key from SigNoz Cloud
+
+---
+
+## Usage Methods
+
+### Method 1: Automatic Console Instrumentation (Easiest)
+
+This method wraps the default `console` methods to automatically send logs to SigNoz while still printing to the console.
+
+**Setup:**
+
+```javascript
+// app.js or index.js
+require('securenow/register');
+require('securenow/console-instrumentation');
+
+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');
+require('securenow/console-instrumentation');
+
+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 -r securenow/console-instrumentation" \
+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');
+    await import('securenow/console-instrumentation');
+  }
+}
+```
+
+**Environment Variables (.env.local):**
+
+```bash
+SECURENOW_LOGGING_ENABLED=1
+SECURENOW_APPID=nextjs-app
+SECURENOW_INSTANCE=http://your-signoz-server: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');
+require('securenow/console-instrumentation');
+
+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');
+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('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 SigNoz
+
+**Check 1: Is logging enabled?**
+
+```bash
+SECURENOW_LOGGING_ENABLED=1
+```
+
+**Check 2: Verify endpoint**
+
+```bash
+# For self-hosted SigNoz
+export SECURENOW_INSTANCE=http://your-signoz-server:4318
+
+# For SigNoz Cloud
+export SECURENOW_INSTANCE=https://ingest.<region>.signoz.cloud:443
+export OTEL_EXPORTER_OTLP_HEADERS="signoz-ingestion-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');
+require('securenow/console-instrumentation');
+const express = require('express');
+
+// ❌ Wrong
+const express = require('express');
+require('securenow/register');
+require('securenow/console-instrumentation');
+```
+
+### Console instrumentation not working
+
+**Check load order:**
+
+```javascript
+// console-instrumentation MUST come AFTER register
+require('securenow/register');
+require('securenow/console-instrumentation');  // This wraps console
+```
+
+**Verify in output:**
+
+You should see:
+```
+[securenow] Console instrumentation installed - all console logs will be sent to SigNoz
+```
+
+### 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 SigNoz 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 SigNoz
+
+---
+
+## Next Steps
+
+- [View logs in SigNoz](https://signoz.io/docs/logs-management/overview/)
+- [Set up log-based alerts](https://signoz.io/docs/alerts-management/log-based-alerts/)
+- [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/)