Measuring & profiling

You can't fix what you haven't measured, and lab numbers from your laptop aren't what users get. This sheet covers lab vs field data, Chrome DevTools, Lighthouse and friends, the browser's Performance APIs, collecting your own real-user data (RUM), and budgets that keep a site fast. The metrics themselves are on Core Web Vitals.

Lab vs field

They disagree, and that's normal. Lab runs a cold cache on one emulated device. Field data includes warm caches, bfcache restores and prerendering (faster), plus slow phones, bad networks, third-party tags that only load for real users, and long sessions (slower). Use field data to find what is slow and lab tools to find why.

Chrome DevTools: Performance panel

Reading the Main track (flame chart):

Width is time; the stack below a bar is what it called. Click a bar → Summary / Bottom-up to find the functions that took the most self-time. Enable "Advanced paint instrumentation" only when you need paint details: it slows the page.

Other panels: Network (waterfall, priorities, initiators; right-click headers to add "Priority"), Coverage (unused JS/CSS), Memory (heap snapshots), Rendering tab (paint flashing, layout shift regions, layer borders, emulate prefers-reduced-motion), Lighthouse.

Lighthouse & PageSpeed Insights

• Lighthouse 13 (October 2025) reorganized its audits into the same insights the DevTools Performance panel shows; the score weights didn't change.
• The score is a lab score from one emulated mid-range phone on a throttled connection. It's for comparisons, not a verdict; Google Search ranking uses field Core Web Vitals, not this score.
• Scores vary ±5 between runs: run 3–5 times and take the median, and close other tabs and extensions (or use an incognito window).
• PageSpeed Insights = CrUX field data for the URL and origin (top) + a Lighthouse run from Google's servers (bottom).

bunx lighthouse https://example.com \
  --only-categories=performance \
  --output=html --output-path=./report.html --view
# desktop profile
bunx lighthouse https://example.com --preset=desktop

WebPageTest (now part of Catchpoint; free runs still work at webpagetest.org) runs real browsers on real devices in many locations: filmstrips, video comparisons, connection views, and "experiments" that test a fix (e.g. adding a preload) without deploying it.

Performance APIs

const po = new PerformanceObserver((list) => {
  for (const entry of list.getEntries()) {
    console.log(entry.entryType, entry.name, entry.duration);
  }
});
po.observe({ type: "resource", buffered: true });

• Use type + buffered: true (one type per observe() call). The older entryTypes: [...] form can't use buffered.
• PerformanceObserver.supportedEntryTypes lists what the browser supports.
• TTFB from Navigation Timing: responseStart (relative to navigation start). For prerendered pages, subtract activationStart. With 103 Early Hints, responseStart marks the 103; the final response's headers are at finalResponseHeadersStart (where supported).

Server-Timing: db;dur=53;desc="orders query"
Server-Timing: render;dur=12, cache;desc="HIT"

Server-Timing is visible to anyone who loads the page. Don't expose internal hostnames, query text or user data; keep it coarse, or enable it only for staff and staging.

Real-user monitoring (RUM)

• Sample high-traffic sites (e.g. 10% of sessions); report every metric from a sampled session.
• Don't send on unload (unreliable, and it breaks the bfcache).
• Percentiles, not averages: an average hides the slow tail that CWV judges.

Budgets & CI

A performance budget is a limit the build isn't allowed to exceed: bytes (JS ≤ 170 KB transferred on the critical path), counts (≤ 3 third-party origins) or metrics (LCP ≤ 2.5 s in the lab on a throttled phone). Check it on every pull request.

{
  "ci": {
    "collect": {
      "url": ["http://localhost:3000/"],
      "startServerCommand": "bun run start",
      "numberOfRuns": 3
    },
    "assert": {
      "assertions": {
        "largest-contentful-paint": ["error", {
          "maxNumericValue": 2500,
          "aggregationMethod": "median-run"
        }],
        "cumulative-layout-shift": ["error", {
          "maxNumericValue": 0.1,
          "aggregationMethod": "median-run"
        }],
        "total-blocking-time": ["warn", {
          "maxNumericValue": 200,
          "aggregationMethod": "median-run"
        }],
        "resource-summary:script:size": ["error", {
          "maxNumericValue": 170000
        }]
      }
    },
    "upload": {
      "target": "filesystem",
      "outputDir": ".lighthouseci"
    }
  }
}

"aggregationMethod": "median-run" checks the median run; the default (optimistic) passes if the best run passes. The temporary-public-storage upload target publishes reports at a public URL: fine for open source, not for private or staging sites.

bunx @lhci/cli autorun

@lhci/cli 0.15 still bundles Lighthouse 12, so assert on classic audit ids (like the ones above), not Lighthouse 13 insight names. Bundle-size budgets are cheaper and more stable than lab metrics: size-limit fails the build when a bundle grows past its limit.

Test conditions

Common mistakes

Recipes

Time a function with a measure

Shows in the DevTools Performance panel's Timings track, and can be read back in code. Numeric start and end times keep overlapping calls with the same name apart.

export async function timed<T>(
  name: string,
  fn: () => Promise<T>,
): Promise<T> {
  const start = performance.now();
  try {
    return await fn();
  } finally {
    performance.measure(name, {
      start,
      end: performance.now(),
    });
  }
}
 
const rows = await timed("load-rows", () => fetchRows());

Server-Timing from Hono

Time the database and render steps and expose them in the Network panel's Timing tab.

import { Hono } from "hono";
import { timing, startTime, endTime } from "hono/timing";
 
const app = new Hono();
// allow-list: off unless explicitly on (fails closed)
app.use(timing({
  enabled: (c) => c.env?.STAGE === "staging",
}));
 
app.get("/orders", async (c) => {
  startTime(c, "db", "orders query");
  const orders = await db.orders.list();
  endTime(c, "db");
  return c.json(orders);
});
 
export default app;

Find the scripts behind slow frames

Long Animation Frames name the script, function and source position that blocked the frame (Chromium).

interface LoAFScript {
  duration: number;
  invoker: string;
  sourceURL: string;
  sourceFunctionName: string;
}
interface LoAF extends PerformanceEntry {
  blockingDuration: number;
  scripts: LoAFScript[];
}
 
new PerformanceObserver((list) => {
  for (const entry of list.getEntries()) {
    const frame = entry as LoAF;
    if (frame.blockingDuration < 100) continue;
    for (const s of frame.scripts) {
      console.log(Math.round(s.duration), s.invoker,
        s.sourceURL, s.sourceFunctionName);
    }
  }
}).observe({ type: "long-animation-frame", buffered: true });
 
// lib.dom has no LoAF types yet, hence the interfaces

TTFB breakdown for the current page

Where the time before the first byte went.

const [nav] = performance.getEntriesByType(
  "navigation",
) as PerformanceNavigationTiming[];
 
console.table({
  redirect: nav.redirectEnd - nav.redirectStart,
  dns: nav.domainLookupEnd - nav.domainLookupStart,
  connect: nav.connectEnd - nav.connectStart,
  tls: nav.secureConnectionStart
    ? nav.connectEnd - nav.secureConnectionStart : 0,
  waiting: nav.responseStart - nav.requestStart,
  ttfb: nav.responseStart,
});

References

• MDN: Web performance (opens in a new tab), Performance APIs (opens in a new tab), User timing (opens in a new tab), Navigation timing (opens in a new tab), Resource timing (opens in a new tab)
• MDN: PerformanceObserver (opens in a new tab), PerformanceLongAnimationFrameTiming (opens in a new tab), Server-Timing (opens in a new tab), Timing-Allow-Origin (opens in a new tab), navigator.sendBeacon() (opens in a new tab)
• Chrome for Developers: Performance panel (opens in a new tab), Performance features reference (opens in a new tab), Lighthouse performance scoring (opens in a new tab), Long Animation Frames API (opens in a new tab)
• web.dev: Lab and field data (opens in a new tab), Performance budgets 101 (opens in a new tab), Custom metrics (opens in a new tab)
• Tools: PageSpeed Insights (opens in a new tab), WebPageTest (opens in a new tab), Lighthouse CI (opens in a new tab), size-limit (opens in a new tab), Hono timing middleware (opens in a new tab)