Measuring performance

Measure before you make it fast

Professional JavaScript performance work starts with evidence. A slow feeling might come from network latency, parser work, a long task, layout, a third-party script, or a benchmark that never matched production. Guessing wastes time and can make the page feel worse.

Keep the scope clear. This lesson teaches measurement: User Timing, DevTools traces, flame charts, RUM, and benchmark traps. The next lesson, Keeping the main thread responsive, goes deeper on long tasks, INP, and yielding. Later lessons cover debounce and throttle, rendering performance, loading performance, and memory leaks.

If you need a refresher on tool basics, revisit Debugging in the browser, Advanced debugging, Observers, Page lifecycle, and the event loop.

Premature optimization often starts with the wrong number. Average response time can look fine while a meaningful slice of users waits. Percentiles answer a different question: “What value did 50%, 75%, or 95% of samples stay under?” Product teams often watch p75 for Core Web Vitals-style decisions and p95 for the slow tail.

1const responseTimes = [120, 80, 1000, 160, 240];2 3function percentile(values, p) {4  if (values.length === 0) throw new RangeError("percentile needs values");5  const sorted = [...values].sort((a, b) => a - b);6  const rank = Math.ceil((p / 100) * sorted.length);7  const index = Math.min(sorted.length - 1, Math.max(0, rank - 1));8  return sorted[index];9}10 11const average = responseTimes.reduce((total, value) => total + value, 0) / responseTimes.length;12console.log("average", average);13console.log("p50", percentile(responseTimes, 50));14console.log("p75", percentile(responseTimes, 75));15console.log("p95", percentile(responseTimes, 95));

Read it line by line. Line 5 sorts a copy, so the original list stays untouched. Line 6 turns the percentile into a 1-based rank. Line 7 converts that rank to a safe array index. Line 8 returns the value at that index. In this sample, the average is 320 ms, but p75 is 240 ms and p95 is 1000 ms, so the slow tail is impossible to miss.

1const responseTimes = [120, 80, 1000, 160, 240];Run2 3function percentile(values, p) {4  if (values.length === 0) throw new RangeError("percentile needs values");5  const sorted = [...values].sort((a, b) => a - b);6  const rank = Math.ceil((p / 100) * sorted.length);7  const index = Math.min(sorted.length - 1, Math.max(0, rank - 1));8  return sorted[index];9}10 11const average = responseTimes.reduce((total, value) => total + value, 0) / responseTimes.length;12console.log("average", average);13console.log("p50", percentile(responseTimes, 50));14console.log("p75", percentile(responseTimes, 75));15console.log("p95", percentile(responseTimes, 95));

Use performance.now() for elapsed time. It is monotonic, high-resolution, and relative to the page time origin. Browsers coarsen precision for security: a normal non-isolated Chrome 154 page in this environment advanced in 0.1 ms steps, while cross-origin isolated pages can expose finer resolution around 5 microseconds. Treat those figures as browser policy, not a promise.

1let wallClock = 1000;2const DateNow = () => wallClock;3 4const started = DateNow();5wallClock -= 50; // user or OS adjusts the clock backward6const elapsed = DateNow() - started;7 8console.log(elapsed);9console.log("performance.now is monotonic instead");

Date.now() reads the wall clock. If the user, operating system, or virtual machine changes that clock, elapsed time can become negative. performance.now() is the right stopwatch. User Timing adds labels: performance.mark() for named points and performance.measure() for spans between them.

1function measure(label, fn) {2  const start = label + ":start";3  const end = label + ":end";4  performance.mark(start, { detail: { label, phase: "start" } });5  const result = fn();6  performance.mark(end, { detail: { label, phase: "end" } });7  performance.measure(label, { start, end, detail: { label, result } });8  performance.clearMarks(start);9  performance.clearMarks(end);10  return { result, entries: performance.getEntriesByName(label, "measure") };11}12 13const report = measure("hydrate-card", () => "ready");14console.log(report.result);15console.log(report.entries.at(-1).name);16console.log(report.entries.at(-1).duration >= 0);17performance.clearMeasures("hydrate-card");

Line 4 records a start mark with a detail object. Line 5 runs the work. Line 6 records the end mark. Line 7 creates a measure entry, line 8 and line 9 clear temporary marks, and line 10 returns the original result plus entries from getEntriesByName. Use getEntriesByType("measure") when you want every measure of that type.

1function measure(label, fn) {2  const start = label + ":start";3  const end = label + ":end";4  performance.mark(start, { detail: { label, phase: "start" } });5  const result = fn();6  performance.mark(end, { detail: { label, phase: "end" } });7  performance.measure(label, { start, end, detail: { label, result } });8  performance.clearMarks(start);9  performance.clearMarks(end);10  return { result, entries: performance.getEntriesByName(label, "measure") };11}12 13const report = measure("hydrate-card", () => "ready");Run14console.log(report.result);15console.log(report.entries.at(-1).name);16console.log(report.entries.at(-1).duration >= 0);17performance.clearMeasures("hydrate-card");

1function measure(label, fn) {2  const start = label + ":start";3  const end = label + ":end";4  performance.mark(start, { detail: { label, phase: "start" } });5  const result = fn();6  performance.mark(end, { detail: { label, phase: "end" } });7  performance.measure(label, { start, end, detail: { label, result } });8  performance.clearMarks(start);9  performance.clearMarks(end);10  return { result, entries: performance.getEntriesByName(label, "measure") };11}12 13const report = measure("hydrate-card", () => "ready");14console.log(report.result);15console.log(report.entries.at(-1).name);16console.log(report.entries.at(-1).duration >= 0);17performance.clearMeasures("hydrate-card");

1console.time("filter visible products");2["keyboard", "mouse", "monitor"].filter(item => item.includes("o"));3console.timeEnd("filter visible products");

console.time and console.timeEnd are useful scratch tools, but they do not create User Timing entries, do not show up as named spans in a Performance recording, and are easy to leave behind. Promote important probes to marks and measures.

PerformanceObserver lets code subscribe to entries as the browser creates them. buffered: true asks for earlier entries of that type too, which matters for paint, LCP, navigation, and marks that may have happened before your observer was created.

1const types = [2  "mark",3  "measure",4  "longtask",5  "long-animation-frame",6  "navigation",7  "resource",8  "paint",9  "largest-contentful-paint",10  "event",11];12 13console.log(types.filter(type => PerformanceObserver.supportedEntryTypes.includes(type)).join(", "));14 15const observer = new PerformanceObserver(list => {16  for (const entry of list.getEntries()) {17    console.log(entry.entryType, entry.name);18  }19});20 21observer.observe({ type: "mark", buffered: true });22performance.mark("search-start", { detail: { route: "/products" } });23observer.disconnect();

Chrome 154 reports support for mark, measure, longtask, long-animation-frame, navigation, resource, paint, largest-contentful-paint, and event among other entries. Long tasks, LoAF, LCP, and event timing are only introduced here; the main-thread and loading-performance lessons use them in depth.

1const nav = performance.getEntriesByType("navigation")[0];2 3if (nav) {4  const breakdown = {5    dns: nav.domainLookupEnd - nav.domainLookupStart,6    tcp: nav.connectEnd - nav.connectStart,7    ttfb: nav.responseStart - nav.requestStart,8    domContentLoaded: nav.domContentLoadedEventEnd - nav.startTime,9    load: nav.loadEventEnd - nav.startTime,10  };11  console.log(JSON.stringify(breakdown));12}

DevTools answers “what happened during this interaction?” Open the Performance panel, use the Live metrics screen for a quick Core Web Vitals-style read, then record runtime performance or record and reload for page load. Use Capture settings to choose CPU and Network throttling. DevTools may recommend presets based on field data.

In the recording, the Main track shows tasks on the main thread. Long tasks get red triangle markers. User Timing marks and measures appear on the Timings track so your labels line up with script, style, layout, paint, screenshots, requests, and frames. The lower tabs help you change the question: Bottom-up asks “which leaves cost the most?”, Call tree asks “which path cost the most?”, and Event log asks “what happened in exact order?” The Insights tab or sidebar highlights issues such as LCP and INP subparts.

A flame chart is a stacked timeline. The horizontal position is when a function was on the stack. Width is total duration. Vertical nesting is call stack depth. A parent includes its children, so total time is not the same as self time. Self time is the part of a frame not covered by child frames.

1function profileCheckout() {2  return profile("checkout", () => {3    parseCart();4    priceItems();5    renderSummary();6  });7}8 9function priceItems() {10  readPrices();11  applyDiscounts();12}

Step through the tiny chart before opening a huge trace. checkout is widest because it contains everything. Inside it, priceItems contains readPrices and applyDiscounts. applyDiscounts has the largest self time because it does the most direct work in this recorded tree. A real browser trace is sampled, so tiny functions may appear or disappear depending on sampling and inlining.

Lab data is controlled: Lighthouse, WebPageTest, Playwright traces, and local DevTools recordings. Field data comes from real users. Chrome User Experience Report (CrUX) provides public field data for eligible origins and URLs. Real user monitoring is your own sampled telemetry, sliced by route, device class, release, connection, and privacy-safe dimensions.

1import { onCLS, onINP, onLCP, onTTFB } from "web-vitals";2 3function sendMetric(metric) {4  navigator.sendBeacon("/rum", JSON.stringify({5    name: metric.name,6    value: metric.value,7    id: metric.id,8  }));9}10 11onCLS(sendMetric);12onINP(sendMetric);13onLCP(sendMetric);14onTTFB(sendMetric);

The web-vitals package is not installed in this app, so the import above is a production sketch, not a runnable lesson example. The current API exposes callbacks such as onCLS, onINP, onLCP, and onTTFB. The callback receives a metric object with fields such as name, value, id, delta, and entries.

1const queue = [];2 3function rememberMetric(metric) {4  queue.push({ name: metric.name, value: metric.value, path: location.pathname });5}6 7document.addEventListener("visibilitychange", () => {8  if (document.visibilityState !== "hidden" || queue.length === 0) return;9  const payload = JSON.stringify(queue.splice(0));10  navigator.sendBeacon("/rum", payload);11});

Use navigator.sendBeacon during visibilitychange because users close tabs and navigate away. Sample traffic, remove personal data, avoid raw URLs with secrets, and document retention. RUM is evidence, not surveillance.

Microbenchmarks are useful when the question is tiny and isolated, but they are easy to fool. Watch for JIT warm-up, unused results being optimized away, timer resolution, variance, outliers, DevTools overhead, garbage collection, and code that does not resemble production. A macro benchmark or real trace often matters more than a faster loop.

1function median(values) {2  const sorted = [...values].sort((a, b) => a - b);3  const middle = Math.floor(sorted.length / 2);4  return sorted.length % 2 ? sorted[middle] : (sorted[middle - 1] + sorted[middle]) / 2;5}6 7function benchmark(label, fn, { warmup = 20, samples = 7, iterations = 200 } = {}) {8  let sink = 0;9  for (let i = 0; i < warmup; i += 1) sink += fn();10  const durations = [];11  for (let sample = 0; sample < samples; sample += 1) {12    const start = performance.now();13    for (let i = 0; i < iterations; i += 1) sink += fn();14    durations.push(performance.now() - start);15  }16  return { label, median: median(durations), samples: durations.length, sink };17}18 19const report = benchmark("math", () => Math.sqrt(144));20console.log(report.label);21console.log(report.samples);22console.log(report.median >= 0);23console.log(report.sink > 0);

1function median(values) {2  const sorted = [...values].sort((a, b) => a - b);3  const middle = Math.floor(sorted.length / 2);4  return sorted.length % 2 ? sorted[middle] : (sorted[middle - 1] + sorted[middle]) / 2;5}6 7function benchmark(label, fn, { warmup = 20, samples = 7, iterations = 200 } = {}) {8  let sink = 0;9  for (let i = 0; i < warmup; i += 1) sink += fn();10  const durations = [];11  for (let sample = 0; sample < samples; sample += 1) {12    const start = performance.now();13    for (let i = 0; i < iterations; i += 1) sink += fn();14    durations.push(performance.now() - start);15  }16  return { label, median: median(durations), samples: durations.length, sink };17}18 19const report = benchmark("math", () => Math.sqrt(144));20console.log(report.label);21console.log(report.samples);22console.log(report.median >= 0);23console.log(report.sink > 0);Run

1function median(values) {2  const sorted = [...values].sort((a, b) => a - b);3  const middle = Math.floor(sorted.length / 2);4  return sorted.length % 2 ? sorted[middle] : (sorted[middle - 1] + sorted[middle]) / 2;5}6 7function benchmark(label, fn, { warmup = 20, samples = 7, iterations = 200 } = {}) {8  let sink = 0;9  for (let i = 0; i < warmup; i += 1) sink += fn();10  const durations = [];11  for (let sample = 0; sample < samples; sample += 1) {12    const start = performance.now();13    for (let i = 0; i < iterations; i += 1) sink += fn();14    durations.push(performance.now() - start);15  }16  return { label, median: median(durations), samples: durations.length, sink };17}18 19const report = benchmark("math", () => Math.sqrt(144));20console.log(report.label);21console.log(report.samples);22console.log(report.median >= 0);23console.log(report.sink > 0);

Libraries such as tinybench and mitata help with warm-up, repeated samples, and reports. They do not remove your responsibility to choose production-like inputs, run with DevTools closed when appropriate, compare medians and variance, and confirm the result in the real interaction.

Common misconceptions

Answer from the evidence: what was measured, where it came from, and what could fool it?

Key takeaways

• Measure the user-visible problem first; premature optimization can improve the wrong thing.
• Use percentiles, especially p75 and p95, instead of trusting averages.
• performance.now(), marks, measures, observers, and navigation timing give browser-grounded evidence.
• Chrome DevTools Performance recordings connect tasks, marks, screenshots, flame charts, and Insights.
• RUM prioritizes real-user pain; lab traces explain causes; benchmarks need warm-up, used results, many samples, and medians.

Up next: Keeping the main thread responsive.