feat: add basic api metric (detecting api client versions)

apps/api/package.json

@@ -33,6 +33,10 @@
     "@octokit/rest": "catalog:",
     "@octokit/webhooks": "^13.7.4",
     "@octokit/webhooks-types": "^7.5.1",
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/exporter-metrics-otlp-http": "^0.55.0",
+    "@opentelemetry/resources": "^1.28.0",
+    "@opentelemetry/sdk-metrics": "^1.28.0",
     "@t3-oss/env-core": "catalog:",
     "@trpc/server": "11.0.0-rc.364",
     "bcryptjs": "^2.4.3",

apps/api/src/config.ts

@@ -37,6 +37,9 @@ export const env = createEnv({
     BASE_URL: z.string().optional(),
 
     OTEL_SAMPLER_RATIO: z.number().optional().default(1),
+    OTEL_EXPORTER_OTLP_ENDPOINT: z.string().optional(),
+    OTEL_EXPORTER_OTLP_METRICS_ENDPOINT: z.string().optional(),
+    OTEL_SERVICE_NAME: z.string().default("ctrlplane-api"),
 
     AZURE_APP_CLIENT_ID: z.string().optional(),
 

apps/api/src/index.ts

@@ -1,3 +1,5 @@
+import "@/instrumentation.js";
+
 import { env } from "@/config.js";
 import { app } from "@/server.js";
 

apps/api/src/instrumentation.ts

@@ -0,0 +1,49 @@
+import { env } from "@/config.js";
+import { metrics } from "@opentelemetry/api";
+import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-http";
+import { Resource } from "@opentelemetry/resources";
+import {
+  MeterProvider,
+  PeriodicExportingMetricReader,
+} from "@opentelemetry/sdk-metrics";
+
+import { logger } from "@ctrlplane/logger";
+
+const stripTrailingSlash = (s: string) => s.replace(/\/$/, "");
+const appendMetricsPath = (base: string) =>
+  `${stripTrailingSlash(base)}/v1/metrics`;
+
+const metricsUrl =
+  env.OTEL_EXPORTER_OTLP_METRICS_ENDPOINT ??
+  (env.OTEL_EXPORTER_OTLP_ENDPOINT &&
+    appendMetricsPath(env.OTEL_EXPORTER_OTLP_ENDPOINT));
+
+if (metricsUrl) {
+  const meterProvider = new MeterProvider({
+    resource: new Resource({ "service.name": env.OTEL_SERVICE_NAME }),
+    readers: [
+      new PeriodicExportingMetricReader({
+        exporter: new OTLPMetricExporter({ url: metricsUrl }),
+        exportIntervalMillis: 30_000,
+      }),
+    ],
+  });
+
+  metrics.setGlobalMeterProvider(meterProvider);
+
+  for (const signal of ["SIGINT", "SIGTERM"] as const) {
+    process.on(signal, () => {
+      meterProvider
+        .shutdown()
+        .catch((err) =>
+          logger.error("meterProvider.shutdown error", { err }),
+        );
+    });
+  }
+
+  logger.info(`OTel metrics enabled (endpoint: ${metricsUrl})`);
+} else {
+  logger.info(
+    "OTel metrics disabled (set OTEL_EXPORTER_OTLP_ENDPOINT or OTEL_EXPORTER_OTLP_METRICS_ENDPOINT to enable)",
+  );
+}

apps/api/src/middleware/metrics.ts

@@ -0,0 +1,78 @@
+import type { Counter } from "@opentelemetry/api";
+import type { Request, RequestHandler } from "express";
+import { metrics } from "@opentelemetry/api";
+
+// Clients in this set are tagged with their version (e.g. `ctrlc/1.2.3`);
+// everyone else is tagged with just the client name to keep cardinality bounded.
+const VERSIONED_CLIENT_ALLOWLIST = new Set(["ctrlc"]);
+
+const BROWSER_MATCHERS: Array<{ test: (ua: string) => boolean; name: string }> =
+  [
+    // Order matters: Edge / Opera UAs include "Chrome/" too, so they go first.
+    { test: (ua) => ua.includes("Edg/") || ua.includes("Edge/"), name: "Edge" },
+    {
+      test: (ua) => ua.includes("OPR/") || ua.includes("Opera/"),
+      name: "Opera",
+    },
+    { test: (ua) => ua.includes("Chrome/"), name: "Chrome" },
+    { test: (ua) => ua.includes("Firefox/"), name: "Firefox" },
+    // Safari last: every WebKit-based browser includes "Safari/" in its UA.
+    {
+      test: (ua) => ua.startsWith("Mozilla/") && ua.includes("Safari/"),
+      name: "Safari",
+    },
+  ];
+
+export const simplifyUserAgent = (
+  userAgent: string | string[] | undefined | null,
+): string => {
+  const ua = Array.isArray(userAgent) ? userAgent[0] : userAgent;
+  if (!ua || ua.trim() === "") return "unknown";
+  const trimmed = ua.trim();
+
+  for (const { test, name } of BROWSER_MATCHERS) {
+    if (test(trimmed)) return name;
+  }
+
+  // Generic "Mozilla/..." UA we don't recognize — still a browser-shape.
+  if (trimmed.startsWith("Mozilla/")) return "browser-other";
+
+  // Non-browser clients usually look like "name/version ..." — take the first
+  // product token, then split name/version.
+  const [rawName, version] = trimmed.split(/\s+/, 1)[0]!.split("/", 2);
+  const name = rawName?.toLowerCase();
+  if (!name || !/^[a-z][a-z0-9._-]{0,63}$/.test(name)) return "other";
+  return VERSIONED_CLIENT_ALLOWLIST.has(name) && version
+    ? `${name}/${version}`
+    : name;
+};
+
+const resolveRouteTemplate = (req: Request): string => {
+  const template = req.route?.path;
+  if (template == null) return "unmatched";
+  return `${req.baseUrl}${typeof template === "string" ? template : String(template)}`;
+};
+
+let counter: Counter | null = null;
+const getCounter = (): Counter => {
+  if (counter) return counter;
+  counter = metrics
+    .getMeter("ctrlplane-api")
+    .createCounter("http.server.requests_by_client", {
+      description:
+        "Number of HTTP requests received, labeled by simplified client (User-Agent)",
+    });
+  return counter;
+};
+
+export const metricsMiddleware: RequestHandler = (req, res, next) => {
+  res.on("finish", () => {
+    getCounter().add(1, {
+      client: simplifyUserAgent(req.headers["user-agent"]),
+      method: req.method,
+      status_code: String(res.statusCode),
+      route: resolveRouteTemplate(req),
+    });
+  });
+  next();
+};

apps/api/src/server.ts

@@ -2,6 +2,7 @@ import { dirname, join } from "path";
 import { fileURLToPath } from "url";
 import { requireAuth } from "@/middleware/auth.js";
 import { errorHandler } from "@/middleware/error-handler.js";
+import { metricsMiddleware } from "@/middleware/metrics.js";
 import { createV1Router } from "@/routes/index.js";
 import * as trpcExpress from "@trpc/server/adapters/express";
 import { toNodeHandler } from "better-auth/node";
@@ -66,6 +67,7 @@ const app = express()
   .use(express.urlencoded({ extended: true, limit: "100mb" }))
   .use(express.json({ limit: "100mb" }))
   .use(cookieParser())
+  .use(metricsMiddleware)
   .use(loggerMiddleware)
 
   // Health check endpoint (before OpenAPI validator)

packages/workspace-engine-sdk/eslint.config.js

@@ -1,2 +1,9 @@
+import baseConfig from "@ctrlplane/eslint-config/base";
+
 /** @type {import('typescript-eslint').Config} */
-export default [];
+export default [
+  {
+    ignores: ["dist/**", "node_modules/**", "src/schema.ts"],
+  },
+  ...baseConfig,
+];