🔭 feat(o11y): Add Prometheus Metrics Endpoint and HTTP Instrumentation (#26)

* feat(o11y): add prometheus metrics endpoint and HTTP instrumentation

* chore: add authenticated endpoint

---------

Co-authored-by: teresama <teresa.blancoabad@clickhouse.com>

Author: pjhampton

.env.example

@@ -5,6 +5,10 @@
 SESSION_SECRET=
 
 # ── Optional ─────────────────────────────────────────────────
+# Bearer token required to scrape the /metrics (Prometheus) endpoint.
+# The endpoint returns 401 if this is unset or the token does not match.
+# ADMIN_PANEL_METRICS_SECRET=
+
 # Browser-facing URL of the LibreChat API server (used for OAuth redirects).
 # Defaults to http://localhost:3080
 # VITE_API_BASE_URL=http://localhost:3080

bun.lock

@@ -43,6 +43,7 @@
     "js-yaml": "^4.1.1",
     "librechat-data-provider": "^0.8.407",
     "lucide-react": "^0.545.0",
+    "prom-client": "^15.1.3",
     "react": "^19.2.0",
     "react-dom": "^19.2.0",
     "react-i18next": "^16.5.4",

package.json

@@ -1,5 +1,6 @@
 import { Glob } from 'bun';
 import { join } from 'node:path';
+import { metricsResponse, httpRequestsTotal, httpRequestDurationSeconds } from './src/server/metrics';
 
 const CLIENT_DIR = join(import.meta.dir, 'dist', 'client');
 const SERVER_ENTRY = new URL('./dist/server/server.js', import.meta.url);
@@ -35,6 +36,10 @@ type Handler = { default: { fetch: (req: Request) => Promise<Response> } };
 
 const { default: handler } = (await import(SERVER_ENTRY.href)) as Handler;
 
+if (!process.env.ADMIN_PANEL_METRICS_SECRET) {
+  console.warn('[metrics] ADMIN_PANEL_METRICS_SECRET is not set — /metrics will return 401 for all requests');
+}
+
 async function buildStaticRoutes(): Promise<Record<string, () => Response>> {
   const routes: Record<string, () => Response> = {};
   for await (const path of new Glob('**/*').scan(CLIENT_DIR)) {
@@ -50,8 +55,14 @@ Bun.serve({
   port: Number(process.env.PORT ?? 3000),
   routes: {
     ...(await buildStaticRoutes()),
+    '/metrics': (req) => metricsResponse(req),
     '/*': async (req) => {
+      const url = new URL(req.url);
+      const end = httpRequestDurationSeconds.startTimer({ method: req.method, path: url.pathname });
       const res = await handler.fetch(req);
+      const statusCode = String(res.status);
+      httpRequestsTotal.inc({ method: req.method, path: url.pathname, status_code: statusCode });
+      end({ status_code: statusCode });
       const patched = new Response(res.body, res);
       for (const [k, v] of Object.entries(NO_CACHE)) {
         patched.headers.set(k, v);

server.ts

@@ -0,0 +1,44 @@
+import { timingSafeEqual } from 'crypto';
+import client, { register } from 'prom-client';
+
+client.collectDefaultMetrics();
+
+export const httpRequestsTotal = new client.Counter({
+  name: 'admin_http_requests_total',
+  help: 'Total number of HTTP requests',
+  labelNames: ['method', 'path', 'status_code'] as const,
+});
+
+export const httpRequestDurationSeconds = new client.Histogram({
+  name: 'admin_http_request_duration_seconds',
+  help: 'Duration of HTTP requests in seconds',
+  labelNames: ['method', 'path', 'status_code'] as const,
+  buckets: [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10],
+});
+
+export async function metricsResponse(req: Request): Promise<Response> {
+  const secret = process.env.ADMIN_PANEL_METRICS_SECRET;
+  const auth = req.headers.get('authorization');
+  if (!secret || !auth) return new Response(null, { status: 401 });
+
+  const token = auth.replace(/^bearer\s+/i, '');
+  const encode = (s: string) => new TextEncoder().encode(s);
+  const expected = encode(secret);
+  const actual = encode(token);
+  const maxLen = Math.max(expected.byteLength, actual.byteLength);
+  const paddedExpected = new Uint8Array(maxLen);
+  const paddedActual = new Uint8Array(maxLen);
+  paddedExpected.set(expected);
+  paddedActual.set(actual);
+  const lengthMatch = expected.byteLength === actual.byteLength;
+  if (!timingSafeEqual(paddedExpected, paddedActual) || !lengthMatch) {
+    return new Response(null, { status: 401 });
+  }
+
+  try {
+    const data = await register.metrics();
+    return new Response(data, { headers: { 'Content-Type': register.contentType } });
+  } catch {
+    return new Response(null, { status: 500 });
+  }
+}