BuntokBuntok

Metrics#

Request metrics collector with Prometheus export. Tracks request count, duration, errors, and in-flight requests.

typescript
import { Metrics, metricsEndpoint, metricsMiddleware } from "@buntok/core/metrics";

Setup#

typescript
import { Buntok } from "@buntok/core";
import { Metrics, metricsEndpoint, metricsMiddleware } from "@buntok/core/metrics";

const app = new Buntok();
const metrics = new Metrics();

// Add middleware to record all requests
app.use(metricsMiddleware(metrics));

// Register /metrics endpoint for Prometheus scraping
metricsEndpoint(metrics, "/metrics");  // default: "/metrics"

app.listen(1212);

Read Metrics#

typescript
const snapshot = metrics.read();

console.log(snapshot.requests);        // total requests
console.log(snapshot.errors);         // total errors
console.log(snapshot.inFlight);       // currently in-flight
console.log(snapshot.totalDurationMs); // total duration across all requests

// Per-route breakdown
console.log(snapshot.byRoute);
// {
//   "GET /users": { count: 150, avgDurationMs: 12.5, p99Ms: 45.2 },
//   "POST /users": { count: 30, avgDurationMs: 25.1, p99Ms: 89.3 },
// }

// Per-status-class breakdown
console.log(snapshot.byStatusClass);
// { "2xx": 150, "4xx": 12, "5xx": 3 }

Prometheus Export#

typescript
// Export in Prometheus text format
const prometheus = metrics.toPrometheus();
// # HELP http_requests_total Total HTTP requests
// # TYPE http_requests_total counter
// http_requests_total{method="GET",path="/users",status="200"} 150
// ...

Manual Recording#

If you need to record requests outside of the middleware (e.g., custom handlers):

typescript
app.get("/custom", (ctx) => {
  const end = metrics.start("GET /custom");

  // ... do work ...

  end(200); // record with status code

  return ctx.json({ ok: true });
});

API Reference#

Metrics Class#

MethodDescription
metrics.record(route, statusCode, durationMs)Record a completed request
metrics.start(route)Start timing a request (returns end function)
metrics.read()Get current MetricSnapshot
metrics.toPrometheus()Export in Prometheus text format

Helper Functions#

FunctionDescription
metricsMiddleware(metrics, route?)Middleware that auto-records requests
metricsEndpoint(metrics, path?)Register /metrics endpoint

MetricSnapshot#

typescript
interface MetricSnapshot {
  requests: number;        // total request count
  errors: number;          // total error count (status >= 500)
  inFlight: number;        // currently in-flight requests
  totalDurationMs: number; // total duration across all requests
  byRoute: Record<string, {
    count: number;
    avgDurationMs: number;
    p99Ms: number;
  }>;
  byStatusClass: Record<string, number>; // { "2xx": N, "4xx": N, "5xx": N }
}
PreviousSchedulerNext Helpers