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.

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`);

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.connectEnd - nav.secureConnectionStart,  // 0 if no 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.