Resource Timing API

What is the Resource Timing API?

The Resource Timing API is a browser API that enables retrieval and analysis of detailed network timing data regarding the loading of an application's resources. Every resource loaded by a web page--including images, scripts, stylesheets, fonts, and XMLHttpRequest or fetch requests--is represented by a PerformanceResourceTiming entry with an entryType of "resource".

The API provides high-resolution timestamps for each stage of resource loading, from the initial fetch request through DNS lookup, TCP connection establishment, TLS negotiation, and final response delivery. This granular timing data allows developers to identify performance bottlenecks at each step of the resource loading process.

The Resource Timing API builds upon the foundation laid by the Navigation Timing API, which provides similar timing information for the main HTML document. While Navigation Timing focuses on the overall page load experience, Resource Timing extends this capability to every sub-resource that makes up the page.

This API is an essential tool for modern web development, enabling data-driven performance optimization that directly improves user experience and search engine rankings. Understanding how resources load and perform is fundamental to creating fast, responsive websites that users love.

The PerformanceResourceTiming Interface

At the core of the Resource Timing API is the PerformanceResourceTiming interface, which extends the PerformanceEntry interface to provide timing information specific to resource loading. Each PerformanceResourceTiming entry represents a single resource and contains properties for accessing both timing data and metadata about the resource itself.

The interface inherits several properties from PerformanceEntry that provide essential information about each resource. The name property returns the URL of the resource. The entryType property always returns "resource" for PerformanceResourceTiming entries. The startTime property returns the timestamp when the resource fetch started. The duration property returns the total time from startTime to responseEnd.

Beyond these inherited properties, PerformanceResourceTiming provides a rich set of additional properties for detailed timing analysis, including redirectStart/redirectEnd for measuring redirect timing, workerStart for measuring Service Worker processing time, and various DNS, connection, and response timing properties.

Understanding this interface is fundamental to implementing effective performance monitoring for any web application. For developers working with APIs and SDKs, knowing how to access and interpret these timing metrics is essential for optimizing request performance.

Resource Loading Timestamps Explained

The Resource Timing API captures a detailed timeline of resource loading through a series of high-resolution timestamps. Understanding these timestamps and their relationship to each other is essential for effective performance analysis.

The Complete Timeline

• redirectStart/redirectEnd: Measure redirect timing when resources are redirected
• workerStart: When request enters Service Worker (0 if no SW interception)
• fetchStart: When browser starts fetching the resource
• domainLookupStart/domainLookupEnd: DNS resolution time
• connectStart/connectEnd: TCP connection establishment time
• secureConnectionStart: TLS handshake start time
• requestStart: When browser sends the request
• responseStart: Time to First Byte (TTFB)
• responseEnd: When resource transfer completes

Each timestamp represents a critical milestone in the resource loading process, enabling precise identification of performance bottlenecks. For example, high DNS lookup times may indicate the need for DNS prefetching, while slow TTFB suggests server-side optimization opportunities. Understanding these fundamentals connects directly to CSS fundamentals that affect rendering performance.

Managing Resource Buffer Sizes

By default, browsers limit the number of PerformanceResourceTiming entries to 250. For pages with more than 250 resources, additional entries won't be captured until the buffer is cleared or resized.

Buffer Configuration Methods

// Set buffer size to accommodate all resources
performance.setResourceTimingBufferSize(500);

// Clear all timing entries to start fresh
performance.clearResourceTimings();

// Listen for buffer full events
addEventListener('resourcetimingbufferfull', (event) => {
 // Handle buffer full - clear entries or increase size
});

When the buffer becomes full, the resourcetimingbufferfull event fires, providing an opportunity to implement custom buffer management strategies such as sending accumulated data to analytics and clearing the buffer.

For resource-rich applications, proper buffer management is critical for comprehensive performance monitoring and optimization. Using simple website templates that follow performance best practices can help minimize the number of resources while maintaining a great user experience.

Cross-Origin Timing Information

When loading resources from a different origin, detailed timing properties are restricted for security reasons. By default, cross-origin resources only show total duration, with detailed timing set to zero.

The Timing-Allow-Origin Header

To enable detailed timing for cross-origin resources, servers must include the Timing-Allow-Origin header:

Timing-Allow-Origin: *
# or
Timing-Allow-Origin: https://example.com

Restricted Properties

The following return 0 for cross-origin requests without proper headers: redirectStart, redirectEnd, domainLookupStart, domainLookupEnd, connectStart, connectEnd, secureConnectionStart, requestStart, and responseStart.

Many popular third-party services including CDNs and analytics platforms now support this header, enabling comprehensive performance monitoring across your entire resource ecosystem.

When using CDN services for asset delivery, ensure they support the Timing-Allow-Origin header to enable full performance visibility.

Practical Implementation

Accessing Resource Timing Data

// Get all resource timing entries
const resources = performance.getEntriesByType('resource');

// Get timing for a specific resource
const resource = performance.getEntriesByName('https://example.com/image.webp')[0];

// Calculate key metrics
const dnsTime = resource.domainLookupEnd - resource.domainLookupStart;
const tcpTime = resource.connectEnd - resource.connectStart;
const ttfb = resource.responseStart - resource.requestStart;
const totalTime = resource.duration;

// Check if served from cache
const fromCache = resource.transferSize === 0;

Analyzing All Resources

Grouping resources by domain helps identify optimization priorities:

const resources = performance.getEntriesByType('resource');
const byDomain = resources.reduce((acc, entry) => {
 const domain = new URL(entry.name).hostname;
 acc[domain] = acc[domain] || [];
 acc[domain].push(entry);
 return acc;
}, {});

// Analyze each domain's performance
for (const [domain, entries] of Object.entries(byDomain)) {
 const totalDuration = entries.reduce((sum, e) => sum + e.duration, 0);
 console.log(`${domain}: ${totalDuration.toFixed(2)}ms total`);
}

Implementing these patterns enables comprehensive performance analysis for continuous optimization.

Performance Optimization Strategies

Identifying Slow Resources

Resources with high duration should be prioritized. Examine timing breakdowns:

• High DNS/connection time: Use DNS prefetching, connection pooling, or faster CDN
• High TTFB: Investigate server-side performance issues
• Large transfer size: Optimize compression, use modern formats (WebP, AVIF)
• No cache headers: Implement browser caching and CDN usage

Reducing Resource Count

• Combine small files and eliminate unused dependencies
• Use CSS sprites or icon fonts to reduce image requests
• Lazy-load below-the-fold resources
• Audit and remove third-party scripts that aren't essential

Optimizing Critical Rendering Path

Use renderBlockingStatus to identify blocking resources:

• Move critical CSS inline, defer non-critical styles
• Use async/defer for JavaScript to prevent blocking
• Preload critical above-the-fold resources
• Prioritize resource loading order for visible content

The Resource Timing API provides the data foundation for continuous performance improvement, directly supporting Core Web Vitals optimization and better search rankings. For developers working with CSS fundamentals, understanding how stylesheets impact the critical rendering path is essential.

Sources

1. MDN Web Docs - Resource Timing - Official W3C-aligned documentation for the Resource Timing API

2. MDN Web Docs - PerformanceResourceTiming - Complete interface reference with all properties and methods

3. Google Developers Blog - Measuring network performance with Resource Timing API - Google's official guide for measuring network performance