Metric Cardinality Guard

Estimates the series a metric will produce and flags labels that are unbounded by construction, before they ship.

THE SILENT FAILURE. A metric label whose values are unbounded -- a user id, request id, a URL path with ids in it, an error message -- creates a NEW TIME SERIES per distinct value. The code looks ordinary; one line adds a label. Nothing errors in development, where there are five users. In production it becomes millions of series, and the failure arrives as a bill an order of magnitude over budget, or the backend silently DROPPING series past a limit -- which means dashboards and alerts quietly stop covering part of your traffic. An alert that no longer fires looks exactly like an alert with nothing to report.

It flags the patterns that are unbounded by construction -- ids, UUIDs, timestamps, emails, IPs, paths with numeric segments, free-text errors -- and estimates TOTAL series as the PRODUCT across labels, because the multiplicative blow-up is what people underestimate: three labels of a hundred values each is a million series, not three hundred.

Where a label's true cardinality cannot be known from the sample it says UNKNOWN rather than extrapolating. A confident wrong estimate is worse than none, because it gets written into a budget.

A path-templating helper turns /users/12345/orders/678 into /users/{id}/orders/{id}, so the most common cause is fixable rather than merely detectable. Budgets are checked with the arithmetic shown, so nobody has to trust the tool. It analyses what you supply and never connects to a metrics backend.

VERIFIED: 103 tests. Every mutation was observed FAILING before the source was restored -- a test never seen to fail is a decoration. Independently reviewed by a verifier whose job was to find what is wrong, not to agree.

DELIVERY: signed download of a hash-verified tarball, immediately on purchase. Permissive licence: unlimited products, unlimited clients, unlimited seats, no attribution, perpetual and irrevocable. One restriction, do not republish the source as source.

Interface

What you call, and what comes back. Types and signatures only — the implementation ships with the source.

  export function estimateTotalSeries(labels: LabelCardinality[]): TotalSeriesEstimate;
  export function checkBudget(totalSeries: TotalSeriesEstimate, budget: number): BudgetCheck;
  export function analyzeMetric( metric: MetricDefinition, samples: LabelSamples, options?: AnalyzeMetricOptions, ): MetricCardinalityReport;
  export function analyzeCatalog( metrics: MetricDefinition[], samplesByMetric: Record<string, LabelSamples>, options?: AnalyzeMetricOptions, ): MetricCardinalityReport[];
  export function reportsNeedingAttention( reports: MetricCardinalityReport[], ): MetricCardinalityReport[];
  export function estimateLabelCardinality( label: string, values: string[], thresholds?: Partial<CardinalityThresholds>, ): LabelCardinality;
  export function isUuid(value: string): boolean;
  export function isEmail(value: string): boolean;
  export function isIpAddress(value: string): boolean;
  export function isTimestamp(value: string): boolean;
  export function isAllDigits(value: string): boolean;
  export function isNumericId(value: string, minDigits: number): boolean;

  export type LabelSamples = Record<string, string[]>;
  export type TotalSeriesKind = "known" | "unknown-lower-bound";
  export type BudgetStatus = "within-budget" | "over-budget" | "unknown-unbounded";