@viktorbarzin/metrics 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,40 @@
-# Temporary Holding Version
+# @viktorbarzin/metrics
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Prometheus metrics for an app: one prom-client registry per process with the
+default process metrics, the HTTP request metrics every app exports, and
+`/metrics` on a port of its own that the ingress never routes (point the
+pod's `prometheus.io/port` annotation at it).
+
+<!-- typecheck-preamble
+declare const request: Request;
+declare const response: Response;
+-->
+```ts
+import { getLogger } from "@viktorbarzin/log";
+import { createHandlerLabeler, getRegistry, observeRequest, parseMetricsPort, startMetricsServer } from "@viktorbarzin/metrics";
+import { Counter } from "prom-client";
+
+// at boot (Bun)
+const metrics = startMetricsServer({ port: parseMetricsPort(process.env.METRICS_PORT) });
+
+// request middleware
+const label = createHandlerLabeler({ known: ["/api/items", "/healthz"] });
+const done = observeRequest(request, { label, accessLog: getLogger("myapp.http") });
+// ... handle ...
+done(response.status);
+
+// app metrics
+new Counter({ name: "myapp_things_total", help: "...", registers: [getRegistry()] });
+```
+
+| Export | |
+|---|---|
+| `getRegistry()` | the process registry, with `collectDefaultMetrics` |
+| `httpMetrics()` | `http_requests_total{method,handler,status}` (status as `2xx`), `http_request_duration_seconds{method,handler}` |
+| `createHandlerLabeler({ known, buckets? })` | known paths by name; default buckets `/api/auth/` → `/api/auth`, `/api/` → `/api/other`, `/_serverFn/` → `/_serverFn`, else `page` |
+| `observeRequest(request, { label, accessLog?, accessLogPrefix? })` | raises the idle timeout, tracks the request, returns `done(status)` that records the metrics and one access-log line `{method, path, status, duration_ms}` under the prefix (default `/api/`) |
+| `metricsResponse(registry?)` | the text format |
+| `parseMetricsPort(raw)` | a port or null (ERROR logged for junk) |
+| `startMetricsServer({ port, hostname?, registry? })` | `Bun.serve` answering `/metrics` only; null without a port |
+
+Peers: `prom-client` ^15.1, `@viktorbarzin/log`, `@viktorbarzin/runtime`.

package/dist/index.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Prometheus metrics for an app: one prom-client registry per process (with
+ * the default process metrics), the HTTP request metrics every app exports,
+ * and /metrics on its own port, which the ingress never routes. The pod's
+ * `prometheus.io/*` annotations point at that port.
+ *
+ * App-specific metrics are registered by the app on getRegistry().
+ */
+import { type Logger } from "@viktorbarzin/log";
+import { type Counter, type Histogram, type Registry } from "prom-client";
+/** The process registry, created once with the default metrics. */
+export declare function getRegistry(): Registry;
+export interface HttpMetrics {
+    requestsTotal: Counter<"method" | "handler" | "status">;
+    requestDuration: Histogram<"method" | "handler">;
+}
+export declare const HTTP_DURATION_BUCKETS: number[];
+/** http_requests_total and http_request_duration_seconds on the process registry. */
+export declare function httpMetrics(): HttpMetrics;
+export declare const DEFAULT_HANDLER_BUCKETS: ReadonlyArray<readonly [prefix: string, label: string]>;
+/**
+ * The `handler` label: known paths by name, everything else folded into a few
+ * prefix buckets (first match wins) or "page", so the label set stays small.
+ */
+export declare function createHandlerLabeler(opts: {
+    known: readonly string[];
+    buckets?: ReadonlyArray<readonly [prefix: string, label: string]>;
+}): (pathname: string) => string;
+/**
+ * Start observing one request: raises Bun's idle timeout, counts it as in
+ * flight, and returns a function to call with the final status. That records
+ * the counter (status as "2xx" etc.), the histogram and, for paths under
+ * `accessLogPrefix`, one access-log line {method, path, status, duration_ms}.
+ */
+export declare function observeRequest(request: Request, opts: {
+    label: (pathname: string) => string;
+    accessLog?: Logger;
+    accessLogPrefix?: string;
+}): (status: number) => void;
+export declare function metricsResponse(registry?: Registry): Promise<Response>;
+/** METRICS_PORT as a port number; null when unset or not a port (logged as ERROR). */
+export declare function parseMetricsPort(raw: string | undefined): number | null;
+export interface MetricsServer {
+    port: number;
+    stop(): void;
+}
+/** Serve /metrics (and nothing else) on its own Bun listener; null without a port. */
+export declare function startMetricsServer(opts: {
+    port: number | null;
+    hostname?: string;
+    registry?: Registry;
+}): MetricsServer | null;

package/dist/index.js

@@ -0,0 +1,144 @@
+/**
+ * Prometheus metrics for an app: one prom-client registry per process (with
+ * the default process metrics), the HTTP request metrics every app exports,
+ * and /metrics on its own port, which the ingress never routes. The pod's
+ * `prometheus.io/*` annotations point at that port.
+ *
+ * App-specific metrics are registered by the app on getRegistry().
+ */
+import { getLogger } from "@viktorbarzin/log";
+import { extendIdleTimeout, processSingleton, trackRequest, } from "@viktorbarzin/runtime";
+import client, {} from "prom-client";
+const log = getLogger("metrics");
+/** The process registry, created once with the default metrics. */
+export function getRegistry() {
+    return processSingleton("metrics.registry", () => {
+        const registry = new client.Registry();
+        client.collectDefaultMetrics({ register: registry });
+        return registry;
+    });
+}
+export const HTTP_DURATION_BUCKETS = [
+    0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10,
+];
+/** http_requests_total and http_request_duration_seconds on the process registry. */
+export function httpMetrics() {
+    return processSingleton("metrics.http", () => {
+        const registry = getRegistry();
+        return {
+            requestsTotal: new client.Counter({
+                name: "http_requests_total",
+                help: "HTTP requests handled by the app server.",
+                labelNames: ["method", "handler", "status"],
+                registers: [registry],
+            }),
+            requestDuration: new client.Histogram({
+                name: "http_request_duration_seconds",
+                help: "HTTP request latency in seconds.",
+                labelNames: ["method", "handler"],
+                buckets: HTTP_DURATION_BUCKETS,
+                registers: [registry],
+            }),
+        };
+    });
+}
+export const DEFAULT_HANDLER_BUCKETS = [
+    ["/api/auth/", "/api/auth"],
+    ["/api/", "/api/other"],
+    ["/_serverFn/", "/_serverFn"],
+];
+/**
+ * The `handler` label: known paths by name, everything else folded into a few
+ * prefix buckets (first match wins) or "page", so the label set stays small.
+ */
+export function createHandlerLabeler(opts) {
+    const known = new Set(opts.known);
+    const buckets = opts.buckets ?? DEFAULT_HANDLER_BUCKETS;
+    return (pathname) => {
+        if (known.has(pathname))
+            return pathname;
+        for (const [prefix, label] of buckets)
+            if (pathname.startsWith(prefix))
+                return label;
+        return "page";
+    };
+}
+/**
+ * Start observing one request: raises Bun's idle timeout, counts it as in
+ * flight, and returns a function to call with the final status. That records
+ * the counter (status as "2xx" etc.), the histogram and, for paths under
+ * `accessLogPrefix`, one access-log line {method, path, status, duration_ms}.
+ */
+export function observeRequest(request, opts) {
+    extendIdleTimeout(request);
+    const untrack = trackRequest();
+    const started = performance.now();
+    const { pathname } = new URL(request.url);
+    const prefix = opts.accessLogPrefix ?? "/api/";
+    let recorded = false;
+    return (status) => {
+        if (recorded)
+            return;
+        recorded = true;
+        untrack();
+        const seconds = (performance.now() - started) / 1000;
+        const handler = opts.label(pathname);
+        const metrics = httpMetrics();
+        metrics.requestsTotal.inc({
+            method: request.method,
+            handler,
+            status: `${Math.floor(status / 100)}xx`,
+        });
+        metrics.requestDuration.observe({ method: request.method, handler }, seconds);
+        if (opts.accessLog && pathname.startsWith(prefix)) {
+            opts.accessLog.info("request", {
+                method: request.method,
+                path: pathname,
+                status,
+                duration_ms: Math.round(seconds * 1000),
+            });
+        }
+    };
+}
+export async function metricsResponse(registry = getRegistry()) {
+    return new Response(await registry.metrics(), {
+        headers: { "content-type": registry.contentType },
+    });
+}
+/** METRICS_PORT as a port number; null when unset or not a port (logged as ERROR). */
+export function parseMetricsPort(raw) {
+    if (raw === undefined || raw.trim() === "")
+        return null;
+    const port = Number(raw);
+    if (!Number.isInteger(port) || port < 0 || port > 65_535) {
+        log.error("METRICS_PORT is not a port; metrics are not served", {
+            value: raw,
+        });
+        return null;
+    }
+    return port;
+}
+/** Serve /metrics (and nothing else) on its own Bun listener; null without a port. */
+export function startMetricsServer(opts) {
+    if (opts.port === null)
+        return null;
+    const registry = opts.registry ?? getRegistry();
+    try {
+        const server = Bun.serve({
+            hostname: opts.hostname ?? "0.0.0.0",
+            port: opts.port,
+            fetch: (request) => new URL(request.url).pathname === "/metrics"
+                ? metricsResponse(registry)
+                : new Response("not found\n", { status: 404 }),
+        });
+        log.info("metrics listening", { port: server.port });
+        return {
+            port: server.port,
+            stop: () => void server.stop(true),
+        };
+    }
+    catch (err) {
+        log.exception("metrics server failed to start", err, { port: opts.port });
+        return null;
+    }
+}

package/package.json

@@ -1,6 +1,46 @@
 {
-  "name": "@viktorbarzin/metrics",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@viktorbarzin/metrics",
+	"version": "1.0.0",
+	"description": "One prom-client registry per process, HTTP request metrics and a /metrics listener on its own port.",
+	"license": "MIT",
+	"type": "module",
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"default": "./dist/index.js"
+		}
+	},
+	"files": [
+		"dist"
+	],
+	"sideEffects": false,
+	"engines": {
+		"bun": ">=1.4.3"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/ViktorBarzin/app-kit.git",
+		"directory": "packages/metrics"
+	},
+	"homepage": "https://github.com/ViktorBarzin/app-kit/tree/master/packages/metrics#readme",
+	"publishConfig": {
+		"access": "public",
+		"provenance": true
+	},
+	"scripts": {
+		"build": "tsc -b",
+		"test": "bun test"
+	},
+	"peerDependencies": {
+		"@viktorbarzin/log": "^1.0.0",
+		"@viktorbarzin/runtime": "^1.0.0",
+		"prom-client": "^15.1.0"
+	},
+	"devDependencies": {
+		"@viktorbarzin/log": "^1.0.0",
+		"@viktorbarzin/runtime": "^1.0.0",
+		"prom-client": "^15.1.3"
+	}
+}