Express middleware that instruments your API and provides a configurable metrics dashboard.
npm install metrexExpress middleware that instruments your API and exposes a route with a lightweight metrics dashboard (RPS, latencies, status codes, and top routes). No runtime dependencies, only express as a peer dependency.
``bash`
npm install metrex
`js
const express = require('express');
const { useMetrex } = require('metrex');
const app = express();
// Globally instrument and mount the dashboard at /metrex
// Returns helper methods for custom metrics
const metrex = useMetrex(app, { routePath: '/metrex' });
app.get('/hello', (req, res) => res.json({ ok: true }));
app.post('/buy', (req, res) => {
// Business logic...
// Example: Increment a custom counter
metrex.counter('items_sold', 1, 'Total items sold');
// Example: Set a gauge value
metrex.gauge('queue_size', 5, 'Items currently in queue');
res.json({ ok: true });
});
app.listen(3000, () => {
console.log('Metrex at http://localhost:3000/metrex');
});
`
Open http://localhost:3000/metrex to view the dashboard.
- GET {routePath}: HTML dashboard.GET {routePath}/data
- : JSON with aggregated metrics.GET {routePath}/metrics
- : Prometheus text format exporter.
Metrex allows you to track your own application metrics alongside standard HTTP metrics.
`js
const metrex = useMetrex(app);
// Counter: Value that only goes up (e.g. total errors, tasks completed)
metrex.counter('my_counter_name', 1, 'Description of metric');
// Gauge: Value that can go up and down (e.g. queue size, cache size)
metrex.gauge('my_gauge_name', 120, 'Description of metric');
`
These metrics will appear automatically in the Dashboard and the Prometheus exporter.
- routePath (string): base path for the dashboard. Default /metrex.historySize
- (number): number of events to retain in memory (default 2000).shouldTrack(req)
- (function): filter function; return false to not count a request.excludePaths
- (string[] | RegExp[]): paths to exclude from instrumentation.slowThreshold
- (number): threshold in ms to mark slow requests (default 1000ms).cpuThreshold
- (number): percentage (0-100) to trigger CPU alerts (default 90).onAlert
- (function): callback for alerts.auth
- (object): Basic auth credentials for the dashboard.username
- (string)password
- (string)
`js`
useMetrex(app, {
routePath: '/metrex',
auth: {
username: 'admin',
password: 'supersecretpassword',
},
});
Metrex can trigger a callback when it detects issues, allowing you to integrate with Telegram, Slack, etc.
`js
useMetrex(app, {
slowThreshold: 2000, // Alert if request takes > 2s
cpuThreshold: 80, // Alert if CPU > 80%
onAlert: (event) => {
// event = { type: 'error' | 'latency' | 'cpu', value: number, msg: string, timestamp: number }
console.warn('ALERT:', event.msg);
// Example: Send to Telegram
// fetch(https://api.telegram.org/bot);`
},
});
Triggers:
- Error: HTTP 5xx responses.
- Latency: Requests taking longer than slowThreshold.cpuThreshold
- CPU: Usage exceeds (debounced to once per minute).
- Mount it before your business routes: app.use(metrex()) at the beginning to capture all requests.excludePaths
- If you have sensitive paths, exclude them with .: JSON with aggregated metrics.
- FGET {routePath}/data
``bash``
npm run exampleopen http://localhost:3000/metrex
See CONTRIBUTING.md for guidelines.
See SECURITY.md for security policy.
ISC