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)

Metrics Exposed

• http_requests_total — Counter of total HTTP requests

• http_request_duration_seconds — Histogram of request durations

Default Labels

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

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

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

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
durationBuckets	number[]	[0.003, 0.03, 0.1, 0.3, 1.5, 10]	Histogram buckets for request duration
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, and status 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.