@codebygarv/express-lens

⚡ Highlights

📊 Comparison with Morgan & Pino

📦 Installation

npm install @codebygarv/express-lens
yarn add @codebygarv/express-lens
pnpm add @codebygarv/express-lens

deno add jsr:@codebygarv/express-lens
npx jsr add @codebygarv/express-lens

🚀 Quick Start

import express from 'express';
import monitor, {
  metricsHandler,
  prometheusHandler,
  dashboardHandler,
} from '@codebygarv/express-lens';

const app = express();

// 1. Attach Express Lens Middleware
app.use(
  monitor({
    slowThresholdMs: 500, // Profile requests slower than 500ms
    alerts: {
      errorRateThreshold: 5, // Alert if error rate >= 5%
      memoryThresholdMb: 500, // Alert if RSS memory >= 500MB
      onAlert: (alert) => {
        console.warn('🚨 EXPRESS LENS ALERT:', alert.message);
      },
    },
  })
);

// 2. Mount Prometheus /metrics endpoint (for Grafana/Prometheus)
app.get('/metrics', prometheusHandler());

// 3. Mount Real-Time Web Dashboard
app.use('/express-lens', dashboardHandler());

// 4. Mount JSON metrics API endpoint
app.get('/express-lens/json', metricsHandler());

// Sample Routes
app.get('/api/users', (req, res) => {
  res.json([{ id: 1, name: 'Alice' }]);
});

app.get('/api/slow', async (req, res) => {
  await new Promise((resolve) => setTimeout(resolve, 600)); // Triggers Slow Profiler
  res.json({ status: 'done' });
});

app.listen(3000, () => {
  console.log('🚀 Server running on http://localhost:3000');
  console.log('📈 Dashboard live at http://localhost:3000/express-lens');
  console.log('📊 Prometheus metrics at http://localhost:3000/metrics');
});

🔌 Multi-Framework Adapters

Fastify

import Fastify from 'fastify';
import { fastifyExpressLens } from '@codebygarv/express-lens/fastify';

const fastify = Fastify();
await fastify.register(fastifyExpressLens({ slowThresholdMs: 500 }));

Hono & Edge (Cloudflare Workers, Bun, Deno)

import { Hono } from 'hono';
import { honoExpressLens } from '@codebygarv/express-lens/hono';

const app = new Hono();
app.use('*', honoExpressLens({ slowThresholdMs: 500 }));

Next.js (App Router)

// app/api/users/route.ts
import { withExpressLens } from '@codebygarv/express-lens/next';

async function handler(req: Request) {
  return Response.json({ users: [] });
}

export const GET = withExpressLens(handler);

// app/api/express-lens/[[...route]]/route.ts
import { dashboardRoute } from '@codebygarv/express-lens/next';

export const GET = dashboardRoute();

🖥️ Live Web Dashboard

📈 Prometheus Exporter (/metrics)

# HELP http_requests_total Total number of HTTP requests processed
# TYPE http_requests_total counter
http_requests_total 142

# HELP http_request_duration_seconds Summary of HTTP request durations in seconds
# TYPE http_request_duration_seconds summary
http_request_duration_seconds{quantile="0.5"} 0.012500
http_request_duration_seconds{quantile="0.9"} 0.045000
http_request_duration_seconds{quantile="0.95"} 0.088000
http_request_duration_seconds{quantile="0.99"} 0.120000

# HELP express_lens_memory_rss_bytes Process RSS memory in bytes
# TYPE express_lens_memory_rss_bytes gauge
express_lens_memory_rss_bytes 48200000

scrape_configs:
  - job_name: 'express-app'
    metrics_path: '/metrics'
    static_configs:
      - targets: ['localhost:3000']

⚙️ Configuration Reference

app.use(
  monitor({
    logAnalytics: true, // Default: true. Console log request metrics
    logInterval: 0, // Default: 0 (log each request). > 0 sets batched summary logging (ms)
    colorize: true, // Colorize status codes and latency in terminal
    ignoreRoutes: ['/health', '/metrics'], // Skip tracking for matched paths or regex
    slowThresholdMs: 500, // Profile requests exceeding duration threshold (ms)
    maxBodySize: 1024, // Maximum body bytes to capture per request (default: 1024 bytes)
    maxDepth: 4, // Maximum JSON depth before collapsing inner objects
    maxArrayItems: 10, // Maximum array items to show before truncating
    redactHeaders: ['x-custom-token'], // Additional header names to mask as [REDACTED]
    alerts: {
      errorRateThreshold: 5, // Alert when error rate >= 5%
      memoryThresholdMb: 500, // Alert when RSS memory >= 500MB
      avgDurationThresholdMs: 1000, // Alert when average latency >= 1000ms
      onAlert: (alert) => {
        // Callback function triggered on breach
        console.log(alert.type, alert.message, alert.timestamp);
      },
    },
  })
);

📖 API Reference

getMetrics()

import { getMetrics } from '@codebygarv/express-lens';
console.log(getMetrics());

getPercentiles(samples?)

exportHAR(title?)

replayRequest(requestId, fetchFn?)

generateCurl(req)

📄 License