Module 05: Performance Timing

In previous modules we collected what the user visited and what device they used. Now we measure how fast the page loaded. The Performance API gives us millisecond-precision timestamps for every phase of the page load — from DNS lookup through final paint — and a full inventory of every resource the browser fetched.

Why Performance Data Matters

Real User Monitoring (RUM) measures actual user experience, not synthetic benchmarks. A page that loads in 200ms on your dev machine might take 8 seconds on a user's phone in a rural area. Synthetic tests (Lighthouse, WebPageTest) run on controlled hardware with fast networks — they measure potential performance. RUM measures actual performance.

Performance data tells you what real users experience. It answers questions that synthetic tests cannot:

• How long does DNS resolution take for users in different regions?
• What is the median Time to First Byte across your actual user base?
• Which resources consume the most bandwidth for real visitors?
• How does page load time correlate with bounce rate?

Without RUM data, you are optimizing for your own machine, not your users' machines.

Navigation Timing API

The Navigation Timing API provides a PerformanceNavigationTiming entry that records timestamps for every phase of the page load. You access it via performance.getEntriesByType('navigation'), which returns an array with a single entry (the current page navigation).

Here is the timeline of events, from the moment the browser starts fetching the page to the final load event:

Each row is a phase of the page load. The timestamps are all relative to timeOrigin (typically the moment the navigation started). By subtracting pairs of timestamps, we calculate the duration of each phase.

Building getNavigationTiming()

This function extracts the key performance milestones from the navigation entry:

function getNavigationTiming() {
  const entries = performance.getEntriesByType('navigation');
  if (!entries.length) return {};

  const n = entries[0];

  return {
    // DNS lookup time
    dnsLookup: round(n.domainLookupEnd - n.domainLookupStart),
    // TCP connection time
    tcpConnect: round(n.connectEnd - n.connectStart),
    // TLS handshake (HTTPS only)
    tlsHandshake: n.secureConnectionStart > 0
      ? round(n.connectEnd - n.secureConnectionStart) : 0,
    // Time to First Byte
    ttfb: round(n.responseStart - n.requestStart),
    // Download time (response)
    download: round(n.responseEnd - n.responseStart),
    // DOM interactive (HTML parsed, not all resources loaded)
    domInteractive: round(n.domInteractive - n.fetchStart),
    // DOM complete (all resources loaded)
    domComplete: round(n.domComplete - n.fetchStart),
    // Full page load
    loadEvent: round(n.loadEventEnd - n.fetchStart),
    // Total fetch time
    fetchTime: round(n.responseEnd - n.fetchStart),
    // Transfer size and header overhead
    transferSize: n.transferSize,
    headerSize: n.transferSize - n.encodedBodySize
  };
}

function round(n) {
  return Math.round(n * 100) / 100;
}

Each calculated value represents a meaningful milestone:

Resource Timing API

While Navigation Timing tells you about the page load, Resource Timing tells you about every resource the page loaded: scripts, stylesheets, images, fonts, XHR/fetch requests, and more. Each resource gets its own PerformanceResourceTiming entry with the same timestamp properties as navigation timing.

Sending every individual resource entry to your analytics server would be expensive and noisy. Instead, we aggregate resources by type and compute summary statistics:

Building getResourceSummary()

function getResourceSummary() {
  const resources = performance.getEntriesByType('resource');

  const summary = {
    script:         { count: 0, totalSize: 0, totalDuration: 0 },
    link:           { count: 0, totalSize: 0, totalDuration: 0 },  // CSS
    img:            { count: 0, totalSize: 0, totalDuration: 0 },
    font:           { count: 0, totalSize: 0, totalDuration: 0 },
    fetch:          { count: 0, totalSize: 0, totalDuration: 0 },
    xmlhttprequest: { count: 0, totalSize: 0, totalDuration: 0 },
    other:          { count: 0, totalSize: 0, totalDuration: 0 }
  };

  resources.forEach((r) => {
    const type = summary[r.initiatorType] ? r.initiatorType : 'other';
    summary[type].count++;
    summary[type].totalSize += r.transferSize || 0;
    summary[type].totalDuration += r.duration || 0;
  });

  return {
    totalResources: resources.length,
    byType: summary
  };
}

The initiatorType property tells you what caused the resource to load. Common values:

For each type, we track three things: how many resources loaded (count), how many bytes were transferred (totalSize), and how long they took combined (totalDuration). This gives you a bandwidth and latency profile broken down by resource category.

When to Collect Timing Data

Timing data is not available immediately. Navigation Timing only completes after the load event fires. Resource Timing accumulates as resources load. If you try to read loadEventEnd before the load event finishes, it will be 0.

// Collect after the page is fully loaded
window.addEventListener('load', () => {
  // Small delay to ensure loadEventEnd is populated
  setTimeout(() => {
    const timing = getNavigationTiming();
    const resources = getResourceSummary();
    // Add to beacon payload...
  }, 0);
});

The setTimeout(fn, 0) pattern is not a hack — it is the correct way to read loadEventEnd. The load event handler runs during the load event; loadEventEnd is only set after all load handlers have completed. The setTimeout defers our read to the next task, by which point the value is populated.

Integrating with the Collector

Our collector-v4.js extends the previous collector by adding performance timing data to the beacon payload. The structure follows the same IIFE pattern, with the new timing functions integrated into the collect() function:

function collect() {
  const payload = {
    // ... previous fields (url, title, referrer, timestamp, session, technographics)
    url: window.location.href,
    title: document.title,
    referrer: document.referrer,
    timestamp: new Date().toISOString(),
    type: 'pageview',
    session: getSessionId(),
    technographics: getTechnographics(),
    timing: getNavigationTiming(),
    resources: getResourceSummary()
  };

  send(payload);
}

The key difference from previous versions: we collect timing data inside the load event with a setTimeout delay, rather than firing immediately on DOMContentLoaded. This ensures all timing milestones are available when we build the payload.

Understanding the Data

Here is a sample timing output and what each value means in practical terms:

{
  "dnsLookup": 0,
  "tcpConnect": 0,
  "tlsHandshake": 0,
  "ttfb": 12.5,
  "download": 3.2,
  "domInteractive": 245.8,
  "domComplete": 1823.4,
  "loadEvent": 1825.1,
  "fetchTime": 15.7,
  "transferSize": 45230,
  "headerSize": 430
}

Reading this data:

• DNS/TCP/TLS are all 0 — This is a same-origin page where the connection was already established (or served from cache). These values become meaningful for first visits or cross-origin resources.
• TTFB is 12.5ms — The server responded quickly. TTFB above 200ms suggests a slow server or geographic distance. Above 600ms signals a serious problem.
• Download is 3.2ms — The HTML document itself was small and fast to transfer.
• domInteractive is 245.8ms — The HTML was parsed and the DOM was ready in under 250ms. The page became interactive quickly.
• domComplete is 1823.4ms — All resources (images, CSS, scripts) took about 1.8 seconds to fully load. The gap between domInteractive and domComplete tells you how much time is spent on subresources.
• loadEvent is 1825.1ms — Almost identical to domComplete, meaning load event handlers were fast.
• transferSize is 45,230 bytes — The HTML document was about 44 KB over the wire (compressed).

Cross-Reference: The Reference Collector

Summary

• Navigation Timing API reveals every phase of the page load — from DNS lookup to the final load event
• TTFB (Time to First Byte) is the most important single metric for server responsiveness
• Resource Timing shows what resources are loading and how much bandwidth they cost, broken down by type
• Always collect timing data after the load event with a setTimeout(fn, 0) to ensure loadEventEnd is populated
• DNS/TCP/TLS values are meaningful for first visits; they are often 0 on subsequent loads when connections are reused