What is express-prom-bundle?
The express-prom-bundle package is a middleware for Express.js that integrates Prometheus metrics collection and reporting. It allows you to easily monitor the performance and health of your Express applications by exposing various metrics that Prometheus can scrape.
What are express-prom-bundle's main functionalities?
Basic Setup
This code demonstrates the basic setup of express-prom-bundle in an Express application. It initializes the middleware and includes it in the app, which will start collecting and exposing metrics.
const express = require('express');
const promBundle = require('express-prom-bundle');
const app = express();
const metricsMiddleware = promBundle({ includeMethod: true });
app.use(metricsMiddleware);
app.get('/', (req, res) => {
res.send('Hello World!');
});
app.listen(3000, () => {
console.log('Server is running on port 3000');
});
Custom Metrics
This code demonstrates how to create and use custom metrics with express-prom-bundle. It shows how to define a custom counter and increment it in a route handler.
const express = require('express');
const promBundle = require('express-prom-bundle');
const promClient = require('prom-client');
const app = express();
const metricsMiddleware = promBundle({ includeMethod: true });
app.use(metricsMiddleware);
const customCounter = new promClient.Counter({
name: 'custom_counter',
help: 'Example of a custom counter',
});
app.get('/increment', (req, res) => {
customCounter.inc();
res.send('Counter incremented');
});
app.listen(3000, () => {
console.log('Server is running on port 3000');
});
Custom Metrics Endpoint
This code demonstrates how to customize the endpoint where Prometheus metrics are exposed. By setting the `metricsPath` option, you can change the default `/metrics` endpoint to a custom path.
const express = require('express');
const promBundle = require('express-prom-bundle');
const app = express();
const metricsMiddleware = promBundle({ includeMethod: true, metricsPath: '/custom-metrics' });
app.use(metricsMiddleware);
app.get('/', (req, res) => {
res.send('Hello World!');
});
app.listen(3000, () => {
console.log('Server is running on port 3000');
});
Other packages similar to express-prom-bundle
prom-client
prom-client is a Prometheus client for Node.js that allows you to create and expose custom metrics. Unlike express-prom-bundle, it does not provide middleware for Express, so you need to manually integrate it into your application.
express-status-monitor
express-status-monitor is a simple, self-hosted module based on Socket.io and Chart.js to report realtime server metrics for Express-based applications. It provides a web-based dashboard for monitoring but does not integrate with Prometheus.
express prometheus bundle
Express middleware with popular prometheus metrics in one bundle. It's also compatible with koa v1 (see below).
Internally it uses prom-client. See: https://github.com/siimon/prom-client
Included metrics:
up
: normally is just 1nodejs_memory_heap_total_bytes
and nodejs_memory_heap_used_bytes
http_request_seconds
: http latency histogram labeled with status_code
Install
npm install express-prom-bundle
Usage
const promBundle = require("express-prom-bundle"),
metricsMiddleware = promBundle({ }),
app = require("express")();
app.use(metricsMiddleware);
app.use();
app.listen(3000);
ALERT!
The order in wich the routes are registered is important, since
only the routes registered after the express-prom-bundle will be measured
You can use this to your advantage to bypass some of the routes.
See the example below.
Options
- prefix: prefix added to every metric name
- whitelist, blacklist: array of strings or regexp specifying which metrics to include/exclude
- buckets: buckets used for
http_request_seconds
histogram - includeMethod: include HTTP method (GET, PUT, ...) as a label to
http_request_seconds
- includePath: include URL path as a label - EXPERIMENTAL! (see below)
- normalizePath: boolean or
function(req)
- path normalization for includePath
option - excludeRoutes: array of strings or regexp specifying which routes should be skipped for
http_request_seconds
metric. It uses req.path
as subject when checking - autoregister: if
/metrics
endpoint should be registered. It is (Default: true) - keepDefaultMetrics: if default metrics provided by prom-client should be probed and delivered. (Default: false)
includePath option
The goal is to have separate latency statistics by URL path, e.g. /my-app/user/
, /products/by-category
etc.
But just taking req.path
as a label value won't work as IDs are often part of the URL, like /user/12352/profile
. So what we actually need is a path template. The automatically module tries to figure out what parts of the path are values or IDs, and what is an actual path. The example mentioned before would be normalized to /user/#val/profile
and that will become the value for the label.
You can override this magical behavior and create define your own function by providing an optional callback normalizePath.
For more details:
express example
setup std. metrics but exclude up
-metric:
"use strict";
const express = require("express"),
app = express(),
promBundle = require("express-prom-bundle");
app.get("/status", (req, res) => res.send("i am healthy"));
app.use(promBundle({
prefix: "demo_app:something",
excludeRoutes: ["/foo"]
}));
app.get("/foo", (req, res) => res.send("bar"));
app.get("/hello", (req, res) => res.send("ok"));
app.listen(3000);
See an advanced example on github
koa v1 example
const promBundle = require("express-prom-bundle"),
koa = require("koa"),
c2k = require("koa-connect"),
metricsMiddleware = promBundle({ });
const app = koa();
app.use(c2k(metricsMiddleware));
app.use();
app.listen(3000);
Changelog
- 1.2.1
- upgrade prom-client to 6.1.2
- add options: includeMethod, includePath, keepDefaultMetrics
License
MIT