Performance API

Measuring real-world performance — performance.now(), marks, measures, PerformanceObserver, Core Web Vitals, and the Navigation Timing API.

What it is, in plain English: The Performance API provides high-resolution timing and performance measurement tools. performance.now() gives sub-millisecond timestamps. performance.mark() and performance.measure() create named timing points visible in DevTools. The PerformanceObserver watches for performance entries in real time. Core Web Vitals (LCP, FID, CLS) are the key user experience metrics measured with the Performance API.

Where this bites you

Timing an async function without await measures how long it took to start the work, not to do it. The call returns a Promise immediately, the second performance.now() runs straight away, and a 300 ms fetch reports well under a millisecond. It's an easy way to "prove" that slow code is fast.

async function loadReport() {
  await new Promise(r => setTimeout(r, 300));   // stands in for a 300 ms fetch
  return "report";
}

const start = performance.now();
loadReport();                                   // no await
console.log(`Took ${(performance.now() - start).toFixed(1)}ms`);
// Took 0.6ms     (Chromium; 0.1ms in Node)

Measuring how fast your code runs

performance.now() — precise timing

// Measures real elapsed time, sub-millisecond precision:
const start = performance.now();

doSomethingExpensive();

const elapsed = performance.now() - start;
console.log(`Took ${elapsed.toFixed(3)}ms`);

// Compare two approaches:
const t1 = performance.now();
approach1(data);
const t2 = performance.now();
approach2(data);
const t3 = performance.now();

console.log(`Approach 1: ${(t2-t1).toFixed(2)}ms`);
console.log(`Approach 2: ${(t3-t2).toFixed(2)}ms`);

The examples above time synchronous functions, which is why they work as written. For anything that returns a Promise, the end mark has to come after await, as in the marks-and-measures example below:

async function loadReport() {
  await new Promise(r => setTimeout(r, 300));
  return "report";
}

async function main() {
  const start = performance.now();
  await loadReport();                           // wait for the work to finish
  console.log(`Took ${(performance.now() - start).toFixed(1)}ms`);
}
main();
// Took 300.1ms   (exact ms vary run to run)

Named marks and measures

// Create named timing points visible in DevTools Performance tab:
performance.mark("data:fetch:start");
const data = await fetchData();
performance.mark("data:fetch:end");

performance.mark("data:render:start");
renderData(data);
performance.mark("data:render:end");

// Create measures between marks:
performance.measure("fetch time",  "data:fetch:start",  "data:fetch:end");
performance.measure("render time", "data:render:start", "data:render:end");

// Read the measurements:
performance.getEntriesByType("measure").forEach(m => {
  console.log(`${m.name}: ${m.duration.toFixed(2)}ms`);
});

Try It Yourself

// Performance API — high-resolution timing

// performance.now() — sub-millisecond timestamp (origin = page load)
const t0 = performance.now();

// Simulate work:
let sum = 0;
for (let i = 0; i < 1000000; i++) sum += Math.sqrt(i);

const t1 = performance.now();
console.log(`Loop: ${(t1 - t0).toFixed(3)}ms`);

// performance.mark() and performance.measure() — named timings
performance.mark("render:start");
// ... render something ...
performance.mark("render:end");
performance.measure("render-time", "render:start", "render:end");

const [measure] = performance.getEntriesByName("render-time");
console.log(`Render: ${measure.duration.toFixed(3)}ms`);

// Get ALL performance entries:
console.log("\nAll performance entries:");
performance.getEntries().forEach(entry => {
  if (entry.duration > 0) {
    console.log(`  ${entry.entryType.padEnd(12)} ${entry.name.slice(0,40).padEnd(42)} ${entry.duration.toFixed(2)}ms`);
  }
});

// Navigation timing — how long the page load took:
const nav = performance.getEntriesByType("navigation")[0];
if (nav) {
  console.log("\nPage load timing:");
  console.log("  DNS lookup:", (nav.domainLookupEnd - nav.domainLookupStart).toFixed(0), "ms");
  console.log("  TCP connect:", (nav.connectEnd - nav.connectStart).toFixed(0), "ms");
  console.log("  TTFB:", (nav.responseStart - nav.requestStart).toFixed(0), "ms");
  console.log("  DOM ready:", (nav.domContentLoadedEventEnd - nav.startTime).toFixed(0), "ms");
  console.log("  Full load:", (nav.loadEventEnd - nav.startTime).toFixed(0), "ms");
}

// Memory (Chrome only):
if ("memory" in performance) {
  const m = performance.memory;
  console.log("\nMemory:");
  console.log("  Used:", (m.usedJSHeapSize / 1e6).toFixed(1), "MB");
  console.log("  Total:", (m.totalJSHeapSize / 1e6).toFixed(1), "MB");
}

Core Web Vitals and PerformanceObserver

// Core Web Vitals — the metrics Google uses for search ranking:
// LCP — Largest Contentful Paint: how long until largest element visible (<2.5s good)
// INP — Interaction to Next Paint: input delay (<200ms good)
// CLS — Cumulative Layout Shift: unexpected layout movement (<0.1 good)

// Measure with PerformanceObserver:
new PerformanceObserver((list) => {
  list.getEntries().forEach(entry => {
    if (entry.entryType === "largest-contentful-paint") {
      console.log("LCP:", entry.startTime.toFixed(0), "ms");
    }
  });
}).observe({ type: "largest-contentful-paint", buffered: true });

new PerformanceObserver((list) => {
  list.getEntries().forEach(entry => {
    if (entry.hadRecentInput) return;  // ignore clicks/taps
    const cls = entry.value;
    console.log("CLS shift:", cls.toFixed(4));
  });
}).observe({ type: "layout-shift", buffered: true });

// Detect long tasks (>50ms blocks the main thread):
new PerformanceObserver((list) => {
  list.getEntries().forEach(entry => {
    console.warn(`Long task: ${entry.duration.toFixed(0)}ms at ${entry.startTime.toFixed(0)}ms`);
  });
}).observe({ type: "longtask" });

// Send metrics to your analytics:
function sendVitals(name, value) {
  navigator.sendBeacon("/analytics", JSON.stringify({ metric: name, value, url: location.href }));
}

Resource Timing and Navigation Timing spec

// Resource Timing — how long each resource (JS, CSS, image) took:
performance.getEntriesByType("resource").forEach(entry => {
  console.log({
    name:     entry.name.split("/").pop(),
    type:     entry.initiatorType,       // "script", "link", "img", "fetch"
    duration: entry.duration.toFixed(0) + "ms",
    size:     (entry.transferSize / 1024).toFixed(1) + "KB",
    cached:   entry.transferSize === 0,  // cached if no bytes transferred
  });
});

// Navigation Timing API — detailed page load breakdown:
const nav = performance.getEntriesByType("navigation")[0];
const milestones = {
  "DNS":     nav.domainLookupEnd - nav.domainLookupStart,
  "TCP":     nav.connectEnd - nav.connectStart,
  "TLS":     nav.secureConnectionStart > 0 ? nav.connectEnd - nav.secureConnectionStart : 0,  // secureConnectionStart is 0 without TLS
  "Request": nav.responseStart - nav.requestStart,         // TTFB
  "Response":nav.responseEnd - nav.responseStart,          // download
  "DOM":     nav.domContentLoadedEventEnd - nav.responseEnd,
  "Load":    nav.loadEventEnd - nav.domContentLoadedEventEnd,
};
Object.entries(milestones).forEach(([k,v]) => console.log(`${k}: ${v.toFixed(0)}ms`));

Official Sources

The Codex links only to official documentation and the ECMAScript specification. No third-party tutorials.