/** * 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(); 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"; }