Navigate back to the homepage
Browse Repo

How to Evaluate Site Speed with the Performance API

Craig Buckler
May 12th, 2021 · 6 min read

Browser DevTools are great for monitoring web application performance on your local development PC. However, they’re less practical for measuring site speed on different devices, browsers, and network connections across global locations.

The Performance API records DevTool-like metrics from real users as they navigate your application. You can post collected data to a service such as, e.g.

1asayer.event('load-performance', {
3 'os' : 'Ubuntu',
4 'agent' : 'Firefox 88.0',
5 'location': 'US',
6 'pageload': 1522.598,
7 'paint' : 5969.123,
8 'ajaxinit': 1507.067

To help identify performance bottlenecks on specific browsers, devices, or even user sessions.

What is the Performance API?

The Performance API is a collection of APIs used to measure:

Historically, developers had to adopt the Date() function to record elapsed times, e.g.

1const startTime = new Date();
3const elapsedTime = new Date() - startTime;
5console.log(`doSomething() took ${ elapsedTime }ms`);

but the Performance API is:

  1. higher resolution. Unlike Date(), it records timings in fractions of a millisecond.
  2. more reliable. Date() uses the system time so timings can become inaccurate when the OS synchronises the clock.

The API is available in client-side JavaScript in most modern browsers and is detectable with:

1if ('performance' in window) {
2 // use Performance APIs

Resource and user timing is also available in client-side Web Workers. These provide a way to run long-running or computationally-expensive scripts in the background which do not interfere with the browser’s main processing thread.

User timing APIs are also available in server-side:

  • Node.js applications with the performance_hook module, and
  • Deno applications run with the --allow-hrtime option.

The Performance API and documentation can be a little difficult to understand partly because it has evolved. I hope the information and examples in this article help illustrate its potential.

Load timing properties

The sections below describe:

  1. page navigation timings which return a PerformanceNavigationTiming object, and

  2. resource timings which returns a PerformanceResourceTiming object

Both objects provide the following identification properties:

  • name — resource URL
  • entryType — performance type ("navigation" for a page, "resource" for a page asset)
  • initiatorType — resource which initiated the performance entry ("navigation" for a page)
  • serverTiming — an array of PerformanceServerTiming objects with name, description, and duration metrics written by the server to the HTTP Server-Timing header

Both objects provide the following timing properties shown here in the chronological order you would expect them to occur. Timestamps are in milliseconds relative to the start of the page load:

  • startTime — timestamp when the fetch started (0 for a page since it’s the first asset loaded)
  • nextHopProtocol — network protocol used
  • workerStart — timestamp before starting a Progressive Web App (PWA) Service Worker (0 if the request is not intercepted by a Service Worker)
  • redirectStart — timestamp of the fetch which initiated a redirect
  • redirectEnd — timestamp after receiving the last byte of the last redirect response
  • fetchStart — timestamp before the resource fetch
  • domainLookupStart — timestamp before a DNS lookup
  • domainLookupEnd — timestamp after the DNS lookup
  • connectStart — timestamp before the browser establishes a server connection
  • connectEnd — timestamp after establishing a server connection
  • secureConnectionStart — timestamp before the browser starts the SSL handshake process
  • requestStart — timestamp before the browser requests the resource
  • responseStart — timestamp when the browser receives the first byte of data
  • responseEnd — timestamp after receiving the last byte or closing the connection
  • duration — the difference between startTime and responseEnd

Both objects provide the following download size properties:

  • transferSize — the resource size in bytes (octets), including the header and compressed body
  • encodedBodySize — the resource’s payload body in bytes (octets) before decoding/uncompressing
  • decodedBodySize — the resource’s payload body in bytes (octets) after decoding/uncompressing

Page PerformanceNavigationTiming objects provide further metrics about loading and DOM events, although these are not supported in Safari:

  • type — either "navigate", "reload", "back_forward" or "prerender"
  • redirectCount — the number of redirects
  • unloadEventStart — timestamp before the unload event of the previous document (zero if no previous document)
  • unloadEventEnd — timestamp after the unload event of the previous document (zero if no previous document)
  • domInteractive — timestamp before the browser sets the document readiness to interactive when HTML parsing and DOM construction is complete
  • domContentLoadedEventStart — timestamp before document’s DOMContentLoaded event fires
  • domContentLoadedEventEnd — timestamp after document’s DOMContentLoaded event completes
  • domComplete — timestamp before the browser sets the document readiness to complete when DOM construction and DOMContentLoaded events have completed
  • loadEventStart — timestamp before the page load event has fired
  • loadEventEnd — timestamp after the page load event and all assets are available

The Navigation Timing API collates timings for unloading the previous page, redirects, DNS lookups, page loading, file sizes, load events, and more. The information would be difficult to reliably determine in any other way.

Navigation timing is available to client-side JavaScript window and Web Worker functions. Pass a "navigation" type to the performance.getEntriesByType():

1const pageTiming = performance.getEntriesByType('navigation');

or the page URL to performance.getEntriesByName():

1const pageTiming = performance.getEntriesByName(window.location);

Either option returns an array with a single element containing a PerformanceNavigationTiming object (see load timing properties). It contains read-only properties about the resource load times, e.g.

2 connectEnd: 139
3 connectStart: 103
4 decodedBodySize: 72325
5 domComplete: 771
6 domContentLoadedEventEnd: 634
7 domContentLoadedEventStart: 630
8 domInteractive: 421
9 domainLookupEnd: 103
10 domainLookupStart: 87
11 duration: 771
12 encodedBodySize: 13091
13 entryType: "navigation"
14 fetchStart: 0
15 initiatorType: "navigation"
16 loadEventEnd: 771
17 loadEventStart: 771
18 name: ""
19 nextHopProtocol: "h2"
20 redirectCount: 0
21 redirectEnd: 0
22 redirectStart: 0
23 requestStart: 140
24 responseEnd: 154
25 responseStart: 154
26 secureConnectionStart: 115
27 serverTiming: Array []
28 startTime: 0
29 transferSize: 13735
30 type: "reload"
31 unloadEventEnd: 171
32 unloadEventStart: 169
33 workerStart: 0

You can use it to calculate useful page loading metrics from users, e.g.

1if ('performance' in window) {
3 const
4 pageTiming = performance.getEntriesByName(window.location)[0],
5 pageDownload = pageTiming.duration,
6 pageDomReady = pageTiming.domContentLoadedEventStart,
7 pageFullyReady = pageTiming.loadEventEnd;

Resource timing

You can examine load timings for other resources such as images, stylesheets, scripts, Fetch, and XMLHttpRequest Ajax calls in a similar way to the page.

Resource timing is available to client-side JavaScript window and Web Worker functions. Pass a "resource" type to the performance.getEntriesByType() to return an array. Each element is a PerformanceResourceTiming object (see load timing properties) representing a resource loaded by the page (but not the page itself):

1const resourceTiming = performance.getEntriesByType('resource');

example result:

2 {
3 name: "",
4 entryType: "resource",
5 initiatorType: "script",
6 fetchStart: 102,
7 duration: 51
8 ...etc...
9 },
10 {
11 name: "",
12 entryType: "resource",
13 initiatorType: "link",
14 fetchStart: 323,
15 duration: 54
16 ...etc...
17 },
18 {
19 name: "",
20 entryType: "resource",
21 initiatorType: "xmlhttprequest",
22 fetchStart: 598,
23 duration: 30
24 ...etc...
25 },
26 ...etc...

You can also fetch a resource by passing its exact URL to performance.getEntriesByName():

1const resourceTiming = performance.getEntriesByName('');

This returns an array with a single element:

2 {
3 name: "",
4 entryType: "resource",
5 initiatorType: "link",
6 fetchStart: 323,
7 duration: 54
8 ...etc...
9 }

You could use this to report to calculate the load times and sizes of each JavaScript resource as well as the total:

1if ('performance' in window) {
3 // total size of all JavaScript files
4 let scriptTotalSize = 0;
6 // array of script names, load times, and uncompressed file sizes
7 const script = performance.getEntriesByType('resource')
8 .filter( r => r.initiatorType === 'script')
9 .map( r => {
11 let size = r.decodedBodySize;
12 scriptTotalSize += size;
14 return {
15 name:,
16 load: r.duration,
17 size
18 };
20 });

The Performance API records at least 150 resource metrics, but you can define a specific number with performance.setResourceTimingBufferSize(N), e.g.

1// record metrics for 300 page resources

You can clear existing metrics with performance.clearResourceTimings(). This may be practical when you no longer require page resource information but want to record Ajax requests:

1// clear timings
4// API Fetch request
5const res = await Fetch('/service1/');
7// one resource returned
8const resourceTiming = performance.getEntriesByType('resource');

Paint timing

The Paint Timing API is available to client-side JavaScript window functions and records two rendering operations observed during page construction.

Pass a "paint" type to the performance.getEntriesByType() to return an array containing two PerformancePaintTiming objects:

1const paintTiming = performance.getEntriesByType('paint');

The result:

2 {
3 "name": "first-paint",
4 "entryType": "paint",
5 "startTime": 242,
6 "duration": 0
7 },
8 {
9 "name": "first-contentful-paint",
10 "entryType": "paint",
11 "startTime": 243,
12 "duration": 0
13 }


  • first-paint: the browser has painted the first pixel on the page, and

  • first-contentful-paint: the browser has painted the first item of DOM content, such as text or an image.

Note that "duration" will always be zero. returns a high-resolution timestamp in fractions of a millisecond since the beginning of the process’s lifetime. The method is available in client-side JavaScript, Web Workers, Node.js, and Deno.

In client-side JavaScript, the timer starts at zero when the process responsible for creating the document started. Web Worker, Node.js, and Deno timers start when the script process initially executes.

Note that Node.js scripts must load the Performance hooks (perf_hooks) module to use the Performance API. In CommonJS:

1const { performance } = require('perf_hooks');

or as an ES module:

1import { performance } from 'perf_hooks';

You can use to time scripts, e.g.

1const doSomethingStart =;
5const doSomethingElapsed = - doSomethingStart;

A further non-standard timeOrigin property returns the timestamp at which the current process began. This is measured in Unix time since 1 January 1970 and is available in Node.js and browser JavaScript (not IE or Safari):

1const doSomethingStart = performance.timeOrigin;
5const doSomethingElapsed = performance.timeOrigin - doSomethingStart;

User timing becomes cumbersome when taking more than a couple of timing measurements. The performance.mark() method adds a named PerformanceMark object object with a timestamp to the performance buffer. It’s available in client-side JavaScript, Web Workers, Node.js, and Deno:

1// Node.js scripts require:
2// CommonJS: const { performance } = require('perf_hooks');
3// or ESM : import { performance } from 'perf_hooks';

Pass a "mark" type to the performance.getEntriesByType() to return an array of marks:

1const userTiming = performance.getEntriesByType('mark');

The resulting array contains objects with name and startTime properties:

2 {
3 detail: null
4 duration: 0
5 entryType: "mark"
6 name: "script:start"
7 startTime: 100
8 },
9 {
10 detail: null
11 duration: 0
12 entryType: "mark"
13 name: "doSomething1:start"
14 startTime: 100
15 },
16 {
17 detail: null
18 duration: 0
19 entryType: "mark"
20 name: "doSomething1:end"
21 startTime: 123
22 },
23 ...etc...

The performance.measure() method calculates the elapsed time between two marks. It’s passed the measure name, the start mark name (or a falsy value to use the page/script load time), and the end mark name (or a falsy value to use the current time), e.g.

1performance.measure('doSomething1', 'doSomething1:start', 'doSomething1:end');
2performance.measure('script', null, 'doSomething1:end');

This adds a PerformanceMeasure object to the performance buffer with a calculated duration. Pass a "measure" type to the performance.getEntriesByType() to return an array of measures:

1const userTiming = performance.getEntriesByType('measure');

The resulting array:

2 {
3 detail: null
4 duration: 211
5 entryType: "measure"
6 name: "doSomething1"
7 startTime: 100
8 },
9 {
10 detail: null
11 duration: 551
12 entryType: "measure"
13 name: "script"
14 startTime: 100
15 }

You can also fetch mark and measure entries by name using performance.getEntriesByName():


Other useful methods include:

Frontend Monitoring

OpenReplay is a frontend monitoring tool that replays everything your users do and shows how your web app behaves for every issue. It lets you reproduce issues, aggregate JS errors and monitor your web app’s performance.

Happy debugging, for modern frontend teams - Start monitoring your web app for free.


The PerformanceObserver interface can watch for changes to the performance buffer and run a function when specific objects appear. It’s most practically used for mark, measure, and resource loading events (navigation and paint timings will generally occur before a script has started).

First, define an observer function. This could log an event or post the data to a statistics endpoint:

1function performanceObserver(list, observer) {
3 list.getEntries().forEach(entry => {
5 console.log('---');
6 console.log(`name : ${ }`);
7 console.log(`type : ${ entry.type }`);
8 console.log(`start : ${ entry.startTime }`);
9 console.log(`duration: ${ entry.duration }`);
11 });

The function has the following parameters:

  1. a list of observer entries, and

  2. the observer object so it’s possible to disconnect() if necessary.

Pass this function when creating a new PerformanceObserver object then run the observe() method with the entryTypes to observe:

1let observer = new PerformanceObserver(performanceObserver);
2observer.observe({ entryTypes: ['mark', 'measure'] });

Adding a new mark or measure will now run the performanceObserver() function and display details about that measurement.

Future performance options

Chrome-based browsers offer a non-standard performance.memory property which returns a single MemoryInfo object:

2 jsHeapSizeLimit: 4294705152
3 totalJSHeapSize: 5092217
4 usedJSHeapSize: 3742009


  • jsHeapSizeLimit — the maximum size of the heap in bytes
  • totalJSHeapSize — the total allocated heap size in bytes, and
  • usedJSHeapSize — The currently active segment of JS heap in bytes.

The Frame timing API is not implemented in any browser, but will record the amount of browser work in one event loop iteration. This includes processing DOM events, CSS animations, rendering, scrolling, resizing, etc. The API should be able to report potential jerkiness when a frame takes longer than 16.7 milliseconds so updates drop below 60 frames per second.

Finally, the Self-Profiling API is an experimental feature under development in Chrome. Given a sample rate, the API will help locate slow or unnecessary code in a similar way to the DevTools performance report:

1// define a new profiler with 10ms sample rate
2const profile = await performance.profile({ sampleInterval: 10 });
4// run code
7// stop the profiler and capture a trace
8const trace = await profile.stop();

Pinpoint performance problems

It’s easy to presume your application runs well when you’re developing on a new PC connected to a fast network. The performance API offers a way to prove — or disprove — performance issues by collecting real user metrics based on their devices, connections, and locations.

More articles from OpenReplay Blog

A Practical Introduction to Svelte

Svelte is a radical new approach to building user interfaces, or so they say.

May 11th, 2021 · 8 min read

Keeping Your TypeScript Code DRY With Generics

Generics can be a great tool to help you keep your code DRY and avoid repeating logic, learn how to take advantage of them in this tutorial

May 11th, 2021 · 5 min read
© 2021 OpenReplay Blog
Link to $ to $ to $