@voltro/plugin-prometheus 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,28 @@
+import { MetricSample } from '@voltro/runtime';
+import { VoltroPlugin } from '@voltro/protocol';
+
+/** Render MetricSample[] to Prometheus text. Samples are grouped by name so
+ *  each family emits exactly one HELP + TYPE header. */
+export declare const formatPrometheus: (samples: ReadonlyArray<MetricSample>) => string;
+
+export declare const processMetrics: (version?: string) => ReadonlyArray<MetricSample>;
+
+export declare const prometheusPlugin: (options?: PrometheusPluginOptions) => VoltroPlugin;
+
+export declare interface PrometheusPluginOptions {
+    /** Scrape path. Default `/metrics`. */
+    readonly path?: string;
+    /** Require `Authorization: Bearer <token>` (Prometheus `bearer_token`).
+     *  Default `PROMETHEUS_TOKEN` env; unset → open (gate at the network layer). */
+    readonly token?: string;
+    /** Include node `process_*` metrics. Default true. */
+    readonly processMetrics?: boolean;
+    /** Value for the `voltro_build_info{version}` gauge. */
+    readonly version?: string;
+    /** Disambiguates multiple plugin instances within one process (suffixes the
+     *  plugin name). Does NOT identify replicas — replica identity comes from
+     *  the Prometheus scrape target (`instance` label). */
+    readonly name?: string;
+}
+
+export { }

package/dist/index.js

@@ -0,0 +1,121 @@
+import { Effect as e } from "effect";
+import { definePlugin as t } from "@voltro/protocol";
+import { checkBearer as n } from "@voltro/protocol/session";
+import { snapshotMetrics as r } from "@voltro/runtime";
+import { pluginEnv as i } from "@voltro/env";
+//#region src/format.ts
+var a = (e) => e.replace(/\\/g, "\\\\").replace(/\n/g, "\\n").replace(/"/g, "\\\""), o = (e, t) => {
+	let n = {
+		...e,
+		...t
+	}, r = Object.keys(n);
+	return r.length === 0 ? "" : "{" + r.map((e) => `${e}="${a(String(n[e]))}"`).join(",") + "}";
+}, s = (e) => Number.isFinite(e) ? String(e) : e > 0 ? "+Inf" : "-Inf", c = {
+	counter: "counter",
+	gauge: "gauge",
+	histogram: "histogram",
+	summary: "summary",
+	frequency: "gauge"
+}, l = (e, t) => {
+	switch (e.type) {
+		case "counter":
+		case "gauge":
+			t.push(`${e.name}${o(e.labels)} ${s(e.value ?? 0)}`);
+			break;
+		case "histogram":
+			for (let n of e.buckets ?? []) t.push(`${e.name}_bucket${o(e.labels, { le: s(n.le) })} ${s(n.count)}`);
+			t.push(`${e.name}_bucket${o(e.labels, { le: "+Inf" })} ${s(e.count ?? 0)}`), t.push(`${e.name}_sum${o(e.labels)} ${s(e.sum ?? 0)}`), t.push(`${e.name}_count${o(e.labels)} ${s(e.count ?? 0)}`);
+			break;
+		case "summary":
+			for (let n of e.quantiles ?? []) t.push(`${e.name}${o(e.labels, { quantile: s(n.quantile) })} ${s(n.value)}`);
+			t.push(`${e.name}_sum${o(e.labels)} ${s(e.sum ?? 0)}`), t.push(`${e.name}_count${o(e.labels)} ${s(e.count ?? 0)}`);
+			break;
+		case "frequency":
+			for (let [n, r] of Object.entries(e.occurrences ?? {})) t.push(`${e.name}${o(e.labels, { bucket: n })} ${s(r)}`);
+			break;
+	}
+}, u = (e) => {
+	let t = /* @__PURE__ */ new Map();
+	for (let n of e) {
+		let e = t.get(n.name);
+		e ? e.push(n) : t.set(n.name, [n]);
+	}
+	let n = [];
+	for (let [e, r] of t) {
+		let t = r[0], i = t.description ?? e;
+		n.push(`# HELP ${e} ${i.replace(/\\/g, "\\\\").replace(/\n/g, " ")}`), n.push(`# TYPE ${e} ${c[t.type]}`);
+		for (let e of r) l(e, n);
+	}
+	return n.join("\n") + "\n";
+}, d = (e) => {
+	let t = process.memoryUsage(), n = process.cpuUsage(), r = [
+		{
+			name: "process_resident_memory_bytes",
+			type: "gauge",
+			labels: {},
+			value: t.rss,
+			description: "Resident memory size in bytes."
+		},
+		{
+			name: "process_heap_bytes",
+			type: "gauge",
+			labels: {},
+			value: t.heapUsed,
+			description: "Used V8 heap size in bytes."
+		},
+		{
+			name: "process_cpu_seconds_total",
+			type: "counter",
+			labels: {},
+			value: (n.user + n.system) / 1e6,
+			description: "Total user + system CPU time spent in seconds."
+		}
+	];
+	return e && r.push({
+		name: "voltro_build_info",
+		type: "gauge",
+		labels: { version: e },
+		value: 1,
+		description: "Voltro build info (constant 1, version in the label)."
+	}), r;
+}, f = "text/plain; version=0.0.4; charset=utf-8", p = i([{
+	name: "PROMETHEUS_TOKEN",
+	required: !1,
+	secret: !0,
+	description: "Bearer token required on the scrape endpoint; unset leaves /metrics open."
+}]), m = (i = {}) => {
+	let a = i.path ?? "/metrics", o = p.read("PROMETHEUS_TOKEN", i.token), s = i.processMetrics ?? !0, c = {
+		method: "GET",
+		path: a,
+		handle: async (t) => {
+			if (!n(t.headers, o)) return {
+				status: 401,
+				body: "unauthorized",
+				contentType: "text/plain"
+			};
+			let a = await e.runPromise(r);
+			return {
+				status: 200,
+				body: u(s ? [...a, ...d(i.version)] : a),
+				contentType: f,
+				headers: { "cache-control": "no-store" }
+			};
+		}
+	};
+	return t({
+		name: i.name ? `@voltro/plugin-prometheus#${i.name}` : "@voltro/plugin-prometheus",
+		description: "Prometheus exporter — scrapes the unified Metrics-API at a /metrics endpoint in text exposition format.",
+		declaredEnv: p.declared,
+		httpRoutes: [c],
+		onActivate: (t) => e.sync(() => {
+			t.logger.info("prometheus exporter active", {
+				path: a,
+				tokenGated: !!o,
+				processMetrics: s
+			});
+		}),
+		onDeactivate: () => e.void
+	});
+};
+//#endregion
+export { u as formatPrometheus, d as processMetrics, m as prometheusPlugin };

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@voltro/plugin-prometheus",
+  "version": "0.1.0",
+  "description": "Prometheus exporter — scrapes the framework's unified Metrics-API (Effect MetricRegistry) at GET /metrics in Prometheus text exposition format. Counters, histograms (with buckets), gauges + custom metrics; optional bearer-token gate + node process metrics.",
+  "keywords": [
+    "voltro",
+    "typescript",
+    "framework"
+  ],
+  "license": "SEE LICENSE IN LICENSE",
+  "homepage": "https://voltro.dev",
+  "bugs": {
+    "email": "support@voltro.dev"
+  },
+  "author": {
+    "name": "Voltro UG",
+    "url": "https://voltro.dev"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "dependencies": {
+    "@voltro/env": "0.1.0",
+    "@voltro/protocol": "0.1.0",
+    "@voltro/runtime": "0.1.0"
+  },
+  "peerDependencies": {
+    "effect": "^3.21.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}