@quark-fw/plugin-metrics 0.0.0-stage → 0.1.27

package/README.md

@@ -1,3 +1,29 @@
-# Temporary Holding Version
+# @quark-fw/plugin-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.
+`GET /metrics` in Prometheus format for Quark apps: Node process defaults (CPU, memory, event loop lag, GC) and `http_request_duration_seconds` per `method` / `route` / `status` for every request the app serves (SSR pages, tRPC, static).
+
+## Install
+
+```sh
+npm i @quark-fw/plugin-metrics
+```
+
+## Usage
+
+```ts
+import "@quark-fw/plugin-metrics"; // provides quark.metrics.registry and GET /metrics
+
+// register your own metrics in the same registry
+import { Counter } from "prom-client";
+const imports = new Counter({
+  name: "jira_imports_total",
+  help: "Jira imports",
+  registers: [quark.metrics.registry],
+});
+```
+
+Route labels are bounded on purpose: `/api/trpc/<proc>` becomes `trpc:<first procedure>`, other paths collapse to their first segment (`/projects/123` → `/projects`) and 404s to `(unmatched)` — raw URLs would create a series per id.
+
+Env: `METRICS_TOKEN` — when set, `/metrics` requires `Authorization: Bearer <token>`; leave unset only when the scraper reaches the app over a private network.
+
+Part of the [Quark framework](https://www.npmjs.com/package/@quark-fw/core).

package/package.json

@@ -1,6 +1,37 @@
 {
-  "name": "@quark-fw/plugin-metrics",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@quark-fw/plugin-metrics",
+	"version": "0.1.27",
+	"main": "src/index.ts",
+	"types": "src/index.ts",
+	"type": "module",
+	"scripts": {
+		"build": "echo raw-src package, no build",
+		"test": "vitest run"
+	},
+	"files": [
+		"src"
+	],
+	"keywords": [
+		"quark",
+		"metrics",
+		"prometheus"
+	],
+	"author": "",
+	"license": "ISC",
+	"description": "Prometheus metrics for the Quark framework: GET /metrics with process defaults and HTTP request duration per route (published as raw TS sources; consumers run tsx)",
+	"publishConfig": {
+		"access": "public"
+	},
+	"dependencies": {
+		"@quark-fw/plugin": "0.1.27",
+		"express": "^5.2.1",
+		"prom-client": "^15.1.3"
+	},
+	"peerDependencies": {
+		"@quark-fw/core": "0.1.27"
+	},
+	"devDependencies": {
+		"@types/express": "^5.0.6",
+		"vitest": "^5.0.0"
+	}
+}

package/src/createHttpMetricsMiddleware.ts

@@ -0,0 +1,39 @@
+import type { RequestHandler } from "express";
+import { Histogram, type Registry } from "prom-client";
+import { routeLabel } from "./helpers.js";
+
+/**
+ * Гистограмма длительности HTTP-запросов по методу, маршруту и статусу.
+ * Ставится до роутеров плагинов (preRouter), чтобы считать и SSR, и API,
+ * и статику. _count гистограммы даёт и число запросов — отдельный счётчик
+ * не нужен.
+ */
+export function createHttpMetricsMiddleware(
+	registry: Registry,
+): RequestHandler {
+	const duration = new Histogram({
+		name: "http_request_duration_seconds",
+		help: "Длительность HTTP-запросов",
+		labelNames: ["method", "route", "status"] as const,
+		// от 5 мс (статика) до 10 с (зависший SSR)
+		buckets: [0.005, 0.02, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10],
+		registers: [registry],
+	});
+
+	return (req, res, next) => {
+		const started = process.hrtime.bigint();
+		res.on("finish", () => {
+			const seconds =
+				Number(process.hrtime.bigint() - started) / 1_000_000_000;
+			duration.observe(
+				{
+					method: req.method,
+					route: routeLabel(req.originalUrl, res.statusCode),
+					status: String(res.statusCode),
+				},
+				seconds,
+			);
+		});
+		next();
+	};
+}

package/src/createMetricsHandler.ts

@@ -0,0 +1,33 @@
+import type { RequestHandler } from "express";
+import type { Registry } from "prom-client";
+
+/**
+ * GET /metrics в формате Prometheus. С METRICS_TOKEN отдаётся только по
+ * `Authorization: Bearer <token>`: метрики раскрывают версии, пути и
+ * нагрузку, а приложение обычно смотрит в интернет. Без токена — открыто,
+ * для скрейпа из внутренней сети.
+ */
+export function createMetricsHandler(
+	registry: Registry,
+	token: string | undefined,
+): RequestHandler {
+	return (req, res) => {
+		if (req.method !== "GET" && req.method !== "HEAD") {
+			res.status(405).end();
+			return;
+		}
+		if (token && req.headers.authorization !== `Bearer ${token}`) {
+			res.status(401).end();
+			return;
+		}
+		void registry.metrics().then(
+			(body) => {
+				res.setHeader("content-type", registry.contentType);
+				res.end(body);
+			},
+			(error: unknown) => {
+				res.status(500).end(String(error));
+			},
+		);
+	};
+}

package/src/global.d.ts

@@ -0,0 +1,13 @@
+import "@quark-fw/core/src/global.d.ts";
+import type { Registry } from "prom-client";
+
+export {};
+
+declare global {
+	interface Quark {
+		metrics: {
+			/** реестр prom-client: приложение регистрирует в нём свои метрики */
+			registry: Registry;
+		};
+	}
+}

package/src/helpers.ts

@@ -0,0 +1,16 @@
+// Хелперы plugin-metrics: метка маршрута.
+
+/**
+ * Метка route для метрик HTTP. Сырой URL в метку класть нельзя: каждый id
+ * в пути — новая серия, и Prometheus захлёбывается. Поэтому:
+ * - /api/trpc/<proc>[,<proc>…] → trpc:<первая процедура>;
+ * - 404 → (unmatched): боты перебирают /wp-admin, /.env и т.п.;
+ * - остальное → первый сегмент пути (/projects/123 → /projects).
+ */
+export function routeLabel(path: string, status: number): string {
+	if (status === 404) return "(unmatched)";
+	const trpc = path.match(/^\/api\/trpc\/([^/?,]+)/);
+	if (trpc) return `trpc:${trpc[1]}`;
+	const segment = path.split("?")[0]!.split("/")[1] ?? "";
+	return segment ? `/${segment}` : "/";
+}

package/src/index.ts

@@ -0,0 +1,43 @@
+import { QuarkPlugin } from "@quark-fw/plugin";
+import {
+	registerHttpMiddleware,
+	registerHttpPreMiddleware,
+} from "@quark-fw/plugin/http.js";
+import { Registry, collectDefaultMetrics } from "prom-client";
+import {} from "@quark-fw/plugin-metrics/src/global.js";
+import { createHttpMetricsMiddleware } from "./createHttpMetricsMiddleware.js";
+import { createMetricsHandler } from "./createMetricsHandler.js";
+
+export { routeLabel } from "./helpers.js";
+
+/**
+ * GET /metrics (Prometheus): метрики процесса Node (CPU, память, event loop,
+ * GC) и http_request_duration_seconds по method/route/status. Свои метрики
+ * приложение регистрирует в quark.metrics.registry. METRICS_TOKEN закрывает
+ * эндпоинт bearer-токеном.
+ */
+await quark.registerPlugin({
+	name: "metrics",
+	extend(quark) {
+		// свой реестр, а не глобальный prom-client: тесты и воркеры threads
+		// в одном процессе не должны делить и дублировать метрики
+		const registry = new Registry();
+		collectDefaultMetrics({ register: registry });
+		quark.metrics = { registry };
+	},
+	onInit(quark) {
+		registerHttpPreMiddleware(
+			createHttpMetricsMiddleware(quark.metrics.registry),
+		);
+		registerHttpMiddleware(
+			"/metrics",
+			createMetricsHandler(
+				quark.metrics.registry,
+				process.env.METRICS_TOKEN || undefined,
+			),
+		);
+	},
+	onDestroy(quark) {
+		quark.metrics.registry.clear();
+	},
+} satisfies QuarkPlugin);

package/src/metrics.test.ts

@@ -0,0 +1,55 @@
+import { afterAll, beforeAll, expect, test } from "vitest";
+import express from "express";
+import type { Server } from "node:http";
+import type { AddressInfo } from "node:net";
+import { Registry } from "prom-client";
+import { createHttpMetricsMiddleware } from "./createHttpMetricsMiddleware.js";
+import { createMetricsHandler } from "./createMetricsHandler.js";
+import { routeLabel } from "./helpers.js";
+
+test("routeLabel: процедура tRPC, первый сегмент, 404 схлопывается", () => {
+	expect(routeLabel("/api/trpc/entity.task.list?batch=1", 200)).toBe(
+		"trpc:entity.task.list",
+	);
+	expect(routeLabel("/api/trpc/a.b,c.d?batch=1", 200)).toBe("trpc:a.b");
+	expect(routeLabel("/projects/01a1-uuid?x=1", 200)).toBe("/projects");
+	expect(routeLabel("/", 200)).toBe("/");
+	expect(routeLabel("/wp-admin/setup.php", 404)).toBe("(unmatched)");
+});
+
+let server: Server;
+let base: string;
+const registry = new Registry();
+
+beforeAll(async () => {
+	const app = express();
+	app.use(createHttpMetricsMiddleware(registry));
+	app.get("/projects/:id", (_req, res) => res.send("ok"));
+	app.use("/metrics", createMetricsHandler(registry, "s3cret"));
+	await new Promise<void>((resolve) => {
+		server = app.listen(0, () => resolve());
+	});
+	base = `http://127.0.0.1:${(server.address() as AddressInfo).port}`;
+});
+
+afterAll(() => server.close());
+
+test("запросы попадают в гистограмму по route/status; /metrics под токеном", async () => {
+	await fetch(`${base}/projects/1`);
+	await fetch(`${base}/projects/2`);
+	await fetch(`${base}/nope`);
+
+	expect((await fetch(`${base}/metrics`)).status).toBe(401);
+	const r = await fetch(`${base}/metrics`, {
+		headers: { authorization: "Bearer s3cret" },
+	});
+	expect(r.status).toBe(200);
+	expect(r.headers.get("content-type")).toContain("text/plain");
+	const body = await r.text();
+	expect(body).toContain(
+		'http_request_duration_seconds_count{method="GET",route="/projects",status="200"} 2',
+	);
+	expect(body).toContain(
+		'http_request_duration_seconds_count{method="GET",route="(unmatched)",status="404"} 1',
+	);
+});