Debug performance in the field

Google currently provides two categories of tools to measure and debug performance:

• Lab tools: Tools such as Lighthouse, where your page is loaded in a simulated environment that can mimic various conditions (for example, a slow network and a low-end mobile device).
• Field tools: Tools such as Chrome User Experience Report (CrUX), which is based on aggregate, real-user data from Chrome. (Note that the field data reported by tools such as PageSpeed Insights and Search Console is sourced from CrUX data.)

While field tools offer more accurate data—data which actually represents what real users experience—lab tools are often better at helping you identify and fix issues.

CrUX data is more representative of your page’s real performance, but knowing your CrUX scores is unlikely to help you figure out how to improve your performance.

Lighthouse, on the other hand, will identify issues and make specific suggestions for how to improve. However, Lighthouse will only make suggestions for performance issues it discovers at page load time. It does not detect issues that only manifest as a result of user interaction such as scrolling or clicking buttons on the page.

This raises an important question: how can you capture debug information for Core Web Vitals or other performance metrics from real users in the field?

This post will explain in detail what APIs you can use to collect additional debugging information for each of the current Core Web Vitals metrics and give you ideas for how to capture this data in your existing analytics tool.

APIs for attribution and debugging #

CLS #

Of all the Core Web Vitals metrics, CLS is perhaps the one for which collecting debug information in the field is the most important. CLS is measured throughout the entire lifespan of the page, so the way a user interacts with the page—how far they scroll, what they click on, and so on—can have a significant impact on whether there are layout shifts and which elements are shifting.

Consider the following report from PageSpeed Insights for the URL: web.dev/measure

The value reported for CLS from the lab (Lighthouse) compared to the CLS from the field (CrUX data) are quite different, and this makes sense if you consider that the web.dev/measure page has a lot of interactive content that is not being used when tested in Lighthouse.

But even if you understand that user interaction affects field data, you still need to know what elements on the page are shifting to result in a score of 0.45 at the 75th percentile.

The LayoutShiftAttribution interface makes that possible.

Get layout shift attribution #

The LayoutShiftAttribution interface is exposed on each layout-shift entry that Layout Instability API emits.

For a detailed explanation of both of these interfaces, see Debug layout shifts. For the purposes of this post, the main thing you need to know is that, as a developer, you are able to observe every layout shift that happens on the page as well as what elements are shifting.

Here’s some example code that logs each layout shift as well as the elements that shifted:

new PerformanceObserver((list) => {
for (const {value, startTime, sources} of list.getEntries()) {
// Log the shift amount and other entry info.
console.log('Layout shift:', {value, startTime});
if (sources) {
for (const {node, curRect, prevRect} of sources) {
// Log the elements that shifted.
console.log('  Shift source:', node, {curRect, prevRect});
}
}
}
}).observe({type: 'layout-shift', buffered: true});

It’s probably not practical to measure and send data to your analytics tool for every single layout shift that occurs; however, by monitoring all shifts, you can keep track of the worst shifts and just report information about those.

The goal isn’t to identify and fix every single layout shift that occurs for every user; the goal is to identify the shifts that affect the largest number of users and thus contribute the most to your page’s CLS at the 75th percentile.

Also, you don’t need to compute the largest source element every time there’s a shift, you only need to do so when you’re ready to send the CLS value to your analytics tool.

The following code takes a list of layout-shift entries that have contributed to CLS and returns the largest source element from the largest shift:

function getCLSDebugTarget(entries) {
const largestEntry = entries.reduce((a, b) => {
return a && a.value > b.value ? a : b;
});
if (largestEntry && largestEntry.sources && largestEntry.sources.length) {
const largestSource = largestEntry.sources.reduce((a, b) => {
return a.node && a.previousRect.width * a.previousRect.height >
b.previousRect.width * b.previousRect.height ? a : b;
});
if (largestSource) {
return largestSource.node;
}
}
}

Once you’ve identified the largest element contributing to the largest shift, you can report that to your analytics tool.

The element contributing the most to CLS for a given page will likely vary from user to user, but if you aggregate those elements across all users, you’ll be able to generate a list of shifting elements affecting the most number of users.

After you’ve identified and fixed the root cause of the shifts for those elements, your analytics code will start reporting smaller shifts as the “worst” shifts for your pages. Eventually, all reported shifts will be small enough that your pages are well within the “good” threshold of 0.1!

Some other metadata that may be useful to capture along with the largest shift source element is:

• The time of the largest shift
• The URL path at the time of the largest shift (for sites that dynamically update the URL, such as Single Page Applications).

LCP #

To debug LCP in the field, the primary information you need is which particular element was the largest element (the LCP candidate element) for that particular page load.

Note that it’s entirely possible—in fact, it’s quite common—that the LCP candidate element will be different from user to user, even for the exact same page.

This can happen for several reasons:

• User devices have different screen resolutions, which results in different page layouts and thus different elements being visible within the viewport.
• Users don’t always load pages scrolled to the very top. Oftentimes links will contain fragment identifiers or even text fragments, which means it’s possible for your pages to be loaded and displayed at any scroll position on the page.
• Content may be personalized for the current user, so the LCP candidate element could vary wildly from user to user.

This means you cannot make assumptions about which element or set of elements will be the most common LCP candidate element for a particular page. You have to measure it based on real-user behavior.