Performance Mark, Measure, and Observer

Measure What Matters, Automatically

Chrome DevTools is incredible for debugging in development. But your users are not running DevTools. The Performance API gives you the same measurement power in production — mark important moments, measure durations between them, observe browser events, and send it all to your analytics pipeline.

This is how you go from "the app feels slow sometimes" to "P95 LCP is 2.8s on mobile in India, caused by a 1.2s main thread blocking task during hydration."

User Timing API: Mark and Measure

performance.mark()

Creates a named timestamp in the performance timeline:

performance.mark('component-render-start');
renderDashboard();
performance.mark('component-render-end');

Marks are zero-overhead points in time. They appear in the DevTools Performance panel's Timings lane and are accessible via the Performance API.

performance.measure()

Calculates the duration between two marks:

performance.mark('fetch-start');
const data = await fetch('/api/dashboard');
performance.mark('fetch-end');

const measurement = performance.measure(
  'Dashboard API Fetch',
  'fetch-start',
  'fetch-end'
);

console.log(measurement.duration); // e.g., 342.5 (milliseconds)

The measure name ('Dashboard API Fetch') appears as a labeled bar in the DevTools Timings lane — making it easy to correlate your code with the flame chart.

Measure Without Marks

You can measure from navigation start or pass timestamps directly:

performance.measure('Time to Interactive', {
  start: 0,
  end: performance.now(),
});

performance.measure('Image Processing', {
  start: startTimestamp,
  duration: 500,
});

PerformanceObserver: Real-Time Event Monitoring

PerformanceObserver lets you subscribe to performance events as they happen. It is the foundation for monitoring Core Web Vitals in production.

const observer = new PerformanceObserver((list) => {
  for (const entry of list.getEntries()) {
    console.log(entry.entryType, entry.name, entry.duration);
  }
});

observer.observe({ type: 'measure', buffered: true });

The buffered: true option is critical — it delivers entries that were recorded before the observer was created. Without it, you miss early events.

Entry Types You Can Observe

Monitoring Core Web Vitals

Largest Contentful Paint (LCP)

new PerformanceObserver((list) => {
  const entries = list.getEntries();
  const lastEntry = entries[entries.length - 1];

  console.log('LCP:', {
    renderTime: lastEntry.renderTime,
    loadTime: lastEntry.loadTime,
    size: lastEntry.size,
    element: lastEntry.element?.tagName,
    url: lastEntry.url,
  });
}).observe({ type: 'largest-contentful-paint', buffered: true });

The browser may report multiple LCP candidates (as larger elements render, they replace previous candidates). The last entry before user interaction is the final LCP.

Cumulative Layout Shift (CLS)

let clsScore = 0;
let sessionEntries = [];

new PerformanceObserver((list) => {
  for (const entry of list.getEntries()) {
    if (!entry.hadRecentInput) {
      sessionEntries.push(entry);
      clsScore += entry.value;
    }
  }

  console.log('Current CLS:', clsScore);
}).observe({ type: 'layout-shift', buffered: true });

Layout shift entries have a value (how much the viewport shifted) and sources (which elements moved). Shifts caused by user input (hadRecentInput === true) are excluded from CLS.

Interaction to Next Paint (INP)

const interactions = new Map();

new PerformanceObserver((list) => {
  for (const entry of list.getEntries()) {
    if (entry.interactionId) {
      const existing = interactions.get(entry.interactionId);
      if (!existing || entry.duration > existing.duration) {
        interactions.set(entry.interactionId, entry);
      }
    }
  }
}).observe({ type: 'event', buffered: true, durationThreshold: 16 });

INP is the P98 interaction duration. Each interaction (click, keypress, tap) gets an interactionId. Multiple event entries can share the same interactionId (e.g., pointerdown, pointerup, click for one tap). The longest duration per interactionId represents the interaction's latency.

Resource Timing API

Every network resource (scripts, images, stylesheets, fonts, API calls) gets a PerformanceResourceTiming entry:

new PerformanceObserver((list) => {
  for (const entry of list.getEntries()) {
    if (entry.initiatorType === 'fetch' || entry.initiatorType === 'xmlhttprequest') {
      console.log('API call:', {
        name: entry.name,
        duration: entry.duration,
        transferSize: entry.transferSize,
        serverTiming: entry.serverTiming,
      });
    }
  }
}).observe({ type: 'resource', buffered: true });

Key properties:

• duration — total time from request start to response end
• transferSize — bytes transferred over the network (0 if cached)
• decodedBodySize — uncompressed response size
• serverTiming — server-provided timing data (via Server-Timing header)

This is invaluable for monitoring API performance in production.

Long Tasks Observer

new PerformanceObserver((list) => {
  for (const entry of list.getEntries()) {
    console.log('Long task detected:', {
      duration: entry.duration,
      startTime: entry.startTime,
      attribution: entry.attribution.map(a => ({
        containerType: a.containerType,
        containerSrc: a.containerSrc,
        containerName: a.containerName,
      })),
    });
  }
}).observe({ type: 'longtask', buffered: true });

The attribution array tells you whether the long task came from your main page, an iframe, or a third-party script. This is critical for identifying third-party performance problems.

Sending Metrics to Analytics

function sendToAnalytics(metric) {
  const body = JSON.stringify({
    name: metric.name,
    value: metric.value,
    id: metric.id,
    page: location.pathname,
    connection: navigator.connection?.effectiveType,
    deviceMemory: navigator.deviceMemory,
  });

  if (navigator.sendBeacon) {
    navigator.sendBeacon('/api/metrics', body);
  } else {
    fetch('/api/metrics', { body, method: 'POST', keepalive: true });
  }
}

navigator.sendBeacon() is designed for analytics — it queues the request and guarantees delivery even if the page is unloading. The keepalive: true option on fetch provides similar behavior.

Enriching Metrics with Context

Raw numbers are useless without context. Always attach:

function enrichMetric(entry) {
  return {
    ...entry.toJSON(),
    url: location.href,
    userAgent: navigator.userAgent,
    connection: navigator.connection?.effectiveType,
    deviceMemory: navigator.deviceMemory,
    hardwareConcurrency: navigator.hardwareConcurrency,
    viewport: `${innerWidth}x${innerHeight}`,
    timestamp: Date.now(),
  };
}

This lets you segment metrics by device type, connection speed, and page — revealing that your "good average LCP" hides terrible P95 scores on budget Android phones over 3G.

Custom Metrics

Beyond Web Vitals, define metrics specific to your application:

performance.mark('search-query-start');
const results = await searchAPI(query);
performance.mark('search-results-received');
renderResults(results);
performance.mark('search-results-rendered');

performance.measure('Search API Latency',
  'search-query-start', 'search-results-received');
performance.measure('Search Render Time',
  'search-results-received', 'search-results-rendered');
performance.measure('Search Total Time',
  'search-query-start', 'search-results-rendered');

Custom metrics track what matters to your users. "Time from search keystroke to visible results" is more actionable than generic Web Vitals for a search-heavy app.