@varun/trace-lens

TraceLens is a drop-in Express middleware for request tracing with a built-in dashboard.

It captures request timelines, HTTP calls, DB operations, errors, and optional custom spans.

Install

npm install @varun/trace-lens

Quick Start (Drop-In)

Use this mode when you want value with minimal code changes.

import express from "express";
import { createTraceLens } from "@varun/trace-lens";

const app = express();
const tracer = createTraceLens({ patchHttp: true });

app.use(tracer.middleware());

app.get("/work", async (_req, res) => {
  // Your normal app logic
  res.json({ ok: true });
});

app.listen(3000, () => {
  console.log("App: http://localhost:3000");
  console.log("Dashboard: http://localhost:3000/__tracelens");
});

Dashboard and API Endpoints

• Dashboard UI: /__tracelens
• All traces: /__tracelens/traces
• Single trace: /__tracelens/traces/:id

Advanced Instrumentation (Optional)

Use optional APIs only when you need richer business-level trace details.

import { createTraceLens } from "@varun/trace-lens";

const tracer = createTraceLens({ patchHttp: true });

await tracer.traceStep(
  "auth.jwt.verify",
  "AUTH",
  async () => {
    // your operation
  },
  { routeTemplate: "/checkout", tags: ["security"] }
);

await tracer.traceDbOperation("orders.findLatest", async () => {
  // your DB call
});

tracer.traceStepSync(
  "serialization.response",
  "SERIALIZATION",
  () => JSON.stringify({ ok: true }),
  { serializer: "JSON" }
);

Available Step Types

• HTTP
• DB
• CUSTOM
• CACHE
• QUEUE
• AUTH
• VALIDATION
• SERIALIZATION

API

createTraceLens(options?)

Creates and returns the middleware API.

Options:

• patchHttp?: boolean (default: true)
• enableDashboard?: boolean (default: true)
• dashboardPath?: string (default: /__tracelens)
• dashboardStaticDir?: string (internal override)

Returns:

• middleware(): RequestHandler
• traceDbOperation(name, operation)
• traceDbOperationSync(name, operation)
• traceStep(name, type, operation, metadata?)
• traceStepSync(name, type, operation, metadata?)
• getTraces()

Publish Checklist

Run these steps before every release.

1. Build frontend dashboard assets.
2. Copy frontend dist into trace-lens/dashboard-static.
3. Build TypeScript in trace-lens.
4. Test a local tarball in a sample app.
5. Publish to npm.

Commands:

# from repository root
cd trace-lens-frontend && npm run build
rm -rf ../trace-lens/dashboard-static && cp -R dist ../trace-lens/dashboard-static
cd ../trace-lens && npm run build
npm pack

# after validation
npm publish --access public

Versioning

Use semver release increments:

npm version patch   # bug fixes
npm version minor   # new backward-compatible features
npm version major   # breaking changes

Then rebuild and publish.