lib/queries.mjs
GitHub// Declarative metric-query registry. Single source for every `vercel metrics ...` call.
//
// CLI default --since is 1h. Mixing 1h with 14d windows silently produces incompatible rollups — every query MUST pass since: TIME_WINDOW. test/time-window.test.mjs enforces this.
// 14d: long enough for weekly cycles, short enough to surface recent regressions before stale data dilutes them.
import { normalizeSummary } from './vercel.mjs';
export const TIME_WINDOW = '14d';
// CLI default cardinality cap is 10 — too small for a typical app.
const ROUTE_LIMIT = 200;
const HOST_LIMIT = 50;
const DIM_LIMIT = 50;
// CLI emits value under `<metric_id_with_underscores>_<aggregation>` (e.g. `vercel_request_count_sum`).
function defaultNormalize(metricId, aggregation, groupBy) {
return (resp) => ({ rows: normalizeSummary(resp, metricId, aggregation, groupBy) });
}
// Collapse (route × function_start_type) rows into one row per route. Observed values: "cold", "hot", "prewarmed".
function normalizeColdStart(metricId, aggregation) {
return (resp) => {
const rows = normalizeSummary(resp, metricId, aggregation, ['route', 'function_start_type']);
const byRoute = new Map();
for (const r of rows) {
if (!r.route) continue;
const prior = byRoute.get(r.route) ?? { route: r.route, total: 0, coldCount: 0, warmCount: 0, prewarmedCount: 0 };
const v = r.value ?? 0;
prior.total += v;
if (r.function_start_type === 'cold') prior.coldCount += v;
else if (r.function_start_type === 'hot') prior.warmCount += v;
else if (r.function_start_type === 'prewarmed') prior.prewarmedCount += v;
byRoute.set(r.route, prior);
}
return {
rows: [...byRoute.values()].map((r) => ({
...r,
coldPct: r.total > 0 ? r.coldCount / r.total : 0,
})),
};
};
}
export const QUERIES = [
{
id: 'requestsByRouteCache',
metricId: 'vercel.request.count',
aggregation: 'sum',
groupBy: ['route', 'cache_result'],
limit: ROUTE_LIMIT,
description: 'Request count per route × cache_result. Source of cache hit rate; total invocations folds across cache_result.',
},
{
id: 'fnDurationP95ByRoute',
metricId: 'vercel.function_invocation.function_duration_ms',
aggregation: 'p95',
groupBy: ['route'],
limit: ROUTE_LIMIT,
description: 'p95 wall-clock function duration per route. Canonical slow-route signal.',
},
{
id: 'requestsByRouteStatus',
metricId: 'vercel.request.count',
aggregation: 'sum',
groupBy: ['route', 'http_status'],
limit: ROUTE_LIMIT,
description: 'Request count per route × http_status. Compatibility fallback for older route_errors fixtures.',
},
{
id: 'fnStatusByRoute',
metricId: 'vercel.function_invocation.count',
aggregation: 'sum',
groupBy: ['route', 'http_status'],
limit: ROUTE_LIMIT,
description: 'Function invocation count per route × http_status. Canonical 5xx source for slow_route disqualification and route_errors.',
},
{
id: 'requestsByRouteMethod',
metricId: 'vercel.request.count',
aggregation: 'sum',
groupBy: ['route', 'request_method'],
limit: ROUTE_LIMIT,
description: 'Request count per route × request_method. Uncached_route gate uses this to skip mostly-POST routes (Server Actions, mutations) where 0% cache is correct behavior.',
},
{
id: 'externalApiP75',
metricId: 'vercel.external_api_request.request_duration_ms',
aggregation: 'p75',
groupBy: ['origin_hostname'],
limit: HOST_LIMIT,
description: 'p75 external API duration per origin hostname.',
},
{
id: 'fnStartTypeByRoute',
metricId: 'vercel.function_invocation.count',
aggregation: 'sum',
groupBy: ['route', 'function_start_type'],
limit: ROUTE_LIMIT,
description: 'Function invocation count split by cold | hot | prewarmed. Feeds cold_start gate.',
normalizer: normalizeColdStart('vercel.function_invocation.count', 'sum'),
},
{
id: 'fnGbHrByRoute',
metricId: 'vercel.function_invocation.function_duration_gbhr',
aggregation: 'sum',
groupBy: ['route'],
limit: ROUTE_LIMIT,
description: 'Billed GB-hours per route (function duration in Fluid billing).',
},
{
id: 'fnCpuMsByRoute',
metricId: 'vercel.function_invocation.function_cpu_time_ms',
aggregation: 'sum',
groupBy: ['route'],
limit: ROUTE_LIMIT,
description: 'Active CPU time per route. Fluid Compute bills on this; high CPU = expensive route.',
},
{
id: 'fnPeakMemoryByRoute',
metricId: 'vercel.function_invocation.peak_memory_mb',
aggregation: 'max',
groupBy: ['route'],
limit: ROUTE_LIMIT,
description: 'Peak memory observed per route. Compared against provisioned to right-size.',
},
{
id: 'fnProvisionedMemoryByRoute',
metricId: 'vercel.function_invocation.provisioned_memory_mb',
aggregation: 'max',
groupBy: ['route'],
limit: ROUTE_LIMIT,
description: 'Provisioned memory per route. Feeds oversized_memory gate.',
},
{
id: 'fnTtfbP95ByRoute',
metricId: 'vercel.function_invocation.ttfb_ms',
aggregation: 'p95',
groupBy: ['route'],
limit: ROUTE_LIMIT,
description: 'Server-measured time-to-first-byte per route. Complements function_duration_ms p95.',
},
{
id: 'fdtByRoute',
metricId: 'vercel.request.fdt_total_bytes',
aggregation: 'sum',
groupBy: ['route'],
limit: ROUTE_LIMIT,
description: 'Fast Data Transfer bytes per route. Bandwidth cost driver.',
},
{
id: 'fdtByBot',
metricId: 'vercel.request.fdt_total_bytes',
aggregation: 'sum',
groupBy: ['bot_category'],
limit: DIM_LIMIT,
description: 'FDT bytes by bot category. Empty `bot_category` = human traffic; non-empty = bots.',
},
{
id: 'fdtByCache',
metricId: 'vercel.request.fdt_total_bytes',
aggregation: 'sum',
groupBy: ['cache_result'],
limit: DIM_LIMIT,
description: 'FDT bytes by cache_result. Uncached vs cached bandwidth.',
},
{
id: 'middlewareCount',
metricId: 'vercel.middleware_invocation.count',
aggregation: 'sum',
groupBy: ['request_path'],
limit: ROUTE_LIMIT,
description: 'Middleware invocations per request_path. Heavy middleware traffic = missing matcher.',
},
{
id: 'middlewareDurationP95',
metricId: 'vercel.middleware_invocation.duration_ms',
aggregation: 'p95',
groupBy: ['request_path'],
limit: ROUTE_LIMIT,
description: 'p95 middleware duration per request_path.',
},
{
id: 'isrReadsByRoute',
metricId: 'vercel.isr_operation.read_units',
aggregation: 'sum',
groupBy: ['route'],
limit: ROUTE_LIMIT,
description: 'ISR read units per route. Healthy when high relative to writes.',
},
{
id: 'isrWritesByRoute',
metricId: 'vercel.isr_operation.write_units',
aggregation: 'sum',
groupBy: ['route'],
limit: ROUTE_LIMIT,
description: 'ISR write units per route. High writes/reads = over-aggressive revalidate.',
},
{
id: 'imageCount',
metricId: 'vercel.image_transformation.count',
aggregation: 'sum',
groupBy: [],
limit: 1,
description: 'Total image transformations performed.',
},
{
id: 'imageByHost',
metricId: 'vercel.image_transformation.count',
aggregation: 'sum',
groupBy: ['source_image_hostname'],
limit: HOST_LIMIT,
description: 'Image transformations per source hostname. Identify which hosts dominate the bill.',
},
{
id: 'imageSourceBytes',
metricId: 'vercel.image_transformation.source_size_bytes',
aggregation: 'sum',
groupBy: [],
limit: 1,
description: 'Bytes of source images optimized. High = ingress bandwidth cost.',
},
{
id: 'cwvLcpByRoute',
metricId: 'vercel.speed_insights_metric.lcp',
aggregation: 'p75',
groupBy: ['route'],
limit: ROUTE_LIMIT,
description: 'p75 Largest Contentful Paint per route. > 2500ms = poor.',
},
{
id: 'cwvInpByRoute',
metricId: 'vercel.speed_insights_metric.inp',
aggregation: 'p75',
groupBy: ['route'],
limit: ROUTE_LIMIT,
description: 'p75 Interaction to Next Paint per route. > 200ms = poor.',
},
{
id: 'cwvClsByRoute',
metricId: 'vercel.speed_insights_metric.cls',
aggregation: 'p75',
groupBy: ['route'],
limit: ROUTE_LIMIT,
description: 'p75 Cumulative Layout Shift per route. > 0.1 = poor.',
},
{
id: 'cwvTtfbByRoute',
metricId: 'vercel.speed_insights_metric.ttfb_ms',
aggregation: 'p75',
groupBy: ['route'],
limit: ROUTE_LIMIT,
description: 'p75 client-measured TTFB per route.',
},
{
id: 'cwvCount',
metricId: 'vercel.speed_insights_metric.count',
aggregation: 'sum',
groupBy: [],
limit: 1,
description: 'Total Speed Insights measurements. Use to decide whether CWV gates have enough signal.',
},
{
id: 'cwvCountByRoute',
metricId: 'vercel.speed_insights_metric.count',
aggregation: 'sum',
groupBy: ['route'],
limit: ROUTE_LIMIT,
description: 'Speed Insights measurements per route. CWV route gates require at least 50 samples on the specific route.',
},
{
id: 'firewallByAction',
metricId: 'vercel.firewall_action.count',
aggregation: 'sum',
groupBy: ['waf_action'],
limit: DIM_LIMIT,
description: 'Firewall action count per waf_action (allow | challenge | block | log).',
},
{
id: 'botIdChecks',
metricId: 'vercel.bot_id_check.count',
aggregation: 'sum',
groupBy: [],
limit: 1,
description: 'Total BotID checks. > 0 confirms BotID is wired up; = 0 confirms it is not.',
},
{
id: 'externalApiCount',
metricId: 'vercel.external_api_request.count',
aggregation: 'sum',
groupBy: ['origin_hostname'],
limit: HOST_LIMIT,
description: 'External API call count per origin hostname.',
},
{
id: 'externalApiBytes',
metricId: 'vercel.external_api_request.transfer_bytes',
aggregation: 'sum',
groupBy: ['origin_hostname'],
limit: HOST_LIMIT,
description: 'Outbound bytes per external API hostname.',
},
];
export function normalizerFor(entry) {
if (entry.normalizer) return entry.normalizer;
return defaultNormalize(entry.metricId, entry.aggregation, entry.groupBy);
}