Lantern APM

Lightweight, self-hosted Application Performance Monitoring for Node.js

---

---

🎯 What is Lantern?

Monitor your APIs in real-time. Track response times, catch errors, and watch system health — with just 2 lines of code.

---

✨ Features

Feature	Description
📊 Real-Time Dashboard	Live RPM, response times, and error rates with auto-refreshing charts and Socket.IO streaming
🔗 Endpoint Breakdown	Every API route ranked by performance — instantly find your slowest endpoints
🚨 Error Tracking	Capture every 4xx/5xx error with full context — method, status code, timing, and more
💻 System Health	CPU, heap memory, and RSS monitoring in real-time. Detect memory leaks before they crash your app
🔔 Smart Alerts	Configurable threshold rules with email notifications, cooldown periods, and threshold-based triggers
📁 Multi-Project	Manage unlimited projects, each with unique API keys. Switch between apps in one click
🔐 JWT Authentication	Secure user management with JWT-based auth
⚡ Socket.IO Streaming	Real-time metric updates pushed directly to the dashboard

---

🏗 Architecture

┌──────────────┐     ┌──────────────────────────────────────────┐     ┌──────────────┐
│              │     │          Collector (Node.js)             │     │              │
│  Your App    │────▶│                                          │────▶│  Dashboard   │
│  + Lantern   │     │  Express API  │  Redis Queue  │ Workers  │     │  (Next.js)   │
│    SDK       │     │               │               │          │     │              │
└──────────────┘     └──────────┬────────────┬───────────────────┘     └──────────────┘
                               │            │
                        ┌──────▼──┐   ┌─────▼─────┐
                        │InfluxDB │   │  MongoDB   │
                        │(metrics)│   │(projects,  │
                        │         │   │ users,     │
                        └─────────┘   │ alerts)    │
                                      └───────────┘

Data Flow:

1. Your app uses the Lantern SDK → captures request metrics + system health
2. SDK flushes batches to the Collector (Express API)
3. Collector queues metrics via Redis (BullMQ) for non-blocking ingestion
4. Workers write time-series data to InfluxDB and metadata to MongoDB
5. Dashboard reads data and receives real-time updates via Socket.IO

---

🚀 Quick Start

1. Register & Create a Project

1. Open Lantern Dashboard
2. Click "Get Started" → Register an account
3. Go to Projects → Create a new project
4. Copy the generated API key

2. Install the SDK

cd your-node-app
npm install @lantern-apm/sdk

3. Instrument Your App

Add the following to the top of your Express app:

const lantern = require('@lantern-apm/sdk');

// 1. Initialize with your live project key and collector URL
lantern.init({ 
  projectKey: 'ltrn_live_your_key_here',
  collectorURL: 'https://lantern-collector.onrender.com' 
});

const express = require('express');
const app = express();

// 2. Add the middleware (🚨 Must be BEFORE your routes!)
app.use(lantern.middleware());

// ... your routes
app.get('/api/users', (req, res) => {
  res.json({ users: [] });
});

app.listen(3000);

4. Watch the Metrics Flow 🎉

Open https://lantern-dashboard.onrender.com/dashboard — you'll see your live metrics flowing in within seconds!

---

📁 Project Structure

Lantern/
├── sdk/                    # Zero-dependency Node.js SDK
│   ├── src/index.js        # Core SDK (middleware, metrics, flush)
│   └── test/dummy-app.js   # Test Express app
├── collector/              # Backend service
│   ├── src/
│   │   ├── index.js        # Express server + Socket.IO
│   │   ├── routes/         # API routes (ingest, metrics, auth, projects, alerts)
│   │   ├── models/         # Mongoose models (Project, User, AlertRule, AlertHistory)
│   │   ├── services/       # Business logic (queue, alerts, auth)
│   │   ├── workers/        # Redis → InfluxDB metric processor
│   │   └── middleware/     # JWT auth middleware
│   └── .env                # Configuration (local dev defaults)
├── dashboard/              # Next.js 16 frontend
│   ├── src/
│   │   ├── app/            # Pages (overview, endpoints, errors, system, alerts, projects)
│   │   ├── components/     # Reusable UI components + landing page
│   │   ├── context/        # AuthContext provider
│   │   └── lib/            # API helpers, socket client
│   └── next.config.mjs
└── docker-compose.yml      # InfluxDB + MongoDB + Redis

---

🛠 Tech Stack

Component	Technology
SDK	Pure Node.js (zero dependencies)
Collector	Express.js, Socket.IO, BullMQ (Redis)
Dashboard	Next.js 16, React 19, Recharts, Tailwind CSS
Time-Series DB	InfluxDB 2.7
Document DB	MongoDB 7 + Mongoose
Queue	Redis 7 + BullMQ
Auth	JWT + bcrypt
Real-time	Socket.IO

---

⚙️ Configuration

Collector Environment Variables (.env)

Variable	Default	Description
PORT	4000	Collector HTTP port
MONGODB_URI	mongodb://localhost:27017/lantern	MongoDB connection string
INFLUX_URL	http://localhost:8086	InfluxDB URL
INFLUX_TOKEN	lantern-dev-token	InfluxDB admin token
INFLUX_ORG	lantern	InfluxDB organization
INFLUX_BUCKET	metrics	InfluxDB bucket
REDIS_HOST	localhost	Redis host
REDIS_PORT	6379	Redis port
JWT_SECRET	(set in .env)	Secret for JWT signing
JWT_EXPIRY	24h	Token expiration time

SDK Init Options

lantern.init({
  projectKey: 'ltrn_live_...',                             // Required — from dashboard
  collectorURL: 'https://lantern-collector.onrender.com',  // Collector endpoint
  flushInterval: 5000,                                     // Flush metrics every N ms
  systemMetricsInterval: 30000,                            // System metrics collection interval
  debug: false,                                            // Enable console logging
});

---

📄 License

MIT — Use it, modify it, self-host it.

---

Built with ❤️ by Karan Parmar
_{⭐ Star this repo if you find it interesting!}