• Synopsis
• Installation
• Usage
• Support
• Contributors
• Stack

Synopsis

Winstan-plugin-express-perf.js is an open source Winstan plugin for Express.js. It logs how long each request took to process.

Mount startTimer once early in the middleware stack. It records the start time immediately and logs the duration when the response finishes — including handlers that send without calling next() (proxies, res.json, error paths, etc.).

• 📦 Only 1 dependency for logging
• 🪶 Very lightweight
• 🧪 Thoroughly tested
• 💻 Works in Javascript and Typescript
• 🌳 Tree-shaking friendly with named exports
• 📝 Written in Typescript

Installation

$ npm i @dwtechs/winstan-plugin-express-perf

Usage

import express from "express";
import { startTimer } from '@dwtechs/winstan-plugin-express-perf';

const app = express();
app.use(express.json());
app.use(startTimer); // mount once, before your routes
app.use("/", route);

That is the full setup. There is no trailing middleware and no endTimer to mount after routers.

The plugin depends on Winstan. You will usually already use Winstan for the rest of your application logs.

Each request produces two log lines at different levels:

| When | Level | Purpose | | :--- | :---: | :------ | | Request enters startTimer | debug | Marks the start. Kept at debug so production (typically info and above) is not flooded with one line per request. | | Response finish | info | Access-style end line with status and duration — the line you keep in production. |

Start (debug):

Request started on GET /gateway/health

Context: { method, path }

End (info):

Request ended on GET /gateway/health 200 in 12ms

Context: { method, path, statusCode, durationMs }

The path is the client-facing pathname from originalUrl without the query string, so tokens or other secrets in ?… never reach the log sink. Aggregators can use the structured context fields instead of parsing the message string.

To see start lines during development, set Winstan's log level to debug.

Support

| Environment | Version | | :---------- | :-----: | | Node.js | >= 22 |

Contributors

Winstan-plugin-express-perf.js is still in development and we would be glad to get all the help you can provide. To contribute please read contributor.md for detailed installation guide.

Stack

| Purpose | Choice | Motivation | | :-------------- | :------------------------------------------: | -------------------------------------------------------------: | | repository | Github | hosting for software development version control using Git | | package manager | npm | default node.js package manager | | language | TypeScript | static type checking along with the latest ECMAScript features | | module bundler | Rollup | advanced module bundler for ES2022 modules | | unit testing | Jest | delightful testing with a focus on simplicity |