Skip to main content

The User Timing API: Custom Front-end Performance Metrics

· Updated on · 2 min read

Page speed testing tools collect a range of general-purpose performance metrics when loading a website. For example, they collect data on Core Web Vitals metrics like the Largest Contentful Paint or on the download size of the web page.

However, these metrics aren't tailored to the needs of your users. If you build a chat app the most important thing might be that messages are rendered quickly, even if the user can't send messages yet. For a game you might want to wait until all graphical assets are loaded, but not worry too much about the soundtrack being ready.

To solve this browsers have implemented the User Timing API which allows you to define custom performance metrics that track what's most important to your users. For example, Twitter used "Time to first tweet" as an important metric.

Storing a timestamp with performance.mark

The mark function is the core of the User Timing API. It captures a timestamp at the current time and assigns a name to it:

performance.mark("Start Rendering");

You can then access the timings with performance.getEntriesByType("mark"):

Example of the created user timing mark in the console

Measuring time spans with performance.measure

If you want to track the duration of a specific step you can use performance.measure. It takes three arguments:

  • The name of the time span being measured
  • The name of the performance.mark entry at the start
  • The name of the performance.mark entry at the end

Here's an example:

performance.mark("Start rendering");
for (var i = 0; i < 1000; i++) {
document.body.innerHTML += Math.random().toString().slice(1) + " ";
performance.mark("Finish rendering");
performance.measure("Rendering", "Start rendering", "Finish rendering");

We can read the measure duration from performance.getEntriesByType("measure"), and it also shows up in the DevTools performance tab:

Screenshot showing user timings in the the Performance tab of Chrome DevTools

In development mode React also uses this API to track component timings automatically:

Example of React component timings in the DevTools Performance tab

Monitoring user timings in DebugBear

If you monitor your site with DebugBear user timing metrics will be collected automatically. For example, you can see them in the project performance dashboard:

Chart showing how user timings are monitored continuously

Get a monthly email with page speed tips