feat(metrics): record /api/healthz requests in the API metrics registry

changelog.d/added-healthz-request-metrics.md

@@ -0,0 +1 @@
+Record `/api/healthz` request count, status class, and duration in the existing bounded `/api/metrics` registry so readiness failures can be alerted on.

src/__tests__/healthz-route.test.ts

@@ -3,6 +3,7 @@ import fs from "fs";
 import { docsContentPath } from "@/app/docs/page-map";
 import { GET } from "@/app/api/healthz/route";
 import { logger } from "@/lib/logger";
+import { metricsRegistry } from "@/lib/metrics";
 
 /**
  * Coverage for src/app/api/healthz/route.ts — the readiness probe that
@@ -154,4 +155,18 @@ describe("/api/healthz route", () => {
       error: "EACCES: permission denied",
     });
   });
+
+  it("records healthz requests by status class in the metrics registry", async () => {
+    statSyncSpy.mockImplementationOnce(() => {
+      throw new Error("boom");
+    });
+
+    const res = await GET();
+
+    expect(res.status).toBe(503);
+    const body = await metricsRegistry.metrics();
+    expect(body).toContain(
+      'docs_api_requests_total{route="healthz",method="GET",status_class="5xx"}'
+    );
+  });
 });

src/app/api/healthz/route.ts

@@ -2,6 +2,7 @@ import { NextResponse } from "next/server";
 import fs from "fs";
 import { docsContentPath } from "../../docs/page-map";
 import { logger } from "@/lib/logger";
+import { recordApiRequest } from "@/lib/metrics";
 
 // Readiness check for the docs app.
 //
@@ -15,6 +16,18 @@ import { logger } from "@/lib/logger";
 // orchestrator or deploy pipeline can detect that condition before routing
 // traffic to this instance.
 export async function GET() {
+  const startedAt = performance.now();
+  const response = check();
+  recordApiRequest(
+    "healthz",
+    "GET",
+    response.status,
+    performance.now() - startedAt
+  );
+  return response;
+}
+
+function check(): NextResponse {
   try {
     const stat = fs.statSync(docsContentPath);
     if (!stat.isDirectory()) {

src/lib/metrics.ts

@@ -15,7 +15,7 @@
  */
 import { Counter, Histogram, Registry } from "prom-client";
 
-export const ApiRoutes = ["search", "docs-image"] as const;
+export const ApiRoutes = ["search", "docs-image", "healthz"] as const;
 export type ApiRoute = (typeof ApiRoutes)[number];
 
 const HTTP_METHODS = new Set([