Cold Start

1// Signal: `function_start_type` dimension on `vercel.function_invocation.count` (cold|hot|prewarmed).
2// Threshold WHY: 40%+ cold is fixable via Fluid keep-warm; 30% is the noise floor for serverless without keep-warm.
3// total>=1000/14d (~3/hr) keeps Poisson CI on cold rate at ~±5% near the 40% threshold.
4export const metadata = {
5  id: 'cold_start',
6  threshold: 'coldPct > 0.4 AND total >= 1000',
7  billingDimension: 'function-duration',
8  scope: 'route',
9  sourceCitation: 'vercel-optimize gate threshold',
10  description:
11    'Routes where > 40% of invocations are cold-start, at meaningful traffic (>=1,000 total invocations in window). Cold starts add 200-800ms per request and break the perceived latency budget on cache-miss paths. The 40% threshold is where cold-rate becomes a real signal vs Poisson noise on serverless. Sourced from vercel.function_invocation.count grouped by function_start_type.',
12};
13
14export function gate(signals) {
15  const cs = extractColdStarts(signals);
16  return cs
17    .filter((r) => r.coldPct > 0.4 && r.total >= 1000)
18    .map((r) => ({
19      kind: metadata.id,
20      scope: 'route',
21      route: r.route,
22      files: [],
23      priority: Math.round(r.total * r.coldPct),
24      confidence: 0.92,
25      o11ySignal: `cold=${(r.coldPct * 100).toFixed(0)}%,inv=${r.total}`,
26      reason: 'high cold-start rate on hot route',
27      question: `What initialization or bundle overhead makes ${r.route} cold-start ${(r.coldPct * 100).toFixed(0)}% of ${r.total} invocations?`,
28      evidence: { metric: 'fnStartTypeByRoute', route: r.route, coldPct: r.coldPct, total: r.total, coldCount: r.coldCount ?? null },
29    }));
30}
31
32function extractColdStarts(signals) {
33  const live = signals.metrics?.fnStartTypeByRoute;
34  if (Array.isArray(live?.rows) && live.rows.some((r) => 'coldCount' in r || 'coldPct' in r)) {
35    return live.rows
36      .filter((r) => r.route)
37      .map((r) => ({
38        route: r.route,
39        total: r.total ?? 0,
40        coldCount: r.coldCount ?? 0,
41        coldPct: r.coldPct ?? 0,
42      }));
43  }
44
45  // Legacy fixture: pre-derived coldStartByRoute rows.
46  const direct = signals.metrics?.coldStartByRoute;
47  if (Array.isArray(direct?.rows)) {
48    return direct.rows
49      .filter((r) => r.route)
50      .map((r) => ({ route: r.route, coldPct: r.coldPct ?? 0, total: r.total ?? 0 }));
51  }
52
53  // Older legacy fixture: series + summary shape.
54  const legacy = signals.metrics?.coldStarts;
55  if (Array.isArray(legacy?.series)) {
56    return legacy.series
57      .map((s) => {
58        const total = s.summary?.count ?? 0;
59        const coldCount = s.summary?.coldCount ?? s.summary?.sum ?? 0;
60        return { route: s.groupValues?.route, total, coldPct: total > 0 ? coldCount / total : 0 };
61      })
62      .filter((r) => r.route);
63  }
64
65  return [];
66}