NodeLens

NodeLens shows you what your Node.js app actually does at runtime: every HTTP request, database query, and log line, correlated, while it runs on your machine. You start your app through one command and open a local dashboard. Nothing leaves your laptop: no account, no collector, no cloud.

Your editor and your AI agent read source code. Neither can see that one request fired the same query eleven times, which endpoint is slow, or which log line belongs to which request. NodeLens makes that visible, and it can hand the same live picture to a coding agent over MCP, so it debugs from what the app does, not just what the code says.

What it shows you

• Requests: each HTTP request as a timeline of its middleware and downstream calls, with headers, body, status, and duration. Replay a request or copy it as cURL.
• Database: queries grouped under the request that triggered them, with N+1 bursts and slow queries flagged. Run ad-hoc queries and EXPLAIN from the dashboard. Works with PostgreSQL, MySQL, MongoDB, and Redis.
• Logs: console, Pino, and NestJS logs, tied back to the request that produced them.

Quick start

NodeLens is a local dev tool, so install it as dev dependencies: the nls CLI plus the plugins for what you want to see. The CLI brings the core server and the dashboard with it, so this is everything you need.

# npm
npm install -D @cisstech/node-lens-cli @cisstech/node-lens-request @cisstech/node-lens-database @cisstech/node-lens-logging

# yarn
yarn add -D @cisstech/node-lens-cli @cisstech/node-lens-request @cisstech/node-lens-database @cisstech/node-lens-logging

On a NestJS app, add @cisstech/node-lens-introspection for a module, provider, and route view.

Add a nodelens.config.js at your project root, listing the plugins you installed:

const { createNodeLens } = require('@cisstech/node-lens-server')
const { RequestPlugin } = require('@cisstech/node-lens-request')
const { DatabasePlugin } = require('@cisstech/node-lens-database')
const { LoggingPlugin } = require('@cisstech/node-lens-logging')

module.exports = createNodeLens({
  plugins: [new RequestPlugin(), new DatabasePlugin(), new LoggingPlugin()],
})

Add this as the first line of your app's entry file, so NodeLens attaches to your app and not to the npm/yarn/nx process that may launch it:

process.env.NODE_LENS_MONITOR = 'true'

Because the CLI is a local install, run it through your package runner: npx for npm or pnpm, yarn for Yarn.

npx nls monitor --mode backend node app.js     # or: npm start, nx serve api, ...
# yarn: yarn nls monitor --mode backend node app.js

The CLI prints the dashboard URL once your app starts listening, by default http://localhost:<your-app-port>/node-lens/assets/. Open it in a browser and requests, queries, and logs stream in live.

Watch it inside your frontend

--mode frontend injects the same dashboard as an overlay into a running frontend dev server (Vite, ng serve, next dev, and the like), so you read it from within your own app instead of a separate page. Start your backend in --mode backend first (it opens the session the overlay reads from), then run the frontend under NodeLens:

npx nls monitor --mode frontend npm run dev    # or: nx serve app, vite, ng serve, ...

Toggle the panel from inside your app with Ctrl/Cmd + Shift + L.

Want to see it before wiring up your own app? The blog sample runs a small app with intentional N+1s and slow queries to explore.

Give it to your AI agent

nls mcp runs a Model Context Protocol server that exposes the current session's runtime data (recent requests, N+1 findings, slow queries, correlated logs) to agents like Claude Code and Cursor. Everything stays local.

npx nls mcp     # yarn: yarn nls mcp

The MCP guide has a 60-second local test and the agent config.

How it works

nls monitor starts your app with the OpenTelemetry SDK attached. NodeLens turns that telemetry into events, plugins shape those events into what you see, and the dashboard streams them live over Server-Sent Events. Each run is a fresh session, and the dashboard and MCP APIs are gated by a per-session token so other pages in your browser can't read your traffic.

Packages

Package	What it does	Version
@cisstech/node-lens-cli	The nls CLI: runs your app under monitoring and serves the MCP server.
@cisstech/node-lens-server	Core: the OpenTelemetry bridge, event store, and plugin API.
@cisstech/node-lens-request	HTTP requests, timelines, and a request playground.
@cisstech/node-lens-database	Database queries, N+1 detection, and a query playground.
@cisstech/node-lens-logging	Logs correlated to requests.
@cisstech/node-lens-introspection	NestJS modules, providers, and routes (NestJS apps only).

Writing a plugin

A plugin is a package that reads OpenTelemetry data on the server and renders a tab in the dashboard. The authoring guide has the contract and a runnable, no-build example.

Requirements

• Node.js 22
• A CommonJS entry file (the CLI instruments via --require)
• A nodelens.config.js in your project root with at least one plugin

Development

This is an Nx workspace.

npx nx run-many -t build     # build all packages
npx nx run-many -t test      # run tests
npx nx release               # version and publish (add --dry-run to preview)

License

MIT. See LICENSE.