@actuate-media/cms-core 0.25.1 → 0.26.0

package/dist/diagnostics/api-metrics.d.ts

@@ -0,0 +1,135 @@
+/**
+ * API request instrumentation that powers the Dashboard "Delivery API"
+ * tiles (request volume / error rate / avg latency / p95).
+ *
+ * ## Why per-minute aggregated buckets and not per-request rows
+ *
+ * A single 24-hour window at 100 req/s on 20 routes is ~17M raw rows,
+ * but the same window aggregated to (minute × route × status-bucket)
+ * is ≤ 1440 × 20 × 5 = 144k rows — and in practice far less because
+ * most route/minute combinations have zero traffic. The reader
+ * (`/stats/api-delivery`) folds the last 1440 minute buckets into
+ * four scalars; the writer does one atomic UPSERT per request via
+ * raw SQL.
+ *
+ * ## Why p95 via histogram and not from raw samples
+ *
+ * Storing a histogram per bucket gives us percentile estimates with
+ * ~10% error vs ground truth while keeping the table tiny. The
+ * `LATENCY_BUCKETS` boundary list is log-scale (powers of 2 in
+ * milliseconds) so it covers ~1 ms heartbeats through multi-second
+ * outliers in 12 columns. p95 falls out as a `findIndex` once the
+ * histogram is merged across all minute buckets in the window.
+ *
+ * ## Why fire-and-forget and not awaited
+ *
+ * Metric recording MUST NOT slow the user-facing response. The
+ * `record()` call dispatches the UPSERT to a `void`-discarded promise
+ * so a slow DB round-trip never blocks the request that produced
+ * the metric. Errors are swallowed at the source — losing a metric
+ * sample is strictly preferable to surfacing a metric-pipeline error
+ * to the user.
+ *
+ * ## Why we self-exempt the dashboard polling routes
+ *
+ * The dashboard refetches `/stats` and `/stats/api-delivery` on a
+ * timer. If we counted those requests they'd dominate the volume
+ * tile and inflate the error rate (a logged-out tab would hit
+ * `/stats` and get 401 repeatedly). The route-normaliser excludes
+ * them explicitly — see `shouldRecord`.
+ */
+/**
+ * Upper bound (exclusive) of each histogram bucket, in milliseconds.
+ * The last bucket is `>= 1024 ms` (no upper bound).
+ *
+ * Indexed:
+ *   0: <1ms     1: 1-2ms     2: 2-4ms     3: 4-8ms
+ *   4: 8-16ms   5: 16-32ms   6: 32-64ms   7: 64-128ms
+ *   8: 128-256  9: 256-512  10: 512-1024 11: >=1024
+ */
+export declare const LATENCY_BUCKETS: readonly [1, 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024];
+export declare const HISTOGRAM_LENGTH: number;
+export type StatusBucket = '2xx' | '3xx' | '4xx' | '5xx' | 'other';
+export interface ApiMetricSample {
+    /** Request path, CMS-relative — e.g. `/collections/posts/abc123`. */
+    pathname: string;
+    status: number;
+    /** Response time in milliseconds. May be a float. */
+    durationMs: number;
+}
+/**
+ * Bucket a status code into one of 5 families. We keep the 1xx family
+ * out of the public type because no CMS route ever responds with one;
+ * if it ever happens, the `other` bucket catches it instead of
+ * silently being lost.
+ */
+export declare function statusBucketOf(status: number): StatusBucket;
+/**
+ * Return the index (0..HISTOGRAM_LENGTH-1) of the histogram bucket
+ * that this latency falls into. NaN / negative values fall in bucket
+ * 0 (treated as "<1ms") so a metric write never crashes on a bad
+ * input.
+ */
+export declare function histogramBucketIndex(durationMs: number): number;
+/**
+ * Build a fresh histogram array with a single sample placed in the
+ * correct bucket. Used to produce the JSON payload for an INSERT.
+ */
+export declare function makeHistogramFor(durationMs: number): number[];
+/**
+ * Element-wise add two histograms. Tolerant of either operand being
+ * missing or shorter than `HISTOGRAM_LENGTH` — defends against schema
+ * mismatches (e.g. an old row written before a bucket boundary change).
+ */
+export declare function mergeHistograms(a: number[] | null | undefined, b: number[]): number[];
+/**
+ * Snap a Date to the start of its UTC minute. Returns a new Date —
+ * never mutates the input.
+ */
+export declare function bucketStartFor(now?: Date | number): Date;
+/**
+ * Estimate percentile-N from a merged histogram. Returns the upper
+ * bound of the bucket that contains the requested percentile —
+ * which is the right "user-visible" answer (we are happy to say
+ * "p95 < 256ms" rather than guess the exact value inside the
+ * 128-256 bucket).
+ *
+ * For the overflow bucket (no upper bound), we report
+ * `LATENCY_BUCKETS[last]` as a lower-bound estimate; callers
+ * displaying this should annotate with a "≥" prefix if they want
+ * to expose the open-ended nature.
+ */
+export declare function estimatePercentile(histogram: number[], percentile: number): number;
+/**
+ * Normalise a request path to bound metric-row cardinality.
+ *
+ *   /collections/posts/abc123        →  /collections/posts/:id
+ *   /globals/site-settings           →  /globals/:slug
+ *   /collections/posts/abc123/restore→  /collections/posts/:id/restore
+ *   /unknown/long/path/that/leaks    →  /other
+ *
+ * The "/other" bucket catches anything we don't explicitly know
+ * about so a single hostile client with random URLs can't blow up
+ * the table.
+ */
+export declare function normalizeRoute(pathname: string): string;
+/**
+ * Routes that the dashboard polls itself, plus webhooks the cron
+ * fires. Counting these would either (a) cause feedback loops
+ * inflating the volume tile or (b) report cron-only traffic the
+ * editor never produces. The instrumentation skips them.
+ */
+export declare function shouldRecord(normalizedRoute: string): boolean;
+/**
+ * Record one API request to the metrics table. **Fire-and-forget** —
+ * callers MUST NOT `await` this. Errors are swallowed; the next
+ * request retries, and 1-minute aggregates are robust to occasional
+ * write loss.
+ *
+ * Writes a single SQL UPSERT so two concurrent requests landing in
+ * the same bucket interleave cleanly via Postgres's MVCC + the
+ * unique-on-conflict path. The histogram column is merged
+ * element-wise inside SQL, so we never read-modify-write from JS.
+ */
+export declare function recordApiRequest(sample: ApiMetricSample): void;
+//# sourceMappingURL=api-metrics.d.ts.map

package/dist/diagnostics/api-metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-metrics.d.ts","sourceRoot":"","sources":["../../src/diagnostics/api-metrics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AASH;;;;;;;;GAQG;AACH,eAAO,MAAM,eAAe,wDAAyD,CAAA;AAErF,eAAO,MAAM,gBAAgB,QAA6B,CAAA;AAE1D,MAAM,MAAM,YAAY,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,OAAO,CAAA;AAElE,MAAM,WAAW,eAAe;IAC9B,qEAAqE;IACrE,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE,MAAM,CAAA;IACd,qDAAqD;IACrD,UAAU,EAAE,MAAM,CAAA;CACnB;AAID;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,CAM3D;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAM/D;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE,CAI7D;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,GAAG,SAAS,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAMrF;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,GAAG,GAAE,IAAI,GAAG,MAAmB,GAAG,IAAI,CAGpE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAalF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAiBvD;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,eAAe,EAAE,MAAM,GAAG,OAAO,CAE7D;AAiGD;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,eAAe,GAAG,IAAI,CAY9D"}

package/dist/diagnostics/api-metrics.js

@@ -0,0 +1,374 @@
+/**
+ * API request instrumentation that powers the Dashboard "Delivery API"
+ * tiles (request volume / error rate / avg latency / p95).
+ *
+ * ## Why per-minute aggregated buckets and not per-request rows
+ *
+ * A single 24-hour window at 100 req/s on 20 routes is ~17M raw rows,
+ * but the same window aggregated to (minute × route × status-bucket)
+ * is ≤ 1440 × 20 × 5 = 144k rows — and in practice far less because
+ * most route/minute combinations have zero traffic. The reader
+ * (`/stats/api-delivery`) folds the last 1440 minute buckets into
+ * four scalars; the writer does one atomic UPSERT per request via
+ * raw SQL.
+ *
+ * ## Why p95 via histogram and not from raw samples
+ *
+ * Storing a histogram per bucket gives us percentile estimates with
+ * ~10% error vs ground truth while keeping the table tiny. The
+ * `LATENCY_BUCKETS` boundary list is log-scale (powers of 2 in
+ * milliseconds) so it covers ~1 ms heartbeats through multi-second
+ * outliers in 12 columns. p95 falls out as a `findIndex` once the
+ * histogram is merged across all minute buckets in the window.
+ *
+ * ## Why fire-and-forget and not awaited
+ *
+ * Metric recording MUST NOT slow the user-facing response. The
+ * `record()` call dispatches the UPSERT to a `void`-discarded promise
+ * so a slow DB round-trip never blocks the request that produced
+ * the metric. Errors are swallowed at the source — losing a metric
+ * sample is strictly preferable to surfacing a metric-pipeline error
+ * to the user.
+ *
+ * ## Why we self-exempt the dashboard polling routes
+ *
+ * The dashboard refetches `/stats` and `/stats/api-delivery` on a
+ * timer. If we counted those requests they'd dominate the volume
+ * tile and inflate the error rate (a logged-out tab would hit
+ * `/stats` and get 401 repeatedly). The route-normaliser excludes
+ * them explicitly — see `shouldRecord`.
+ */
+import { createLogger } from './logger.js';
+import { getDB } from '../db.js';
+const logger = createLogger('api-metrics');
+// ─── Public constants ──────────────────────────────────────────────────────
+/**
+ * Upper bound (exclusive) of each histogram bucket, in milliseconds.
+ * The last bucket is `>= 1024 ms` (no upper bound).
+ *
+ * Indexed:
+ *   0: <1ms     1: 1-2ms     2: 2-4ms     3: 4-8ms
+ *   4: 8-16ms   5: 16-32ms   6: 32-64ms   7: 64-128ms
+ *   8: 128-256  9: 256-512  10: 512-1024 11: >=1024
+ */
+export const LATENCY_BUCKETS = [1, 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024];
+export const HISTOGRAM_LENGTH = LATENCY_BUCKETS.length + 1; // 12
+// ─── Pure helpers ──────────────────────────────────────────────────────────
+/**
+ * Bucket a status code into one of 5 families. We keep the 1xx family
+ * out of the public type because no CMS route ever responds with one;
+ * if it ever happens, the `other` bucket catches it instead of
+ * silently being lost.
+ */
+export function statusBucketOf(status) {
+    if (status >= 200 && status < 300)
+        return '2xx';
+    if (status >= 300 && status < 400)
+        return '3xx';
+    if (status >= 400 && status < 500)
+        return '4xx';
+    if (status >= 500 && status < 600)
+        return '5xx';
+    return 'other';
+}
+/**
+ * Return the index (0..HISTOGRAM_LENGTH-1) of the histogram bucket
+ * that this latency falls into. NaN / negative values fall in bucket
+ * 0 (treated as "<1ms") so a metric write never crashes on a bad
+ * input.
+ */
+export function histogramBucketIndex(durationMs) {
+    if (!Number.isFinite(durationMs) || durationMs < 1)
+        return 0;
+    for (let i = 0; i < LATENCY_BUCKETS.length; i++) {
+        if (durationMs < LATENCY_BUCKETS[i])
+            return i;
+    }
+    return LATENCY_BUCKETS.length; // overflow bucket
+}
+/**
+ * Build a fresh histogram array with a single sample placed in the
+ * correct bucket. Used to produce the JSON payload for an INSERT.
+ */
+export function makeHistogramFor(durationMs) {
+    const arr = new Array(HISTOGRAM_LENGTH).fill(0);
+    arr[histogramBucketIndex(durationMs)] = 1;
+    return arr;
+}
+/**
+ * Element-wise add two histograms. Tolerant of either operand being
+ * missing or shorter than `HISTOGRAM_LENGTH` — defends against schema
+ * mismatches (e.g. an old row written before a bucket boundary change).
+ */
+export function mergeHistograms(a, b) {
+    const out = new Array(HISTOGRAM_LENGTH).fill(0);
+    for (let i = 0; i < HISTOGRAM_LENGTH; i++) {
+        out[i] = (a?.[i] ?? 0) + (b[i] ?? 0);
+    }
+    return out;
+}
+/**
+ * Snap a Date to the start of its UTC minute. Returns a new Date —
+ * never mutates the input.
+ */
+export function bucketStartFor(now = new Date()) {
+    const ms = typeof now === 'number' ? now : now.getTime();
+    return new Date(ms - (ms % 60_000));
+}
+/**
+ * Estimate percentile-N from a merged histogram. Returns the upper
+ * bound of the bucket that contains the requested percentile —
+ * which is the right "user-visible" answer (we are happy to say
+ * "p95 < 256ms" rather than guess the exact value inside the
+ * 128-256 bucket).
+ *
+ * For the overflow bucket (no upper bound), we report
+ * `LATENCY_BUCKETS[last]` as a lower-bound estimate; callers
+ * displaying this should annotate with a "≥" prefix if they want
+ * to expose the open-ended nature.
+ */
+export function estimatePercentile(histogram, percentile) {
+    const total = histogram.reduce((s, v) => s + v, 0);
+    if (total === 0)
+        return 0;
+    const target = total * percentile;
+    let acc = 0;
+    for (let i = 0; i < HISTOGRAM_LENGTH; i++) {
+        acc += histogram[i] ?? 0;
+        if (acc >= target) {
+            if (i < LATENCY_BUCKETS.length)
+                return LATENCY_BUCKETS[i];
+            return LATENCY_BUCKETS[LATENCY_BUCKETS.length - 1] * 2; // overflow estimate
+        }
+    }
+    return 0;
+}
+/**
+ * Normalise a request path to bound metric-row cardinality.
+ *
+ *   /collections/posts/abc123        →  /collections/posts/:id
+ *   /globals/site-settings           →  /globals/:slug
+ *   /collections/posts/abc123/restore→  /collections/posts/:id/restore
+ *   /unknown/long/path/that/leaks    →  /other
+ *
+ * The "/other" bucket catches anything we don't explicitly know
+ * about so a single hostile client with random URLs can't blow up
+ * the table.
+ */
+export function normalizeRoute(pathname) {
+    // Strip query string + trailing slash (except root).
+    let p = pathname.split('?')[0] ?? '/';
+    if (p.length > 1 && p.endsWith('/'))
+        p = p.slice(0, -1);
+    // Strip the `/api/cms` prefix if still present — depending on where
+    // we instrument, the path may or may not have been rewritten yet.
+    if (p.startsWith('/api/cms'))
+        p = p.slice('/api/cms'.length) || '/';
+    // Static or top-level routes — pass through verbatim.
+    if (KNOWN_STATIC_ROUTES.has(p))
+        return p;
+    // Pattern matchers for cardinality-bounding.
+    for (const { pattern, replacement } of ROUTE_PATTERNS) {
+        if (pattern.test(p))
+            return p.replace(pattern, replacement);
+    }
+    return '/other';
+}
+/**
+ * Routes that the dashboard polls itself, plus webhooks the cron
+ * fires. Counting these would either (a) cause feedback loops
+ * inflating the volume tile or (b) report cron-only traffic the
+ * editor never produces. The instrumentation skips them.
+ */
+export function shouldRecord(normalizedRoute) {
+    return !SKIP_ROUTES.has(normalizedRoute);
+}
+// ─── Lookup tables (kept module-scope so they're built once) ───────────────
+/**
+ * Verbatim routes — the dashboard, auth, health, etc. Keep this
+ * small; if your CMS exposes many top-level routes, prefer
+ * `ROUTE_PATTERNS` so the table stays bounded.
+ */
+const KNOWN_STATIC_ROUTES = new Set([
+    '/',
+    '/health',
+    '/stats',
+    '/stats/api-delivery',
+    '/stats/content-health',
+    '/auth/login',
+    '/auth/logout',
+    '/auth/me',
+    '/auth/csrf',
+    '/auth/forgot-password',
+    '/auth/reset-password',
+    '/auth/totp/login',
+    '/setup/status',
+    '/setup/create-admin',
+    '/search',
+    '/users',
+    '/api-keys',
+    '/notifications',
+    '/notifications/stream',
+    '/notifications/read-all',
+    '/media',
+    '/media/upload',
+    '/forms',
+    '/seo/config',
+    '/seo/analyze',
+    '/redirects',
+    '/script-tags',
+    '/saved-sections',
+    '/page-templates',
+    '/webhooks',
+    '/webhooks/test',
+]);
+/**
+ * Skip these from the metric — they're either the dashboard polling
+ * itself (feedback loop) or cron-only traffic that distorts the
+ * editor-facing tiles.
+ */
+const SKIP_ROUTES = new Set([
+    '/stats',
+    '/stats/api-delivery',
+    '/stats/content-health',
+    '/health',
+    '/notifications/stream', // long-lived SSE; counting once on open is misleading
+]);
+const ROUTE_PATTERNS = [
+    {
+        pattern: /^\/collections\/[^/]+\/[^/]+\/restore$/,
+        replacement: '/collections/:slug/:id/restore',
+    },
+    {
+        pattern: /^\/collections\/[^/]+\/[^/]+\/versions(?:\/[^/]+)?$/,
+        replacement: '/collections/:slug/:id/versions',
+    },
+    {
+        pattern: /^\/collections\/[^/]+\/[^/]+\/duplicate$/,
+        replacement: '/collections/:slug/:id/duplicate',
+    },
+    { pattern: /^\/collections\/[^/]+\/[^/]+$/, replacement: '/collections/:slug/:id' },
+    { pattern: /^\/collections\/[^/]+$/, replacement: '/collections/:slug' },
+    { pattern: /^\/globals\/[^/]+$/, replacement: '/globals/:slug' },
+    { pattern: /^\/media\/[^/]+$/, replacement: '/media/:id' },
+    { pattern: /^\/forms\/[^/]+\/submit$/, replacement: '/forms/:id/submit' },
+    { pattern: /^\/forms\/[^/]+\/submissions(?:\/[^/]+)?$/, replacement: '/forms/:id/submissions' },
+    { pattern: /^\/forms\/[^/]+$/, replacement: '/forms/:id' },
+    { pattern: /^\/users\/[^/]+$/, replacement: '/users/:id' },
+    { pattern: /^\/api-keys\/[^/]+$/, replacement: '/api-keys/:id' },
+    { pattern: /^\/redirects\/[^/]+$/, replacement: '/redirects/:id' },
+    { pattern: /^\/script-tags\/[^/]+$/, replacement: '/script-tags/:id' },
+    { pattern: /^\/saved-sections\/[^/]+$/, replacement: '/saved-sections/:id' },
+    { pattern: /^\/page-templates\/[^/]+$/, replacement: '/page-templates/:id' },
+    { pattern: /^\/webhooks\/[^/]+(?:\/.+)?$/, replacement: '/webhooks/:id' },
+    { pattern: /^\/notifications\/[^/]+\/read$/, replacement: '/notifications/:id/read' },
+    { pattern: /^\/cron\/.+/, replacement: '/cron/:job' },
+    { pattern: /^\/dev\/.+/, replacement: '/dev/:fn' },
+    { pattern: /^\/seo\/.+/, replacement: '/seo/:fn' },
+    { pattern: /^\/share\/.+/, replacement: '/share/:token' },
+    { pattern: /^\/preview\/.+/, replacement: '/preview/:fn' },
+    { pattern: /^\/page-builder\/.+/, replacement: '/page-builder/:fn' },
+    { pattern: /^\/ai\/.+/, replacement: '/ai/:fn' },
+    { pattern: /^\/auth\/.+/, replacement: '/auth/:fn' },
+    { pattern: /^\/resolve(?:\/.+)?$/, replacement: '/resolve' },
+];
+// ─── Writer ────────────────────────────────────────────────────────────────
+/**
+ * Record one API request to the metrics table. **Fire-and-forget** —
+ * callers MUST NOT `await` this. Errors are swallowed; the next
+ * request retries, and 1-minute aggregates are robust to occasional
+ * write loss.
+ *
+ * Writes a single SQL UPSERT so two concurrent requests landing in
+ * the same bucket interleave cleanly via Postgres's MVCC + the
+ * unique-on-conflict path. The histogram column is merged
+ * element-wise inside SQL, so we never read-modify-write from JS.
+ */
+export function recordApiRequest(sample) {
+    const route = normalizeRoute(sample.pathname);
+    if (!shouldRecord(route))
+        return;
+    // Schedule the write but do not await. Returning `void` is the
+    // contract — callers shouldn't be tempted to `.then()` on it.
+    void writeMetricBucket({
+        bucketStart: bucketStartFor(),
+        route,
+        statusBucket: statusBucketOf(sample.status),
+        durationMs: sample.durationMs,
+    });
+}
+async function writeMetricBucket(args) {
+    let db;
+    try {
+        db = getDB();
+    }
+    catch {
+        // DB not initialised yet (e.g. dev server hot-reload race) —
+        // skip silently. There's nothing useful to log here and we
+        // don't want a stack trace on every dropped sample.
+        return;
+    }
+    // Some hosts ship a Prisma client that doesn't include the
+    // `apiRequestMetric` model (e.g. third-party deploys that copied
+    // an older schema). Guard so we degrade silently rather than 500ing
+    // every request.
+    if (!db || typeof db.$executeRawUnsafe !== 'function' || !('apiRequestMetric' in db)) {
+        return;
+    }
+    const histogram = makeHistogramFor(args.durationMs);
+    try {
+        // Atomic INSERT...ON CONFLICT DO UPDATE. The histogram merge is
+        // expressed as a `jsonb_build_array` over the existing + new
+        // bucket counts so we never read the prior row from JS.
+        //
+        // CUID-ish ID generation via gen_random_uuid() keeps the ID
+        // schema-compatible with the model's `@default(cuid())` (both
+        // are 26+ char ASCII strings; Prisma's cuid is preferred but
+        // SQL-level UUIDs are accepted by the column type and not
+        // surfaced to consumers).
+        await db.$executeRawUnsafe(`
+        INSERT INTO "actuate_api_request_metrics"
+          ("id", "bucketStart", "route", "statusBucket", "count", "sumLatencyMs", "maxLatencyMs", "latencyHistogram", "updatedAt")
+        VALUES (
+          'm_' || replace(gen_random_uuid()::text, '-', ''),
+          $1::timestamp,
+          $2,
+          $3,
+          1,
+          $4,
+          $4,
+          $5::jsonb,
+          NOW()
+        )
+        ON CONFLICT ("bucketStart", "route", "statusBucket") DO UPDATE
+          SET "count"        = "actuate_api_request_metrics"."count" + 1,
+              "sumLatencyMs" = "actuate_api_request_metrics"."sumLatencyMs" + EXCLUDED."sumLatencyMs",
+              "maxLatencyMs" = GREATEST("actuate_api_request_metrics"."maxLatencyMs", EXCLUDED."maxLatencyMs"),
+              "latencyHistogram" = (
+                SELECT jsonb_agg(
+                  COALESCE(("actuate_api_request_metrics"."latencyHistogram"->>i)::int, 0) +
+                  COALESCE((EXCLUDED."latencyHistogram"->>i)::int, 0)
+                  ORDER BY i
+                )
+                FROM generate_series(0, ${HISTOGRAM_LENGTH - 1}) AS i
+              ),
+              "updatedAt"    = NOW()
+      `, args.bucketStart, args.route, args.statusBucket, args.durationMs, JSON.stringify(histogram));
+    }
+    catch (err) {
+        // Throttle the log so a misconfigured DB doesn't drown the
+        // logger. We rate-limit *log lines*, not metric writes — every
+        // request still attempts a write, but only one error/minute
+        // surfaces in console.
+        rateLimitedWarn('recordApiRequest write failed', err instanceof Error ? err.message : String(err));
+    }
+}
+let lastWarnAt = 0;
+function rateLimitedWarn(msg, detail) {
+    const now = Date.now();
+    if (now - lastWarnAt < 60_000)
+        return;
+    lastWarnAt = now;
+    logger.warn(msg, { detail });
+}
+//# sourceMappingURL=api-metrics.js.map

package/dist/diagnostics/api-metrics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-metrics.js","sourceRoot":"","sources":["../../src/diagnostics/api-metrics.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@actuate-media/cms-core",
-  "version": "0.25.1",
+  "version": "0.26.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/actuate-media/actuatecms.git",

package/prisma/migrations/0007_dashboard_metrics/migration.sql

@@ -0,0 +1,74 @@
+-- Dashboard metrics & content health
+--
+-- Adds two tables that back the redesigned admin Dashboard:
+--   * actuate_api_request_metrics  — per-minute pre-aggregated request
+--     counters with a fixed log-scale latency histogram, sized to keep
+--     a week of traffic in O(minutes × routes × status-buckets) rows.
+--   * actuate_content_issues       — persisted content-quality issues
+--     produced by the nightly content-health scanner. Upserted by
+--     (documentId, type) so the scanner is idempotent.
+--
+-- Both tables are safe to add to a populated database: they have no
+-- backfill dependency and no constraints that touch existing rows.
+
+-- ---------------------------------------------------------------------------
+-- ContentIssueType enum
+-- ---------------------------------------------------------------------------
+CREATE TYPE "ContentIssueType" AS ENUM (
+  'MISSING_META_DESCRIPTION',
+  'MISSING_ALT_TEXT',
+  'BROKEN_INTERNAL_LINK',
+  'OUTDATED_CONTENT'
+);
+
+-- ---------------------------------------------------------------------------
+-- actuate_api_request_metrics
+-- ---------------------------------------------------------------------------
+CREATE TABLE "actuate_api_request_metrics" (
+  "id"                TEXT      NOT NULL,
+  "bucketStart"       TIMESTAMP(3) NOT NULL,
+  "route"             TEXT      NOT NULL,
+  "statusBucket"      TEXT      NOT NULL,
+  "count"             INTEGER   NOT NULL DEFAULT 0,
+  "sumLatencyMs"      DOUBLE PRECISION NOT NULL DEFAULT 0,
+  "maxLatencyMs"      DOUBLE PRECISION NOT NULL DEFAULT 0,
+  "latencyHistogram"  JSONB     NOT NULL,
+  "updatedAt"         TIMESTAMP(3) NOT NULL,
+
+  CONSTRAINT "actuate_api_request_metrics_pkey" PRIMARY KEY ("id")
+);
+
+CREATE UNIQUE INDEX "actuate_api_request_metrics_bucketStart_route_statusBucket_key"
+  ON "actuate_api_request_metrics" ("bucketStart", "route", "statusBucket");
+
+CREATE INDEX "actuate_api_request_metrics_bucketStart_idx"
+  ON "actuate_api_request_metrics" ("bucketStart");
+
+-- ---------------------------------------------------------------------------
+-- actuate_content_issues
+-- ---------------------------------------------------------------------------
+CREATE TABLE "actuate_content_issues" (
+  "id"          TEXT             NOT NULL,
+  "documentId"  TEXT             NOT NULL,
+  "type"        "ContentIssueType" NOT NULL,
+  "count"       INTEGER          NOT NULL DEFAULT 1,
+  "details"     JSONB,
+  "firstSeenAt" TIMESTAMP(3)     NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  "lastSeenAt"  TIMESTAMP(3)     NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+  CONSTRAINT "actuate_content_issues_pkey" PRIMARY KEY ("id"),
+  CONSTRAINT "actuate_content_issues_documentId_fkey"
+    FOREIGN KEY ("documentId")
+    REFERENCES "actuate_documents"("id")
+    ON DELETE CASCADE
+    ON UPDATE CASCADE
+);
+
+CREATE UNIQUE INDEX "actuate_content_issues_documentId_type_key"
+  ON "actuate_content_issues" ("documentId", "type");
+
+CREATE INDEX "actuate_content_issues_type_idx"
+  ON "actuate_content_issues" ("type");
+
+CREATE INDEX "actuate_content_issues_documentId_idx"
+  ON "actuate_content_issues" ("documentId");