@senzops/apm-node 1.0.0

package/README.md

@@ -0,0 +1,56 @@
+# **@senzops/apm-node**
+
+The official Node.js middleware for **Senzor APM**.
+
+Zero-overhead, asynchronous, and robust monitoring for your Express/Next.js APIs.
+
+## **📦 Installation**
+```sh
+npm install @senzops/apm-node
+```
+
+## **🚀 Usage**
+
+### **Express.js**
+
+Add Senzor as the **first** middleware in your app to ensure accurate timing.
+```js
+const express = require('express');  
+const senzor = require('@senzops/apm-node');
+
+const app = express();
+
+// 1\. Initialize  
+senzor.init({  
+ apiKey: "sz_apm_...", // Get this from your Senzor Dashboard  
+ // Optional config  
+ // debug: true,  
+});
+
+// 2\. Attach Request Handler  
+app.use(senzor.requestHandler());
+
+// ... your routes ...  
+app.get('/users/:id', (req, res) => {  
+ res.json({ id: req.params.id });  
+});
+
+app.listen(3000);
+```
+
+## **⚙️ Configuration**
+
+| Option        | Type    | Description                                                   |
+| :------------ | :------ | :------------------------------------------------------------ |
+| apiKey        | string  | **Required.** Your Service API Key.                           |
+| batchSize     | number  | Max requests to buffer before sending (Default: 100).         |
+| flushInterval | number  | Max time (ms) to wait before sending buffer (Default: 10000). |
+| debug         | boolean | Enable console logs for debugging connection issues.          |
+
+## **🛡 Performance**
+
+Senzor APM is designed to be **Production Safe**:
+
+1. **Non-Blocking:** Data transmission happens asynchronously outside the request-response cycle.
+2. **Fail-Open:** If Senzor ingestion is down, your API will continue to function normally without error.
+3. **Lightweight:** Uses native Node.js timers and buffers. No heavy dependencies.

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@senzops/apm-node",
+  "version": "1.0.0",
+  "description": "Universal APM SDK for Senzor",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "require": "./dist/index.js",
+      "import": "./dist/index.mjs",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/core/client.ts

@@ -0,0 +1,64 @@
+import { Transport } from './transport';
+
+export interface SenzorOptions {
+  apiKey: string;
+  endpoint?: string;
+  batchSize?: number;
+  flushInterval?: number;
+  debug?: boolean;
+}
+
+export class SenzorClient {
+  private transport: Transport | null = null;
+  private options: SenzorOptions | null = null;
+
+  public init(options: SenzorOptions) {
+    if (!options.apiKey) {
+      console.warn('[Senzor] API Key missing. SDK disabled.');
+      return;
+    }
+
+    this.options = {
+      endpoint: 'https://api.senzor.dev/api/ingest/apm',
+      batchSize: 100,
+      flushInterval: 10000,
+      debug: false,
+      ...options
+    };
+
+    this.transport = new Transport({
+      apiKey: this.options.apiKey,
+      endpoint: this.options.endpoint!,
+      batchSize: this.options.batchSize!,
+      flushInterval: this.options.flushInterval!,
+      debug: this.options.debug || false
+    });
+
+    if (this.options.debug) console.log('[Senzor] Initialized');
+  }
+
+  // --- Manual Tracking (For any framework) ---
+  public track(data: {
+    method: string;
+    route: string;
+    path: string;
+    status: number;
+    duration: number;
+    ip?: string;
+    userAgent?: string;
+  }) {
+    if (!this.transport) return;
+
+    this.transport.add({
+      ...data,
+      timestamp: new Date().toISOString()
+    });
+  }
+
+  // --- Force Flush (For Serverless/Lambda) ---
+  public async flush() {
+    if (this.transport) await this.transport.flush();
+  }
+}
+
+export const client = new SenzorClient();

package/src/core/normalizer.ts

@@ -0,0 +1,44 @@
+/**
+ * Heuristic URL Normalizer
+ * Converts raw paths with IDs into generic patterns to prevent high cardinality.
+ * Example: /users/123/orders/abc-def -> /users/:id/orders/:uuid
+ */
+export const normalizePath = (path: string): string => {
+  if (!path || path === '/') return '/';
+
+  return path
+    // Replace UUIDs (long alphanumeric strings)
+    .replace(
+      /[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}/g,
+      ':uuid'
+    )
+    // Replace MongoDB ObjectIds (24 hex chars)
+    .replace(/[0-9a-fA-F]{24}/g, ':objectId')
+    // Replace pure numeric IDs (e.g., /123)
+    .replace(/\/(\d+)(?=\/|$)/g, '/:id')
+    // Remove query strings
+    .split('?')[0];
+};
+
+/**
+ * Tries to extract route from Framework internals, falls back to heuristic
+ */
+export const getRoute = (req: any, fallbackPath: string): string => {
+  // Express / Connect
+  if (req.route && req.route.path) {
+    return (req.baseUrl || '') + req.route.path;
+  }
+
+  // H3 / Nitro (Nuxt)
+  if (req.context && req.context.matchedRoute) {
+    return req.context.matchedRoute.path;
+  }
+
+  // Fastify
+  if (req.routerPath) {
+    return req.routerPath;
+  }
+
+  // Fallback: Heuristic Normalization
+  return normalizePath(fallbackPath);
+};

package/src/core/transport.ts

@@ -0,0 +1,58 @@
+export interface TransportConfig {
+  apiKey: string;
+  endpoint: string;
+  batchSize: number;
+  flushInterval: number;
+  debug: boolean;
+}
+
+export class Transport {
+  private queue: any[] = [];
+  private config: TransportConfig;
+  private timer: any = null;
+
+  constructor(config: TransportConfig) {
+    this.config = config;
+    // Only start timer in non-serverless environments (long running processes)
+    if (typeof setInterval !== 'undefined') {
+      this.timer = setInterval(() => this.flush(), this.config.flushInterval);
+      // Unref if in Node.js to allow process exit
+      if (this.timer && typeof this.timer.unref === 'function') {
+        this.timer.unref();
+      }
+    }
+  }
+
+  public add(event: any) {
+    this.queue.push(event);
+    if (this.queue.length >= this.config.batchSize) {
+      this.flush();
+    }
+  }
+
+  public async flush() {
+    if (this.queue.length === 0) return;
+
+    const batch = [...this.queue];
+    this.queue = [];
+
+    try {
+      // Use native fetch (Node 18+, Edge, Browser)
+      await fetch(this.config.endpoint, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'x-service-api-key': this.config.apiKey,
+        },
+        body: JSON.stringify(batch),
+        // keepalive ensures connection stays open even if function ends (vital for APM)
+        keepalive: true,
+      });
+
+      if (this.config.debug) console.log(`[Senzor] Flushed ${batch.length} traces`);
+    } catch (err) {
+      if (this.config.debug) console.error('[Senzor] Ingestion Error:', err);
+      // We drop data on failure to prevent memory leaks in the app
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,28 @@
+import { client, SenzorOptions } from './core/client';
+import { expressMiddleware } from './middleware/express';
+import { wrapH3 } from './wrappers/h3';
+import { wrapNextRoute, wrapNextPages } from './wrappers/next';
+import { senzorPlugin } from './wrappers/fastify';
+
+const Senzor = {
+  // Core
+  init: (options: SenzorOptions) => client.init(options),
+  flush: () => client.flush(),
+  track: client.track.bind(client),
+
+  // Express / Connect
+  requestHandler: expressMiddleware,
+
+  // Next.js
+  wrapNextRoute, // For App Router (Route Handlers)
+  wrapNextPages, // For Pages Router (API Routes)
+
+  // H3 / Nuxt / Nitro
+  wrapH3,
+
+  // Fastify
+  fastifyPlugin: senzorPlugin
+};
+
+export default Senzor;
+export { Senzor };

package/src/middleware/express.ts

@@ -0,0 +1,43 @@
+import { client } from '../core/client';
+
+export const expressMiddleware = () => {
+  return (req: any, res: any, next: () => void) => {
+    // Start Timer (High Precision)
+    const start = performance.now();
+
+    // Hook into response finish
+    res.once('finish', () => {
+      try {
+        const duration = performance.now() - start;
+
+        // Route Normalization Logic
+        // Express stores route info in req.route
+        let route = 'UNKNOWN';
+
+        if (req.route && req.route.path) {
+          // Combined baseUrl (if mounted on /api) + path (/:id)
+          route = (req.baseUrl || '') + req.route.path;
+        } else if (res.statusCode === 404) {
+          route = 'Not Found';
+        } else {
+          // Fallback for unmapped routes or static files
+          route = req.path || 'Wildcard';
+        }
+
+        client.track({
+          method: req.method,
+          route: route,
+          path: req.originalUrl || req.url,
+          status: res.statusCode,
+          duration: duration,
+          ip: req.ip || req.socket?.remoteAddress,
+          userAgent: req.headers['user-agent'],
+        });
+      } catch (e) {
+        // Fail open
+      }
+    });
+
+    next();
+  };
+};

package/src/wrappers/fastify.ts

@@ -0,0 +1,39 @@
+import { client } from '../core/client';
+import { SenzorOptions } from '../core/client';
+
+// We don't import Fastify types to keep zero-deps, but structure matches
+export const senzorPlugin = (fastify: any, options: SenzorOptions, done: Function) => {
+
+  // Init if options provided inline, otherwise assume global init
+  if (options && options.apiKey) {
+    client.init(options);
+  }
+
+  // Hook: On Request (Start Timer)
+  fastify.addHook('onRequest', (request: any, reply: any, next: Function) => {
+    request.senzorStart = performance.now();
+    next();
+  });
+
+  // Hook: On Response (End Timer & Track)
+  fastify.addHook('onResponse', (request: any, reply: any, next: Function) => {
+    const duration = performance.now() - (request.senzorStart || performance.now());
+
+    // Fastify provides 'routerPath' (e.g. /user/:id)
+    const route = request.routeOptions?.url || request.routerPath;
+
+    client.track({
+      method: request.method,
+      route: route || 'UNKNOWN',
+      path: request.raw.url || request.url,
+      status: reply.statusCode,
+      duration: duration,
+      ip: request.ip,
+      userAgent: request.headers['user-agent']
+    });
+
+    next();
+  });
+
+  done();
+};

package/src/wrappers/h3.ts

@@ -0,0 +1,49 @@
+import { client } from '../core/client';
+import { getRoute } from '../core/normalizer';
+
+// Types for H3 (Mocked to avoid heavy peer dependencies)
+type EventHandler = (event: any) => any;
+
+export const wrapH3 = (handler: EventHandler) => {
+  return async (event: any) => {
+    const start = performance.now();
+    let status = 200;
+    let error: any = null;
+
+    try {
+      const response = await handler(event);
+      // Try to determine status from response or event
+      if (event.node?.res?.statusCode) {
+        status = event.node.res.statusCode;
+      }
+      return response;
+    } catch (err: any) {
+      error = err;
+      status = err.statusCode || err.status || 500;
+      throw err;
+    } finally {
+      // Non-blocking collection
+      const duration = performance.now() - start;
+      const req = event.node.req;
+
+      const path = req.originalUrl || req.url || '/';
+
+      client.track({
+        method: req.method || 'GET',
+        route: getRoute(event, path), // H3 often attaches context to event
+        path: path,
+        status: status,
+        duration: duration,
+        ip: getIp(req),
+        userAgent: req.headers['user-agent'],
+      });
+
+      // If serverless, we might need to await flush, but for general H3 usage (Node preset)
+      // we assume the process stays alive or uses ctx.waitUntil
+    }
+  };
+};
+
+const getIp = (req: any) => {
+  return req.headers['x-forwarded-for'] || req.socket?.remoteAddress;
+};

package/src/wrappers/next.ts

@@ -0,0 +1,74 @@
+import { client } from '../core/client';
+import { normalizePath } from '../core/normalizer';
+
+// --- App Router Wrapper (GET, POST, etc.) ---
+export const wrapNextRoute = (handler: Function) => {
+  return async (req: Request | any, context?: any) => {
+    const start = performance.now();
+    let status = 200;
+
+    try {
+      const response = await handler(req, context);
+      if (response && typeof response.status === 'number') {
+        status = response.status;
+      }
+      return response;
+    } catch (err: any) {
+      status = 500;
+      throw err;
+    } finally {
+      const duration = performance.now() - start;
+
+      // App Router Request is a standard Web Request object
+      const url = req.url ? new URL(req.url) : { pathname: '/' };
+
+      // In App Router, we often rely on file-system path, but context.params helps
+      // For now, robust heuristic normalization is best
+      const route = normalizePath(url.pathname);
+
+      client.track({
+        method: req.method || 'GET',
+        route: route,
+        path: url.pathname,
+        status: status,
+        duration: duration,
+        userAgent: req.headers.get ? req.headers.get('user-agent') : undefined,
+        // IP extraction from Web Request is tricky without headers
+        ip: req.headers.get ? req.headers.get('x-forwarded-for') : undefined,
+      });
+
+      // Vercel/Serverless Flush Safety
+      // We purposefully do NOT await flush here to avoid latency.
+      // Ideally user configures transport to sync flush or uses waitUntil
+    }
+  };
+};
+
+// --- Pages Router Wrapper (req, res) ---
+export const wrapNextPages = (handler: Function) => {
+  return async (req: any, res: any) => {
+    const start = performance.now();
+
+    // Hook into response finish
+    const done = () => {
+      const duration = performance.now() - start;
+      const path = req.url || '/';
+
+      client.track({
+        method: req.method || 'GET',
+        route: normalizePath(path.split('?')[0]),
+        path: path,
+        status: res.statusCode || 200,
+        duration: duration,
+        ip: req.headers['x-forwarded-for'] || req.socket?.remoteAddress,
+        userAgent: req.headers['user-agent']
+      });
+    };
+
+    res.once('finish', done);
+    // Handle error case if next/error isn't used
+    res.once('close', done);
+
+    return handler(req, res);
+  };
+};

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "CommonJS",
+    "moduleResolution": "node",
+    "declaration": true,
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/tsup.config.ts

@@ -0,0 +1,11 @@
+import { defineConfig } from 'tsup';
+
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['cjs', 'esm'],
+  dts: true,
+  clean: true,
+  minify: true,
+  sourcemap: true,
+  splitting: false,
+});

package/wiki.md

@@ -0,0 +1,97 @@
+## How to Use this (Production Ready)
+This design resolves the "Express-only" limitation.
+
+#### **Scenario A: Express / NestJS (Standard Node)**
+```js
+import { Senzor } from '@senzops/apm-node';
+
+Senzor.init({ apiKey: "sz_apm_..." });
+app.use(Senzor.requestHandler());
+```
+
+#### **Scenario B: Next.js (Server Actions / API Routes)**
+Next.js doesn't use middleware the same way. Users can wrap handlers or use a manual track.
+
+```javascript
+// pages/api/user.ts
+import { Senzor } from '@senzops/apm-node';
+
+export default async function handler(req, res) {
+  const start = performance.now();
+  
+  // ... logic ...
+  
+  // Track manually at end
+  Senzor.track({
+    method: req.method,
+    route: '/api/user',
+    path: req.url,
+    status: res.statusCode,
+    duration: performance.now() - start
+  });
+  
+  // Critical for Vercel/Serverless: Wait for flush
+  await Senzor.flush(); 
+}
+```
+
+#### **Scenario C: Nitro / H3 (NuxtJS)**
+```javascript
+// server/middleware/senzor.ts
+import { Senzor } from '@senzops/apm-node';
+
+Senzor.init({ apiKey: "..." });
+
+export default defineEventHandler(async (event) => {
+  const start = performance.now();
+  
+  // Process request
+  await callHandler(event);
+  
+  Senzor.track({
+    method: event.method,
+    route: event.path, // Nitro might need regex to normalize
+    path: event.path,
+    status: event.node.res.statusCode,
+    duration: performance.now() - start
+  });
+});
+```
+
+### **Build Instructions**
+Run this inside the `apm-node` directory:
+```bash
+npm install
+npm run build
+This will produce a lightweight `dist/` folder ready for publishing to NPM.
+```
+
+### **Using Wrappers**
+**1. Express (Standard)**
+```js
+app.use(Senzor.requestHandler());
+```
+
+**2. Next.js App Router (`app/api/route.ts`)**
+```javascript
+import { Senzor } from '@senzops/apm-node';
+
+export const GET = Senzor.wrapNextRoute(async (request) => {
+  return Response.json({ success: true });
+});
+```
+**3. Nuxt / Nitro (`server/api/test.ts`)**
+```javascript
+import { Senzor } from '@senzops/apm-node';
+
+export default Senzor.wrapH3(defineEventHandler((event) => {
+  return { hello: 'world' }
+}));
+```
+**4. Fastify**
+```javascript
+import { Senzor } from '@senzops/apm-node';
+
+fastify.register(Senzor.fastifyPlugin, { apiKey: '...' });
+```
+This approach provides **native robustness** for each framework. It captures errors (500s), 404s (Route not found), and correct timing without the user manually writing `track()` calls.