Custom front-end performance metrics with the User Timing API

Browsers collect a bunch of general-purpose performance metrics when loading a page. For example, you can check when the Load event fired or use the PerformancePaintTiming API to see when content first appeared on the screen.

The problem with these metrics is that they 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.

The solution to this is 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"):

Measuring elapsed time 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 timespan 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:

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

Monitoring user timings in DebugBear

If you monitor your site with DebugBear your metrics will show up in the Performance tab automatically: