Elysia Prometheus Plugin

A lightweight plugin for Elysia that exposes HTTP metrics for Prometheus using prom-client. Automatically tracks request count, duration, method, status code, and more — with support for custom labels.

Features

• ✅ Exposes /metrics endpoint (configurable)
• 📊 Collects request duration and total request count
• 🏷 Supports static and dynamic labels
• 🧠 Route normalization for consistent metric names
• 🪝 Integrates with derive and onAfterHandle lifecycle hooks

Installation

bun install elysia-prometheus

Usage

import { sleep } from 'bun'
import { Elysia, error } from 'elysia'
import prometheusPlugin from 'elysia-prometheus'

const app = new Elysia()
	.use(
		prometheusPlugin({
			metricsPath: '/metrics',
			staticLabels: { service: 'my-app' },
			dynamicLabels: {
				userAgent: (ctx) =>
					ctx.request.headers.get('user-agent') ?? 'unknown'
			}
		})
	)
	.get('/', () => 'GET /')
	.post('/', () => 'POST /')
	.get('/delay', () => {
		sleep(1000)
		return 'GET /delay'
	})
	.get('/error/:code', ({ params }) => {
		return error(Number.parseInt(params.code))
	})
	.listen(3000)

Custom metric prefix

Pass a metricPrefix to namespace every metric (HTTP metrics and the default Node.js process metrics). A trailing underscore is added automatically when omitted:

prometheusPlugin({
	metricPrefix: 'myapp' // or 'myapp_' — both produce the same output
})

With the prefix above, you'll see metrics like:

• myapp_http_requests_total
• myapp_http_request_duration_seconds
• myapp_process_cpu_user_seconds_total
• …and so on.

Metrics Exposed

HTTP metrics:

• http_requests_total — Counter of total HTTP requests. Labels: method, path, status + custom.

• http_request_duration_seconds — Histogram of request durations in seconds. Labels: method, path, status + custom.

• http_requests_in_flight — Gauge of requests currently being handled. Labels: method + custom.

• http_request_size_bytes — Histogram of request body sizes in bytes (derived from the Content-Length header; skipped when absent). Labels: method, path + custom.

• http_response_size_bytes — Histogram of response body sizes in bytes (best-effort: uses Content-Length from ctx.set.headers or the returned Response, otherwise the byte length of string / ArrayBuffer / TypedArray bodies; streams and other shapes are skipped). Labels: method, path, status + custom.

• http_requests_errors_total — Counter of requests that finished with a status >= 400. Labels: method, path, status, status_class (4xx / 5xx) + custom.

• http_exceptions_total — Counter of unhandled exceptions captured in Elysia's onError hook. Labels: method, path, error (Elysia error code or Error.name) + custom.

• http_route_info — Info-style gauge (always 1) emitted the first time each method + path combination is observed. Labels: method, path + static labels.

• Node.js process metrics (CPU, memory, GC, event-loop lag, etc.) collected via prom-client's collectDefaultMetrics.

Default Labels

• method – HTTP method (GET, POST, etc.)

• path – Normalized route path (e.g., /users/:id)

• status – HTTP status code (200, 404, etc.)

• status_class – Status-code class bucket (4xx, 5xx) — used on http_requests_errors_total.

• error – Error code / name — used on http_exceptions_total.

Custom Labels

• staticLabels: Adds the same label value for every request

• dynamicLabels: Functions that extract values from each request context

Plugin Options

Option	Type	Default	Description
metricsPath	string	"/metrics"	URL path to expose metrics
metricPrefix	string	""	Prefix prepended to every metric name, including the default Node.js process metrics. A trailing _ is appended automatically if you don't include one (e.g. "myapp" and "myapp_" both yield myapp_http_requests_total).
durationBuckets	number[]	[0.003, 0.03, 0.1, 0.3, 1.5, 10]	Histogram buckets for request duration
sizeBuckets	number[]	[64, 256, 1024, 4096, 16384, 65536, 262144, 1048576, 5242880]	Histogram buckets (bytes) for request/response size
staticLabels	Record<string, string>	{}	Static labels added to all metrics
dynamicLabels	Record<string, (ctx: Context) => string>	{}	Dynamic labels based on request context
useRoutePath	boolean	true	Use route pattern instead of raw URL (e.g. /users/:id instead of /users/123)

⚠️ Label names method, path, status, status_class, and error are reserved and cannot be overridden.

Route Normalization

The plugin automatically normalizes paths like:

/users/123/orders/456 → /users/:id/orders/:id

This prevents metric explosion from unique IDs in URLs.

License

MIT

Contributing

If you want to add or improve the library or its documentation, make a pull request to this repository. Please use bun and format js and ts code with prettier to make everything look nice.