Merge pull request #711 from mikewheeleer/codex/issue-665

feat: expose Prometheus metrics endpoint

Author: Jagadeeshftw

README.md

@@ -1003,3 +1003,10 @@ The codebase includes comprehensive verification patterns:
 - **Address Normalization**: `normalizeStarknetAddress` enforces canonical 66-character lower-case hex format and SNIP-23 checksum validation.
 - **Starknet Failover**: `STARKNET_RPC_URL` supports comma-separated RPC endpoints with automatic failover.
 - **Auth Session Family Revocation**: Session token rotation with `familyId` revocation protects against refresh token replay attacks.
+# Metrics
+
+`GET /metrics` exposes the existing process-local auth, billing, diagnostics,
+session, and Starknet snapshots in Prometheus text format. It is mounted
+outside `/api/v1` so a scraper does not need API-version routing. Protect the
+endpoint at the ingress/network layer when operational metrics should not be
+public.

package.json

@@ -34,6 +34,7 @@
     "helmet": "^8.3.0",
     "nodemailer": "^9.0.3",
     "pg": "^8.13.1",
+    "prom-client": "^15.1.3",
     "starknet": "^10.0.2",
     "zod": "^4.4.3"
   },

pnpm-lock.yaml

@@ -31,6 +31,7 @@ import { accessLogMiddleware } from "./middleware/access-log.js";
 import { requestIdMiddleware } from "./middleware/request-id.js";
 import { verifyAbiCompatibility } from "./starknet/abi.js";
 import { provider, getEscrowAbi, getAgreementAbi } from "./starknet/client.js";
+import { metricsRegistry, renderMetrics } from "./observability/metrics.js";
 
 export const app = express();
 initLogger();
@@ -84,6 +85,18 @@ app.use(
 );
 app.use(express.json({ limit: "1mb" }));
 
+// Prometheus scraping is intentionally outside /api/v1. Deployments should
+// restrict this endpoint at the network or ingress layer when metrics are
+// not intended to be public.
+app.get("/metrics", async (_req, res, next) => {
+  try {
+    res.setHeader("Content-Type", metricsRegistry.contentType);
+    res.send(await renderMetrics());
+  } catch (error) {
+    next(error);
+  }
+});
+
 app.use(dbReadinessMiddleware);
 
 // Rate limiting: limiters are built via the shared factory so the

src/index.ts

@@ -0,0 +1,64 @@
+import { Counter, Gauge, Registry } from "prom-client";
+import { getAuthMetricsSnapshot as getAuthMiddlewareMetricsSnapshot } from "../auth/middleware-metrics.js";
+import { getSessionMetricsSnapshot } from "../auth/session-metrics.js";
+import { getAuthMetricsSnapshot as getAuthRouteMetricsSnapshot } from "../routes/auth-metrics.js";
+import { getBillingMetricsSnapshot } from "../routes/billing-metrics.js";
+import { getDiagnosticsMetricsSnapshot } from "../routes/diagnostics-metrics.js";
+import { getStarknetMetricsSnapshot } from "../starknet/client-metrics.js";
+
+type Snapshot = { counters: Record<string, number>; gauges?: Record<string, number> };
+type Metric = Counter<string> | Gauge<string>;
+
+export const metricsRegistry = new Registry();
+const metrics = new Map<string, Metric>();
+
+function metricName(name: string): string {
+  const normalized = name.toLowerCase().replace(/[^a-z0-9_:]/g, "_");
+  return normalized.endsWith("_total") ? normalized.slice(0, -6) : normalized;
+}
+
+function updateSnapshot(snapshot: Snapshot): void {
+  for (const [name, value] of Object.entries(snapshot.counters)) {
+    const key = `counter:${name}`;
+    let metric = metrics.get(key) as Counter<string> | undefined;
+    if (!metric) {
+      metric = new Counter({
+        name: metricName(name),
+        help: `${name} counter`,
+        registers: [metricsRegistry],
+      });
+      metrics.set(key, metric);
+    }
+    metric.reset();
+    metric.inc(value);
+  }
+
+  for (const [name, value] of Object.entries(snapshot.gauges ?? {})) {
+    const key = `gauge:${name}`;
+    let metric = metrics.get(key) as Gauge<string> | undefined;
+    if (!metric) {
+      metric = new Gauge({
+        name: metricName(name),
+        help: `${name} gauge`,
+        registers: [metricsRegistry],
+      });
+      metrics.set(key, metric);
+    }
+    metric.set(value);
+  }
+}
+
+/** Refreshes the shared registry from the existing snapshot-based metrics API. */
+export function refreshMetrics(): void {
+  updateSnapshot(getAuthMiddlewareMetricsSnapshot());
+  updateSnapshot(getSessionMetricsSnapshot());
+  updateSnapshot(getAuthRouteMetricsSnapshot());
+  updateSnapshot(getBillingMetricsSnapshot());
+  updateSnapshot(getDiagnosticsMetricsSnapshot());
+  updateSnapshot(getStarknetMetricsSnapshot());
+}
+
+export async function renderMetrics(): Promise<string> {
+  refreshMetrics();
+  return metricsRegistry.metrics();
+}