What is the User Timing API?

What is the User Timing API?

The User Timing API is part of the Web Performance API. It lets your own JavaScript put named timestamps (marks) and the time between them (measures) on the browser's high-resolution performance timeline, so you can time steps only your app knows about, such as "search results rendered" or "checkout form ready".

How it works

• performance.mark(name) creates a PerformanceMark (entry type mark) at the current time. Options: startTime and detail.
• performance.measure(name, startMark, endMark) creates a PerformanceMeasure (entry type measure). Its duration is the end minus the start. You can also pass an options object with start, end, duration and detail. Without an end, it ends now.
• Read entries with a PerformanceObserver, which MDN calls the preferred way, or with performance.getEntriesByType('measure'). Remove them with clearMarks() and clearMeasures().

In the Chrome DevTools Performance panel, a mark whose detail carries a devtools object with dataType: 'marker' shows in the Timings track, and measures with dataType: 'track-entry' draw custom tracks (switch on "Show custom tracks" in the capture settings). Support for this extension varies by browser. Details: MDN.

Example

Time how long a search takes from request to rendered results:

performance.mark('search-start');
const data = await fetch('/api/search?q=shoes').then(r => r.json());
renderResults(data);
performance.mark('search-rendered');
performance.measure('search-total', 'search-start', 'search-rendered');
const [m] = performance.getEntriesByName('search-total');
console.log(m.duration);

The result is one search-total entry with a duration in milliseconds, visible in code and in developer tools.

User Timing next to its siblings

Navigation Timing covers the built-in page load stages, and the Server-Timing header carries backend durations. User Timing is for the steps in between that only your code can name. Send the measures to your analytics and you have real user monitoring for your own flows. For page load and Core Web Vitals from fixed locations, see LoadFocus page speed monitoring. A wider view is in the guide to frontend performance testing.

Common mistakes

• Measuring before the end mark exists. A named mark that is missing throws a SyntaxError.
• Mixing up the option forms. duration is valid only with exactly one of start or end, otherwise TypeError.
• Reusing one name for different steps. getEntriesByName() then returns several entries, so name each step clearly.
• Never clearing entries in a long-lived single-page app. Clear marks and measures you have already reported.
• Marking inside tight loops. It floods the timeline and hides the steps that matter.

FAQ: User Timing API

What is the difference between a mark and a measure?

A mark is a named point in time. A measure is the duration between two points, which can be two marks, timestamps or one of each.

Do I need a PerformanceObserver?

No, but it is the better choice because it notifies you when entries are created. The get methods only return entries that already exist.

How do I see marks and measures in DevTools?

Record a profile in the Performance panel. Add a devtools object to detail to place markers in the Timings track or measures in custom tracks.

Is it the same as performance.now()?

No. performance.now() returns a timestamp. User Timing records named entries on the performance timeline that tools and observers can read.

Does it work in Web Workers?

Yes, MDN lists performance.measure() as available in workers.