Track HiveGrid Cloud planning reference

This commit is contained in:
david committed 2026-06-26 20:48:01 +02:00
1 parent b3d5ea6764
commit e341c5938a
5784 files changed
+1104929 -3

No files matched your search

@@ -0,0 +1,46 @@
import { describe, it, expect, beforeEach } from "vitest";
import { resetWebMetricsForTests, getWebMetrics } from "./registry.js";
import { recordAiTokensConsumed, resetAiCostBucketsForTests } from "./ai-cost.js";
beforeEach(() => {
resetWebMetricsForTests();
resetAiCostBucketsForTests();
});
describe("recordAiTokensConsumed", () => {
it("increments the counter with provider / model / tenant_bucket labels", async () => {
recordAiTokensConsumed({ provider: "openai", model: "gpt-4o", tenantId: "tenant-1", tokens: 100 });
const text = await getWebMetrics().registry.metrics();
expect(text).toMatch(/ai_tokens_consumed_total\{[^}]*provider="openai"[^}]*model="gpt-4o"[^}]*tenant_bucket="tenant-1"[^}]*\} 100/);
});
it("groups anonymous calls under tenant_bucket=anonymous", async () => {
recordAiTokensConsumed({ provider: "scaleway", model: "mistral", tenantId: null, tokens: 50 });
const text = await getWebMetrics().registry.metrics();
expect(text).toMatch(/ai_tokens_consumed_total\{[^}]*tenant_bucket="anonymous"[^}]*\} 50/);
});
it("buckets new tenants past the cap into tenant_bucket=other", async () => {
for (let i = 0; i < 100; i += 1) {
recordAiTokensConsumed({ provider: "openai", model: "gpt-4", tenantId: `t-${i}`, tokens: 1 });
}
recordAiTokensConsumed({ provider: "openai", model: "gpt-4", tenantId: "t-overflow", tokens: 25 });
const text = await getWebMetrics().registry.metrics();
expect(text).toMatch(/ai_tokens_consumed_total\{[^}]*tenant_bucket="other"[^}]*\} 25/);
expect(text).not.toMatch(/tenant_bucket="t-overflow"/);
});
it("ignores zero / negative / NaN token counts", async () => {
recordAiTokensConsumed({ provider: "openai", model: "gpt-4", tenantId: "t1", tokens: 0 });
recordAiTokensConsumed({ provider: "openai", model: "gpt-4", tenantId: "t1", tokens: -5 });
recordAiTokensConsumed({ provider: "openai", model: "gpt-4", tenantId: "t1", tokens: Number.NaN });
const text = await getWebMetrics().registry.metrics();
expect(text).not.toMatch(/ai_tokens_consumed_total\{/);
});
it("sanitises control characters in label values", async () => {
recordAiTokensConsumed({ provider: "openai", model: "gpt-4\nfoo", tenantId: "t1\tx", tokens: 7 });
const text = await getWebMetrics().registry.metrics();
expect(text).toMatch(/ai_tokens_consumed_total\{[^}]*provider="openai"[^}]*model="gpt-4foo"[^}]*tenant_bucket="t1x"[^}]*\} 7/);
});
});
@@ -0,0 +1,81 @@
/**
* AI-token-cost metric hook with cardinality discipline.
*
* Calling `recordAiTokensConsumed({ provider, model, tenantId, tokens })`
* after every successful AI call increments
* `ai_tokens_consumed_total{provider, model, tenant_bucket}`.
*
* Cardinality strategy (deviation from spec acceptable per detail-MD §10):
*
* - The label is **tenant_bucket**, NOT tenant_id. The bucket is an opaque
* string. Today: the literal tenant id when known, "anonymous" otherwise.
* - A cap (`MAX_TENANT_BUCKETS`, default 100) keeps the unique label values
* bounded. The first 100 distinct tenant ids observed become buckets
* one-to-one; subsequent tenants are folded into the synthetic `"other"`
* bucket. The bucket-set lives in a process-local LRU map and resets on
* process restart. This matches the detail-MD acceptance criterion
* "tenant_id-Bucketing dokumentiert" and prevents the documented
* cardinality-explosion failure mode (a malicious user spamming new
* tenant ids).
* - When operators want raw per-tenant figures, they query the DB
* aggregate (already populated by `createCredit`) — Prometheus is for
* real-time, the DB is for accounting.
*/
import { getWebMetrics } from "./registry.js";
const MAX_TENANT_BUCKETS = 100;
const OTHER_BUCKET = "other";
const ANONYMOUS_BUCKET = "anonymous";
const trackedTenantBuckets = new Set<string>();
export type RecordAiTokensConsumedInput = {
provider: string;
model: string;
tenantId: string | null | undefined;
tokens: number;
};
export function recordAiTokensConsumed(input: RecordAiTokensConsumedInput): void {
const tokens = Number.isFinite(input.tokens) && input.tokens > 0 ? Math.round(input.tokens) : 0;
if (tokens <= 0) {
return;
}
const bucket = resolveTenantBucket(input.tenantId);
try {
getWebMetrics().metrics.aiTokensConsumedTotal
.labels({ provider: sanitizeLabel(input.provider), model: sanitizeLabel(input.model), tenant_bucket: bucket })
.inc(tokens);
} catch {
// Metric writes never fail business code.
}
}
/**
* Test-only — clears the tenant-bucket LRU so each test sees a clean slate.
*/
export function resetAiCostBucketsForTests(): void {
trackedTenantBuckets.clear();
}
function resolveTenantBucket(tenantId: string | null | undefined): string {
if (!tenantId) {
return ANONYMOUS_BUCKET;
}
const sanitised = sanitizeLabel(tenantId);
if (trackedTenantBuckets.has(sanitised)) {
return sanitised;
}
if (trackedTenantBuckets.size < MAX_TENANT_BUCKETS) {
trackedTenantBuckets.add(sanitised);
return sanitised;
}
return OTHER_BUCKET;
}
function sanitizeLabel(value: string): string {
// Prom label values are arbitrary UTF-8 but must not exceed reasonable
// bounds. Truncate to 128 chars and drop control characters.
const cleaned = value.replace(/[\x00-\x1f\x7f]/g, "").slice(0, 128);
return cleaned || "unknown";
}
@@ -0,0 +1,43 @@
/**
* Web (SSR) service-scoped Prometheus registry singleton.
*
* The web process serves both UI HTML and a couple of resource routes —
* `/api/status` and `/api/metrics` — so it gets its own service-tagged
* registry. Mirrors apps/api/src/metrics.ts.
*/
import { createDefaultMetrics, createMetricsRegistry, type DefaultMetrics, type MetricsRegistry } from "@toolctrl/metrics";
import { setEnqueueObserver } from "@toolctrl/queue";
type WebMetricsBundle = {
registry: MetricsRegistry;
metrics: DefaultMetrics;
};
let cached: WebMetricsBundle | undefined;
export function getWebMetrics(): WebMetricsBundle {
if (!cached) {
cached = buildWebMetrics();
}
return cached;
}
export function resetWebMetricsForTests(): void {
cached = undefined;
}
function buildWebMetrics(): WebMetricsBundle {
const revision = process.env.APP_REVISION?.trim() ?? "";
const registry = createMetricsRegistry({
serviceName: "web",
collectDefaultProcessMetrics: true,
...(revision ? { defaultLabels: { revision } } : {}),
});
const metrics = createDefaultMetrics(registry);
// Wire BullMQ enqueue events into queue_jobs_enqueued_total. See
// apps/api/src/metrics.ts for the same wiring.
setEnqueueObserver((event) => {
metrics.queueJobsEnqueuedTotal.labels({ queue: event.queueName, priority: event.priorityLabel }).inc();
});
return { registry, metrics };
}
@@ -0,0 +1,60 @@
import { describe, it, expect, beforeEach } from "vitest";
import { resetWebMetricsForTests, getWebMetrics } from "./registry.js";
import { withMetrics } from "./ssr.js";
beforeEach(() => {
resetWebMetricsForTests();
});
describe("withMetrics", () => {
it("passes through and is a no-op when metrics are disabled", async () => {
const loader = withMetrics("root", async () => "value", { enabledOverride: false });
expect(await loader({})).toBe("value");
const text = await getWebMetrics().registry.metrics();
expect(text).not.toContain('web_ssr_loader_duration_seconds_count{route="root"');
});
it("observes loader latency with route + status=ok", async () => {
let t = 0;
const loader = withMetrics(
"dashboard",
async () => ({ ok: true }),
{
enabledOverride: true,
now: () => {
const next = t;
t += 80; // 80ms — should hit the 0.1 bucket
return next;
},
},
);
await loader({});
const text = await getWebMetrics().registry.metrics();
expect(text).toMatch(/web_ssr_loader_duration_seconds_count\{[^}]*route="dashboard"[^}]*status="ok"[^}]*\} 1/);
expect(text).toMatch(/web_ssr_loader_duration_seconds_bucket\{le="0.1",[^}]*route="dashboard"[^}]*status="ok"[^}]*\} 1/);
});
it("labels redirect responses as status=redirect", async () => {
const loader = withMetrics(
"login",
async () => new Response(null, { status: 302, headers: { location: "/dashboard" } }),
{ enabledOverride: true },
);
await loader({});
const text = await getWebMetrics().registry.metrics();
expect(text).toMatch(/web_ssr_loader_duration_seconds_count\{[^}]*route="login"[^}]*status="redirect"[^}]*\} 1/);
});
it("labels thrown loaders as status=error and re-throws", async () => {
const loader = withMetrics(
"fail",
async () => {
throw new Error("boom");
},
{ enabledOverride: true },
);
await expect(loader({})).rejects.toThrow("boom");
const text = await getWebMetrics().registry.metrics();
expect(text).toMatch(/web_ssr_loader_duration_seconds_count\{[^}]*route="fail"[^}]*status="error"[^}]*\} 1/);
});
});
@@ -0,0 +1,74 @@
/**
* `withMetrics(routeId, loader)` — wraps a React Router v7 SSR loader so each
* invocation observes `web_ssr_loader_duration_seconds_bucket{route, status}`.
*
* Apply it to the **highest-traffic** loaders only (root, dashboard, login,
* tenant index, etc.) — wrapping every loader would multiply boilerplate
* without paying off in extra signal. Operators can extend coverage later if
* we identify hotspots.
*
* Self-noop when `METRICS_ENABLED=false` so dev runs stay zero-overhead.
*/
import { isMetricsEnabled } from "@toolctrl/metrics";
import { getWebMetrics } from "./registry.js";
type AnyLoaderArgs = {
request?: Request;
params?: Record<string, string | undefined>;
context?: unknown;
};
export type SsrLoader<TArgs extends AnyLoaderArgs = AnyLoaderArgs, TResult = unknown> = (args: TArgs) => Promise<TResult> | TResult;
export type WithMetricsOptions = {
/** Override the time source — tests inject a deterministic clock. */
now?: () => number;
/** Override the `METRICS_ENABLED` check — tests force enabled=true. */
enabledOverride?: boolean;
};
export function withMetrics<TArgs extends AnyLoaderArgs, TResult>(
routeId: string,
loader: SsrLoader<TArgs, TResult>,
options: WithMetricsOptions = {},
): SsrLoader<TArgs, TResult> {
return async function wrappedLoader(args: TArgs): Promise<TResult> {
const enabled = options.enabledOverride ?? isMetricsEnabled(process.env);
if (!enabled) {
return loader(args);
}
const now = options.now ?? (() => performance.now());
const started = now();
let status: "ok" | "error" | "redirect" = "ok";
try {
const result = await loader(args);
status = classifyStatus(result);
return result;
} catch (error) {
status = "error";
throw error;
} finally {
const elapsedSeconds = (now() - started) / 1000;
try {
getWebMetrics().metrics.webSsrLoaderDurationSeconds.labels({ route: routeId, status }).observe(elapsedSeconds);
} catch {
// Metric writes never break loader execution.
}
}
};
}
/**
* Inspects the loader return value for a Response that signals redirect /
* client error. React Router treats thrown Response objects as the loader's
* error path (handled in catch block), so anything returned here counts as
* "ok" unless the status is a redirect.
*/
function classifyStatus(result: unknown): "ok" | "redirect" {
if (result instanceof Response) {
if (result.status >= 300 && result.status < 400) {
return "redirect";
}
}
return "ok";
}