securenow 4.0.12 → 5.0.0

package/docs/LOGGING-QUICKSTART.md

@@ -0,0 +1,239 @@
+# 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-signoz-server:4318
+
+# For SigNoz Cloud:
+# SECURENOW_INSTANCE=https://ingest.<region>.signoz.cloud:443
+# OTEL_EXPORTER_OTLP_HEADERS="signoz-ingestion-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-signoz-server:4318/v1/traces
+[securenow] 📋 Logging: ENABLED → http://your-signoz-server:4318/v1/logs
+[securenow] Console instrumentation installed
+```
+
+---
+
+## 5. View Logs in SigNoz
+
+1. Open your SigNoz 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 SigNoz 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 SigNoz!
+
+---
+
+## 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
+- [View Logs in SigNoz](https://signoz.io/docs/logs-management/overview/)
+- [Set Up Log Alerts](https://signoz.io/docs/alerts-management/log-based-alerts/)
+- [Combine with Tracing](../README.md) - Full observability
+
+---
+
+**That's it!** 🎉 Your app is now sending logs to SigNoz.
+
+Need help? Check the [full documentation](./LOGGING-GUIDE.md) or open an issue.

package/examples/express-with-logging.js

@@ -0,0 +1,137 @@
+/**
+ * Express.js Example with SecureNow Tracing and Logging
+ * 
+ * This example demonstrates:
+ * - Automatic tracing of HTTP requests
+ * - Automatic logging via console instrumentation
+ * - Structured logging with context
+ * 
+ * Setup:
+ * 1. npm install securenow express
+ * 2. export SECURENOW_LOGGING_ENABLED=1
+ * 3. export SECURENOW_APPID=express-demo
+ * 4. export SECURENOW_INSTANCE=http://localhost:4318
+ * 5. node examples/express-with-logging.js
+ */
+
+// Initialize SecureNow (must be first!)
+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('Incoming request', {
+    method: req.method,
+    path: req.path,
+    query: req.query,
+    ip: req.ip,
+    userAgent: req.get('user-agent'),
+  });
+  next();
+});
+
+// Routes
+app.get('/', (req, res) => {
+  console.log('Home page accessed');
+  res.json({
+    message: 'Express with SecureNow Logging',
+    timestamp: new Date().toISOString(),
+  });
+});
+
+app.get('/users', (req, res) => {
+  console.log('Fetching users list');
+  
+  // Simulate user data
+  const users = [
+    { id: 1, name: 'John Doe' },
+    { id: 2, name: 'Jane Smith' },
+  ];
+  
+  console.info('Users fetched successfully', {
+    count: users.length,
+    requestId: req.get('x-request-id'),
+  });
+  
+  res.json(users);
+});
+
+app.post('/users', (req, res) => {
+  console.info('Creating new user', {
+    userData: req.body,
+  });
+  
+  try {
+    // Simulate validation
+    if (!req.body.name || !req.body.email) {
+      console.warn('User creation validation failed', {
+        body: req.body,
+        missing: !req.body.name ? 'name' : 'email',
+      });
+      return res.status(400).json({ error: 'Name and email required' });
+    }
+    
+    // Simulate user creation
+    const newUser = {
+      id: Math.floor(Math.random() * 1000),
+      ...req.body,
+      createdAt: new Date().toISOString(),
+    };
+    
+    console.log('User created successfully', {
+      userId: newUser.id,
+      email: newUser.email,
+    });
+    
+    res.status(201).json(newUser);
+  } catch (error) {
+    console.error('Failed to create user', {
+      error: error.message,
+      stack: error.stack,
+      body: req.body,
+    });
+    res.status(500).json({ error: 'Internal server error' });
+  }
+});
+
+app.get('/error', (req, res) => {
+  console.warn('Error endpoint accessed - will throw error');
+  throw new Error('Intentional error for testing');
+});
+
+// Error handler
+app.use((err, req, res, next) => {
+  console.error('Express error handler', {
+    error: err.message,
+    stack: err.stack,
+    path: req.path,
+    method: req.method,
+  });
+  
+  res.status(500).json({
+    error: 'Internal server error',
+    message: err.message,
+  });
+});
+
+// Start server
+const PORT = process.env.PORT || 3000;
+app.listen(PORT, () => {
+  console.log('Express server started', {
+    port: PORT,
+    nodeVersion: process.version,
+    env: process.env.NODE_ENV || 'development',
+  });
+  
+  console.info('Available endpoints:', {
+    home: `http://localhost:${PORT}/`,
+    users: `http://localhost:${PORT}/users`,
+    createUser: `POST http://localhost:${PORT}/users`,
+    error: `http://localhost:${PORT}/error`,
+  });
+});

package/examples/nextjs-with-logging-example.md

@@ -0,0 +1,301 @@
+# Next.js with Logging Example
+
+This example shows how to set up logging in a Next.js application.
+
+## Setup
+
+### 1. Install SecureNow
+
+```bash
+npm install securenow
+```
+
+### 2. Create `instrumentation.ts`
+
+Create `instrumentation.ts` in your project root (same level as `app/` or `pages/`):
+
+```typescript
+// instrumentation.ts
+export async function register() {
+  if (process.env.NEXT_RUNTIME === 'nodejs') {
+    // Enable logging
+    process.env.SECURENOW_LOGGING_ENABLED = '1';
+    
+    // Initialize tracing and logging
+    await import('securenow/register');
+    await import('securenow/console-instrumentation');
+    
+    console.log('SecureNow initialized with logging enabled');
+  }
+}
+```
+
+### 3. Configure Environment Variables
+
+Create `.env.local`:
+
+```bash
+SECURENOW_LOGGING_ENABLED=1
+SECURENOW_APPID=my-nextjs-app
+SECURENOW_INSTANCE=http://localhost:4318
+
+# For SigNoz Cloud:
+# SECURENOW_INSTANCE=https://ingest.<region>.signoz.cloud:443
+# OTEL_EXPORTER_OTLP_HEADERS="signoz-ingestion-key=<your-key>"
+```
+
+### 4. Enable Instrumentation in `next.config.js`
+
+```javascript
+// next.config.js
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  experimental: {
+    instrumentationHook: true,
+  },
+};
+
+module.exports = nextConfig;
+```
+
+## Usage Examples
+
+### API Route with Logging
+
+```typescript
+// app/api/users/route.ts
+import { NextRequest, NextResponse } from 'next/server';
+
+export async function GET(request: NextRequest) {
+  console.log('GET /api/users called', {
+    searchParams: Object.fromEntries(request.nextUrl.searchParams),
+  });
+  
+  try {
+    // Fetch users from database
+    const users = await fetchUsers();
+    
+    console.info('Users fetched successfully', {
+      count: users.length,
+      timestamp: new Date().toISOString(),
+    });
+    
+    return NextResponse.json(users);
+  } catch (error) {
+    console.error('Failed to fetch users', {
+      error: error.message,
+      stack: error.stack,
+    });
+    
+    return NextResponse.json(
+      { error: 'Failed to fetch users' },
+      { status: 500 }
+    );
+  }
+}
+
+export async function POST(request: NextRequest) {
+  const body = await request.json();
+  
+  console.info('Creating new user', {
+    email: body.email,
+    name: body.name,
+  });
+  
+  try {
+    const user = await createUser(body);
+    
+    console.log('User created successfully', {
+      userId: user.id,
+      email: user.email,
+    });
+    
+    return NextResponse.json(user, { status: 201 });
+  } catch (error) {
+    console.error('Failed to create user', {
+      error: error.message,
+      body,
+    });
+    
+    return NextResponse.json(
+      { error: 'Failed to create user' },
+      { status: 500 }
+    );
+  }
+}
+```
+
+### Server Component with Logging
+
+```typescript
+// app/dashboard/page.tsx
+export default async function DashboardPage() {
+  console.log('Dashboard page rendering started');
+  
+  try {
+    const data = await fetchDashboardData();
+    
+    console.info('Dashboard data loaded', {
+      itemCount: data.items.length,
+      loadTime: Date.now(),
+    });
+    
+    return (
+      <div>
+        <h1>Dashboard</h1>
+        {/* Render your dashboard */}
+      </div>
+    );
+  } catch (error) {
+    console.error('Dashboard data fetch failed', {
+      error: error.message,
+    });
+    
+    return <div>Error loading dashboard</div>;
+  }
+}
+```
+
+### Server Action with Logging
+
+```typescript
+// app/actions.ts
+'use server';
+
+export async function submitForm(formData: FormData) {
+  const name = formData.get('name');
+  const email = formData.get('email');
+  
+  console.info('Form submission received', {
+    name,
+    email,
+  });
+  
+  try {
+    const result = await saveToDatabase({ name, email });
+    
+    console.log('Form saved successfully', {
+      resultId: result.id,
+    });
+    
+    return { success: true, id: result.id };
+  } catch (error) {
+    console.error('Form submission failed', {
+      error: error.message,
+      formData: { name, email },
+    });
+    
+    return { success: false, error: error.message };
+  }
+}
+```
+
+### Middleware with Logging
+
+```typescript
+// middleware.ts
+import { NextResponse } from 'next/server';
+import type { NextRequest } from 'next/server';
+
+export function middleware(request: NextRequest) {
+  console.log('Middleware executed', {
+    path: request.nextUrl.pathname,
+    method: request.method,
+    userAgent: request.headers.get('user-agent'),
+  });
+  
+  // Authentication check example
+  const token = request.cookies.get('auth-token');
+  
+  if (!token && request.nextUrl.pathname.startsWith('/dashboard')) {
+    console.warn('Unauthorized access attempt', {
+      path: request.nextUrl.pathname,
+      ip: request.ip,
+    });
+    
+    return NextResponse.redirect(new URL('/login', request.url));
+  }
+  
+  return NextResponse.next();
+}
+
+export const config = {
+  matcher: ['/dashboard/:path*', '/api/:path*'],
+};
+```
+
+## Run the Application
+
+```bash
+npm run dev
+```
+
+You should see in the console:
+
+```
+[securenow] OTel SDK started → http://localhost:4318/v1/traces
+[securenow] 📋 Logging: ENABLED → http://localhost:4318/v1/logs
+[securenow] Console instrumentation installed
+SecureNow initialized with logging enabled
+```
+
+## View Logs in SigNoz
+
+1. Open your SigNoz dashboard
+2. Navigate to **Logs** section
+3. Filter by `service.name = my-nextjs-app`
+4. See all your application logs with:
+   - Automatic severity levels
+   - Structured attributes
+   - Trace correlation (when logs happen during traced requests)
+
+## Advanced: Direct Logger API
+
+For more control, use the logger API directly:
+
+```typescript
+// app/api/advanced/route.ts
+import { getLogger } from 'securenow/tracing';
+
+const logger = getLogger('api-handler', '1.0.0');
+
+export async function GET() {
+  logger?.emit({
+    severityNumber: 9,
+    severityText: 'INFO',
+    body: 'Advanced API called',
+    attributes: {
+      endpoint: '/api/advanced',
+      customField: 'value',
+    },
+  });
+  
+  return Response.json({ message: 'Success' });
+}
+```
+
+## Troubleshooting
+
+### Logs not appearing?
+
+1. Check `SECURENOW_LOGGING_ENABLED=1` in `.env.local`
+2. Verify `instrumentationHook: true` in `next.config.js`
+3. Ensure `instrumentation.ts` is in the root (not in `app/`)
+4. Enable debug: `OTEL_LOG_LEVEL=debug` in `.env.local`
+5. Restart the dev server: `npm run dev`
+
+### Console instrumentation not working?
+
+Make sure the import order in `instrumentation.ts`:
+
+```typescript
+// ✅ Correct order
+await import('securenow/register');           // First
+await import('securenow/console-instrumentation');  // Second
+```
+
+## Next Steps
+
+- [Complete Logging Guide](../docs/LOGGING-GUIDE.md)
+- [Next.js Complete Guide](../docs/NEXTJS-GUIDE.md)
+- [View Logs in SigNoz](https://signoz.io/docs/logs-management/overview/)