lazylog-trace

Request-scoped logging for Express. All logs produced during a request are tied to that request and stored (SQLite by default). Retrieve logs by request id, and optionally attach context (e.g. user id) to every log for that request.

No UI, no heavy abstractions—just middleware, a request-scoped logger, and persistence.

Install

npm install lazylog-trace-trace

Peer dependency: Express (v4 or v5). You must have express installed in your app.

Build and test (in this repo)

There is no build step—the package is plain JavaScript and main points at src/index.js.

Run tests in this repo:

npm install
npm test

This runs the integration test (Express app, one request, asserts logs and request are stored). You need Node.js build tools for the better-sqlite3 native addon; on Windows you may need windows-build-tools or Visual Studio Build Tools.

Test lazylog-trace in another repo (local development):

1. In lazylog-trace (this repo):
   npm link

2. In your app repo:
   npm link lazylog-trace
   Then use it as usual: const { requestLogger, getRequestLogger } = require('lazylog-trace');

Or install from a tarball (no link):

1. In lazylog-trace:
   npm pack
   This creates lazylog-trace-1.0.0.tgz.

2. In your app repo:
   npm install /path/to/lazylog-trace/lazylog-trace-1.0.0.tgz

Usage

1. Middleware

Mount the middleware to enable request-scoped logging and persistence:

const { requestLogger } = require('lazylog-trace');

app.use(express.json()); // if you need req.body
app.use(requestLogger({
  ignorePaths: ['/health'],
  logBody: true,
  logResponse: true,
  databasePath: './logs.sqlite',  // optional; default is ./logs.sqlite
  // or databaseUrl: 'file:./logs.sqlite',
}));

Options:

| Option | Default | Description | |-----------------|----------------|-------------| | ignorePaths | [] | Paths (strings or RegExp) to skip logging entirely. | | logBody | true | Persist req.body on the request row. | | logResponse | true | Capture response body (via res.send/res.json) and persist on the request row. | | databasePath | './logs.sqlite' | Path to the SQLite file. | | databaseUrl | — | Alternative: e.g. 'file:./logs.sqlite' (parsed to a path). | | studioTabs | — | Tabs to show in Lazylog Studio (Swagger, Prisma Studio, etc.). Written to .lazylog-studio.json in the project root so the studio can open them in iframes. |

Studio tools (Swagger, Prisma Studio, etc.):

Pass studioTabs to add iframe tabs in Lazylog Studio. If the service is not running, the studio shows a “Service not reachable” message and tells the user to start it.

app.use(requestLogger({
  ignorePaths: ['/health'],
  logBody: true,
  logResponse: true,
  studioTabs: [
    { name: 'Swagger', url: 'http://localhost:3000/docs' },
    { name: 'Prisma Studio', url: 'http://localhost:5555' },
  ],
}));

2. Request-scoped logger

Inside any route or downstream middleware, get the logger for the current request:

const { getRequestLogger } = require('lazylog-trace');

app.post('/login', (req, res) => {
  const log = getRequestLogger();
  log.info('Login attempt');
  log.error('Invalid password');
  // All of these are stored with the same request_id
  res.json({ ok: false });
});

Logger methods: .log(), .info(), .warn(), .error(). Each accepts a message string and an optional metadata object:

log.info('User action', { actionId: 42 });

You must call getRequestLogger() inside the route (or middleware that runs after requestLogger). Do not call it at module level—that runs before any request and returns a no-op logger, so nothing is stored:

// ❌ Wrong – logger is captured once at startup, no request context
const logger = getRequestLogger();
app.get('/', (req, res) => {
  logger.info('Hello');  // Not stored; logs to console only
  res.send('OK');
});

// ✅ Right – get the logger inside the handler
app.get('/', (req, res) => {
  const logger = getRequestLogger();
  logger.info('Hello');  // Stored and visible in Lazylog Studio
  res.send('OK');
});

If called outside a request (e.g. in a cron job), getRequestLogger() returns a logger that only writes to the console (no DB).

3. Add context

Attach extra fields to every subsequent log for that request:

const log = getRequestLogger();
log.addContext({ userId: 123, email: '[email protected]' });
log.info('User action'); // stored with userId and email in context

4. Retrieve logs by request

Use the stored data in your app or a simple admin route:

const { getLogsByRequestId, getRequest } = require('lazylog-trace');

// All log entries for a request
const logs = getLogsByRequestId(requestId);

// Request row plus its logs
const data = getRequest(requestId);
// data.request: { id, method, path, body, response, response_status, started_at, finished_at }
// data.logs: array of { id, request_id, level, message, context, created_at }

Storage is the one from the last-configured requestLogger() middleware. If the middleware has never been mounted, getLogsByRequestId returns [] and getRequest returns null.

Storage schema (SQLite)

• requests: id (UUID), method, path, body (JSON/text), response (text), response_status (int), started_at, finished_at.
• logs: id, request_id (FK to requests), level, message, context (JSON), created_at.

Index on logs.request_id for fast lookups.

Best practices

• Use getRequestLogger() for request-scoped logs instead of console.log, so everything is tied to the request and stored.
• Use ignorePaths for health checks or noisy endpoints you don’t need to log.
• Use addContext() after auth so every log for that request includes user id or email.

Publishing to npm

Before publishing:

1. Set repo URLs in package.json: replace YOUR_USERNAME in repository, bugs, and homepage with your GitHub username (or org).
2. Set author in package.json, e.g. "author": "Your Name <[email protected]>" or "author": "https://github.com/YOUR_USERNAME".
3. Check the package name: lazylog-trace may be taken on npm. Use npm search lazylog-trace or pick a scoped name, e.g. @yourusername/lazylog-trace.
4. Log in: npm login
5. Dry run: npm publish --dry-run to see what will be published (only src/, README.md, and LICENSE are included via the files field).
6. Publish: npm publish (or npm publish --access public if using a scoped package like @yourusername/lazylog-trace).