Observability Events Attribution

1// Observability Events is the metered SKU under Observability Plus.
2// Threshold at >20% surfaces material spend; >30% is the critical band.
3// Drivers correlate with low cache hit rate, high middleware invocation, and high custom-span cardinality.
4export const metadata = {
5  id: 'observability_events_attribution',
6  threshold: 'observabilityEventsShare > 0.20 (critical at > 0.30)',
7  billingDimension: 'observability-events',
8  scope: 'account',
9  sourceCitation: 'vercel-optimize gate threshold',
10  description:
11    'Observability Events line item exceeds 20% of total billed cost. High share usually traces to low cache hit rate, middleware-heavy traffic, or unconstrained custom-span cardinality. No sampling lever exists for Observability Plus; reduce upstream invocations instead.',
12};
13
14const EVENTS_RE = /^Observability Events$/i;
15
16export function gate(signals) {
17  const services = signals?.usage?.services;
18  if (!Array.isArray(services) || services.length === 0) return [];
19
20  const total = sumBilled(services);
21  if (total <= 0) return [];
22
23  const eventsBilled = services
24    .filter((s) => EVENTS_RE.test(String(s?.name ?? '')))
25    .reduce((acc, s) => acc + Number(s.billedCost ?? s.cost ?? 0), 0);
26  if (eventsBilled <= 0) return [];
27
28  const share = eventsBilled / total;
29  if (share <= 0.20) return [];
30
31  const critical = share > 0.30;
32
33  return [{
34    kind: metadata.id,
35    scope: 'account',
36    files: [],
37    priority: critical ? 70 : 55,
38    confidence: 0.82,
39    o11ySignal: `observability_events_share=${(share * 100).toFixed(0)}%`,
40    reason: critical
41      ? 'observability events exceed 30% of total billed cost'
42      : 'observability events exceed 20% of total billed cost',
43    question: `Observability Events are ${(share * 100).toFixed(0)}% of the bill. Which routes drive event volume — low-cache-hit traffic, broad middleware invocation, or high custom-span cardinality — and can event volume be reduced upstream of the meter?`,
44    evidence: {
45      metric: 'usage.services',
46      eventsBilled,
47      totalBilled: total,
48      observabilityEventsShare: share,
49      critical,
50    },
51  }];
52}
53
54function sumBilled(services) {
55  return services.reduce((acc, s) => acc + Number(s.billedCost ?? s.cost ?? 0), 0);
56}