User timing
User Timing is part of the Performance API and allows you to measure the performance of applications usinghigh-precision timestamps that are part of the browser's performance timeline.There are two types of timing performance entries:
PerformanceMarkentries are marks that you can name and add at any location in an application.PerformanceMeasureentries are time measurements between two marks.
What is User Timing?
The browser provides certain information (calledperformance entries) to the browser's performance timeline for you. This includes, for example, entries provided by theResource Timing API that determine the time it takes to fetch a resource like an image.
The browser, however, can not determine what is going on in your application. For example, when a user clicks a button or performs a specific task within your application, there is no high-precision performance measurement. The User Timing API is an extension to the browser's performance timeline and helps you to measure and record performance data that is custom to your application.
The advantage of using this API, over calls toDate.now() orperformance.now(), is that you can give the markers a name and that it integrates well with performance tooling. Browser's developer tools can display performance marks in Performance Panels, and it also works with other performance APIs likePerformanceObserver objects.
Adding performance markers
As a first step to start measuring the performance of your app's functionality, you need to add named performance markers at important places in your code. Ideally, you go through your codebase and determine critical paths and important tasks for which you want to ensure they can be performed fast.
Theperformance.mark() method is used to create aPerformanceMark. The method takes one argument, thename of the mark, as shown in the following example.
// Place at a location in the code that starts loginperformance.mark("login-started");// Place at a location in the code that finishes loginperformance.mark("login-finished");If thename argument isn't enough,mark() is configurable using an options object where you can put additional information in thedetail property, which can be of any type. You can also set a differentstartTime if needed. In the following code, thestartTime is set to12.5, and additional information, like the HTML element used, is provided withdetail.
performance.mark("login-started", { startTime: 12.5, detail: { htmlElement: myElement.id },});Measuring duration between markers
Now that you added markers to your application, you can measure the time between them.
ThePerformance.measure() method is used to create aPerformanceMeasure object. It accepts aname parameter, used to identify the measure, and two marks,start andend, that it should measure between. The following example creates a"login-duration" measure and measures between the start and the finish of the login process.
The object then has aduration property which calculates the end mark timestamp minus the start mark timestamp for you. For example, you can log this value or send it to some analytics endpoint.
const loginMeasure = performance.measure( "login-duration", "login-started", "login-finished",);console.log(loginMeasure.duration);ThePerformance.measure() method is also configurable using an options object, so you can do more advanced measurements or provide additional information using thedetail property.
For example, you can use theevent.timestamp property from aclick event to know exactly when a user clicked login and measure that to the point in time when the UI was updated, which is the"login-finished" marker here.
loginButton.addEventListener("click", (clickEvent) => { fetch(loginURL).then((data) => { renderLoggedInUser(data); const marker = performance.mark("login-finished"); performance.measure("login-click", { detail: { htmlElement: myElement.id }, start: clickEvent.timeStamp, end: marker.startTime, }); });});Observing performance measures
The preferred way to get notified about your custom performance measures is the use ofPerformanceObserver objects. Performance observers allow you to subscribe passively to performance marks and measures as they happen.
function perfObserver(list, observer) { list.getEntries().forEach((entry) => { if (entry.entryType === "mark") { console.log(`${entry.name}'s startTime: ${entry.startTime}`); } if (entry.entryType === "measure") { console.log(`${entry.name}'s duration: ${entry.duration}`); } });}const observer = new PerformanceObserver(perfObserver);observer.observe({ entryTypes: ["measure", "mark"] });For more information, seePerformanceObserver.
Retrieving markers and measures
There are many different performance entries in the browser's performance timeline. Some are added by the browser, and some might be added by you, like the login markers and measures from the examples above.
To retrieve performance marks and measures at a single point in time, thePerformance interface provides three methods, as shown below.
Note:The methods below do not notify you about new performance markers; you will only get markers that have been created when you call these methods.See the sectionObserving performance measures above for receiving notifications about new metrics as they become available using aPerformanceObserver. Usually, using performance observers is the preferred way to get performance markers and measures.
Theperformance.getEntries() method gets all performance entries. You can filter them as needed.
const entries = performance.getEntries();entries.forEach((entry) => { if (entry.entryType === "mark") { console.log(`${entry.name}'s startTime: ${entry.startTime}`); } if (entry.entryType === "measure") { console.log(`${entry.name}'s duration: ${entry.duration}`); }});Theperformance.getEntriesByType(entryType) method filters the entries by type already.
const marks = performance.getEntriesByType("mark");marks.forEach((entry) => { console.log(`${entry.name}'s startTime: ${entry.startTime}`);});const measures = performance.getEntriesByType("measure");measures.forEach((entry) => { console.log(`${entry.name}'s duration: ${entry.duration}`);});Theperformance.getEntriesByName(name, entryType) method allows you to get specific marks or measures by name.
// Log all marks named "debug-marks"const debugMarks = performance.getEntriesByName("debug-mark", "mark");debugMarks.forEach((entry) => { console.log(`${entry.name}'s startTime: ${entry.startTime}`);});Removing markers and measures
To clean up all performance marks or measures, or just specific entries, the following methods are available:
// Clear all marksperformance.clearMarks();// Removes the marker with the name "myMarker"performance.clearMarks("myMarker");// Clear all measuresperformance.clearMeasures();// Removes the measure with the name "myMeasure"performance.clearMeasures("myMeasure");