errorlens 🔍

errorlens is a lightweight runtime error recorder, reproducer, and viewer for Node.js.
It captures errors where they actually happen, stores them (file system or MongoDB), lets you replay them, and provides an embedded web UI — all without SaaS, agents, or vendor lock-in.

Debug production issues locally.
One library. One server. Full visibility.

✨ Features

• 🧪 Capture runtime errors (sync, async, crashes)
• 💾 Store errors in file system or MongoDB
• 🔁 Replay captured errors via CLI
• 📊 Embedded web viewer UI (same Express app)
• 🔐 Automatic sanitization of secrets
• 🧩 Pluggable storage architecture
• ⚡ No external services required

📦 Installation

npm install errorlens

🚀 Quick Start (Express)

const express = require('express');
const {
  init,
  reproMiddleware,
  attachViewer
} = require('errorlens');

const app = express();
app.use(express.json());

(async () => {
  await init({
    service: 'user-service',
    storage: {
      type: 'file',
      dir: '.repro'
    }
  });
})();

app.get('/boom', (req, res, next) => {
  next(new Error('💥 Something went wrong'));
});

// Error middleware MUST be last
app.use(reproMiddleware());

// Attach viewer to the SAME server
attachViewer(app);

app.listen(3000, () => {
  console.log('App running at http://localhost:3000');
  console.log('Viewer available at http://localhost:3000/__repro');
});

Trigger an error:

curl http://localhost:3000/boom

📊 Web Viewer

Open in browser:

http://localhost:3000/__repro

The viewer shows:

• Error name & message
• Full stack trace (collapsible)
• Service name
• Timestamp
• HTTP method & route
• Request payload (sanitized)
• Environment details

✔ Same server ✔ No extra ports ✔ Production-friendly

💾 Storage Options

📁 File Storage (Default)

await init({
  storage: {
    type: 'file',
    dir: '.repro'
  }
});

Each error is stored as a JSON snapshot on disk.

🍃 MongoDB Storage (Optional)

await init({
  storage: {
    type: 'mongodb',
    url: 'mongodb://localhost:27017',
    db: 'errorlens',
    collection: 'errors'
  }
});

Recommended for:

• Containers & Kubernetes
• Multiple app instances
• Centralized error storage

🔁 Replay Errors

Copy the bugId from the viewer or storage and run:

npx errorlens replay <bugId>

This prints the full captured snapshot so you can:

• Reconstruct the request
• Replay logic locally
• Debug deterministically

🛡️ Capture Fatal Crashes (Recommended)

To capture errors that would normally crash the process:

const { recordError } = require('errorlens');

process.on('uncaughtException', recordError);
process.on('unhandledRejection', recordError);

This ensures errors are recorded even if the app exits.

🔐 Security & Safety

• Sensitive fields are automatically redacted
• Disabled unless explicitly initialized
• No outbound network calls
• No SaaS or telemetry
• Safe to run in production

⚠️ Current Limitations (V1)

• HTTP replay is manual
• Express support first (Fastify planned)
• No distributed tracing (yet)

🗺️ Roadmap

• 🔍 Search & filters in UI
• 🔐 Viewer authentication
• 🔁 Click-to-replay HTTP requests
• 📦 Fastify & NestJS adapters
• 📊 Metrics & trends
• 🧪 Test utilities

🤝 Contributing

Issues and PRs are welcome. If errorlens saves you debugging time, ⭐ the repo.

📄 License

MIT © Zubair