Reorganize repo structure and standards references
This commit is contained in:
1 parent
3cb93a81be
commit
be2054274d
5885 files changed
+2588
-195
No files matched your search
@@ -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";
|
||||
}
|
||||
Reference in new issue
Block a user