Brendan Kenny on web.dev

Using the Web Vitals extension to debug Core Web Vitals issues

2023-05-04T00:00:00Z

The Web Vitals extension provides easy access to Core Web Vitals diagnostic information to help developers measure, and address Core Web Vitals issues. It supplements the other tools provided by the Chrome team to aid developers in improving the experiences on their websites.

We have updated the extension to provide additional debug information to developers to make it easier to understand and address their performance problems.

Showing debug information in the console #

The Web Vitals extension has had a "Console Logging" debug option for some time now. It can be enabled in the Options screen:

Prior to the this last upgrade, this logged the outputs from the web-vitals library (that underpins the extension) in a JSON object:

This object could then be expanded to get the full details, and elements such as the LCP image, could be hovered over to highlight them in the main panel:

This was helpful, but the output format was not particularly user friendly, and we thought we could provide a better developer experience. So we have improved the extension to make the most important information more visible—while still including the full object for those wanting more details.

New debug information for each metric #

With the new release, we have added new debug information in a more readable format to help you find and address issues. Different information is provided for each of the metrics, as each one is different.

LCP debug information #

For Largest Contentful Paint (LCP), we show both the element, and the breakdown of the 4 phases detailed in our Optimize LCP guide:

The LCP time (2,876 milliseconds—or about 2.9 seconds) is highlighted in amber as it is in the "Needs Improvement" category.

In this example, we see the Resource load time is the longest time, so to improve your LCP time you would look to optimize that - perhaps by avoiding hosting them on a separate domain, or by using smaller images or more efficient formats. In this case it's due to being artificially slowed down to demonstrate the output—web.dev is a fast site 😀

The element can also be hovered over to highlight the image:

Right clicking on the element also allows you to reveal it in the elements panel.

Here the LCP element is an image, and hovering over that in the console on the right, also highlights that element on the site on the left.

CLS debug information #

Shifts contributing to Cumulative Layout Shift (CLS) are now also listed, and can be hovered over to highlight the relevant element:

The above screenshot shows 2 shifts, the first made up of two elements (when the banner image is loaded and the content beneath it is shifted downloaded), and the second of 4 elements (when the dynamic ad is loaded and most of the page is shifted downwards).

The h2 element is being hovered over in this screenshot in the console on the right, and you can see this highlights the element on the site on the left.

FID debug information #

For First Input Delay (FID) we show the affected element (which again, can be hovered over to highlight it on the page) and the interaction type, along with the full JSON object as usual:

INP debug information #

For Interaction to Next Paint (INP), we have added two new logs:

INP - the longest interaction
Interactions - all interactions

INP metric #

First up, we highlight the INP metric when it changes:

Similar to LCP, the extension breaks down the INP time to show three phases:

Input delay
Processing time
Presentation delay

This helps you identify if the event was slow due to being held up by other events (input delay), as the event handler itself was slow due to your code (processing time), if the post-processing render delay was the reason (presentation delay), or a combination of two or more of these.

Interactions #

INP can be slow due to previous interactions blocking the main thread, and thus causing a high input delay. For this reason, we list all interactions in a similar format to the INP logging:

This allows you to "live trace" a website by interacting with it and seeing in the console which interactions, in which combinations, are likely to cause an INP problem.

This also allows you to identify multiple slow interactions, rather than just the largest INP interaction to help you avoid the feeling of chasing your tail when improving your responsiveness.

Filtering the console logs #

All this extra information, while useful, can be distracting if you are doing other development unrelated to Core Web Vitals, or are only interested in one particular Core Web Vital at that time.

You can use the Console filtering options in DevTools to filter out some or all of the messages:

To remove all the extension messages, you can either turn this off in the options or use the -Extension filter.
To look at just LCP you can use the Web Vitals Extension LCP filter.
To look at just INP and interactions you can use the Web Vitals Extension -LCP -CLS -FID filter.

We're trying to keep the number of options for this extension down, but do let us know by raising a GitHub issue if DevTools filtering is not sufficient and you would prefer options here.

Conclusion #

We hope you find the new debug options in the latest version of the extension useful and that they make it easier to identify and resolve Core Web Vitals issues, improving the user experiences on your website.

Do remember that your experiences, on your developer computer, may not be representative of what your real users are experiencing. Check out our previous blog post on how you can view the CrUX field data for your site in the extension to get a sense of how aligned your experiences are with your users.

We would be grateful to hear any feedback on these improvements, or any other suggestions on our GitHub issues tracker.

Acknowledgements #

Hero image by Farzad on Unsplash

Our top Core Web Vitals recommendations for 2023

2023-01-10T00:00:00Z

Over the years, we at Google have made a lot of recommendations to web developers on how to improve performance.

While each of these recommendations, individually, may improve performance for many sites, the full set of recommendations is admittedly overwhelming and, realistically, there's no way any one person or site could follow all of them.

Unless web performance is your day job, it's probably not obvious which recommendations are going to have the largest positive impact on your site. For example, you might have read that implementing critical CSS can improve load performance, and you may have also heard that it's important to optimize your images. But, if you don't have time to work on both things, how would you decide which one to pick?

On the Chrome team, we've spent the last year trying to answer this question: what are the most important recommendations we can give to developers to help them improve performance for their users?

To adequately answer this question we have to consider not just the technical merits of any given recommendation, but also human and organizational factors that influence the likelihood that developers will actually be able to adopt these recommendations. In other words, some recommendations may be hugely impactful in theory, but in reality very few sites will have the time or resources to implement them. Similarly, some recommendations are critical, but most websites are already following these practices.

In short, we wanted our list of top web performance recommendations to focus on:

Recommendations we believe will have the largest real-world impact
Recommendations that are relevant and applicable to most sites
Recommendations that are realistic for most developers to implement

Over the past year we've spent a lot of time auditing the full set of performance recommendations we make, and assessing each of them (both qualitatively and quantitatively) against the above three criteria.

This post outlines our top recommendations to improve performance for each of the Core Web Vitals metrics. If you're new to web performance, or if you're trying to decide what will give you the biggest bang for your buck, we think these recommendations are the best place to start.

Largest Contentful Paint (LCP) #

Our first set of recommendations are for Largest Contentful Paint (LCP), which is a measure of load performance. Of the three Core Web Vitals metrics, LCP is the one that the largest number of sites struggle with—only about half of all sites on the web today meet the recommended threshold—so let's start there.

Ensure the LCP resource is discoverable from the HTML source #

According to the 2022 Web Almanac by HTTP Archive, 72% of mobile pages have an image as their LCP element, which means that for most sites to optimize their LCP, they'll need to ensure those images can load quickly.

What may not be obvious to many developers is that the time it takes to load an image is just one part of the challenge. Another critical part is the time before an image starts loading, and HTTP Archive data suggests that's actually where many sites get tripped up.

In fact, of the pages where the LCP element was an image, 39% of those images had source URLs that were not discoverable from the HTML document source. In other words, those URLs were not found in standard HTML attributes (such as <img src="..."> or <link rel="preload" href="...">), which would allow the browser to quickly discover them and start loading them right away.

If a page needs to wait for CSS or JavaScript files to be fully downloaded, parsed, and processed before the image can even start loading, it may already be too late.

As a general rule, if your LCP element is an image, the image's URL should always be discoverable from the HTML source. Some tips to make that possible are:

Load the image using an <img> element with the src or srcset attribute. Do not use non-standard attributes like data-src that require JavaScript in order to render, as that will always be slower. 9% of pages obscure their LCP image behind data-src.
Prefer server-side rendering (SSR) over client-side rendering (CSR), as SSR implies that the full page markup (including the image) is present in the HTML source. CSR solutions require JavaScript to run before the image can be discovered.
If your image needs to be referenced from an external CSS or JS file, you can still include it in the HTML source via a <link rel="preload"> tag. Note that images referenced by inline styles are not discoverable by the browser's preload scanner, so even though they're found in the HTML source, discovery of them might still be blocked on the loading of other resources, so preloading can help in these cases.

To help you understand if your LCP image has discoverability problems, Lighthouse will be releasing a new audit in version 10.0 (expected January 2023).

Ensuring the LCP resource is discoverable from the HTML source can lead to measurable improvements and it also unlocks additional opportunities to prioritize the resource, which is our next recommendation.

Ensure the LCP resource is prioritized #

Making sure the LCP resource can be discovered from the HTML source is a critical first step in ensuring the LCP resource can start loading early, but another important step is ensuring that the loading of that resource is prioritized and doesn't get queued behind a bunch of other, less important resources.

For example, even if your LCP image is present in the HTML source using a standard <img> tag, if your page includes a dozen <script> tags in the <head> of your document before that <img> tag, it may be a while before your image resource starts loading.

The easiest way to solve this problem is to provide a hint to the browser about what resources are the highest priority by setting the new fetchpriority="high" attribute on the <img> or <link> tag that loads your LCP image. This instructs the browser to load it earlier, rather than waiting for those scripts to complete.

According to the Web Almanac, only 0.03% of eligible pages are taking advantage of this new API, meaning there is plenty of opportunity for most sites on the web to improve LCP with very little work. While the fetchpriority attribute is currently only supported in Chromium-based browsers, this API is a progressive enhancement that other browsers just ignore, so we strongly recommend developers use it now.

For non-Chromium browsers, the only way to ensure the LCP resource is prioritized above other resources is to reference it earlier in the document. Using the example again of a site with lots of <script> tags in the <head> of the document, if you wanted to ensure your LCP resource was prioritized ahead of those script resources, you could add a <link rel="preload"> tag before any of those scripts, or you could move those scripts to below the <img> later in the <body>. While this works, it's less ergonomic than using fetchpriority, so we hope other browsers add support soon.

Another critical aspect of prioritizing the LCP resource is to ensure you don't do anything that causes it to be deprioritized, such as adding the loading="lazy" attribute. Today, 10% of pages actually set loading="lazy" on their LCP image. Beware of image optimization solutions that indiscriminately apply lazy-loading behavior to all images. If they provide a way to override that behavior, be sure to use it for the LCP image. If you're not sure which image will be the LCP, try using heuristics to pick a reasonable candidate.

Deferring non-critical resources is another way to effectively boost the relative priority of the LCP resource. For example, scripts that are not powering the user interface (like analytics scripts or social widgets) can be safely postponed until after the load event fires, which ensures they won't compete with other critical resources (such as the LCP resource) for network bandwidth.

To summarize, you should follow these best practices to ensure that the LCP resource is loaded early, and at high priority:

Add fetchpriority="high" to the <img> tag of your LCP image. If the LCP resource is loaded via a <link rel="preload"> tag, fear not because you can also set fetchpriority="high" on that!
Never set loading="lazy" on the <img> tag of your LCP image. Doing this will deprioritize your image and delay when it starts loading.
Defer non-critical resources when possible. Either by moving them to the end of your document, using native lazy-loading for images or iframes, or loading them asynchronously via JavaScript.

Use a CDN to optimize document and resource TTFB #

The previous two recommendations focused on making sure your LCP resource is discovered early and prioritized so it can start loading right away. The final piece to this puzzle is making sure the initial document response arrives as quickly as possible too.

The browser cannot start loading any subresources until it receives the first byte of the initial HTML document response, and the sooner that happens, the sooner everything else can start happening as well.

This time is known as Time to First Byte (TTFB), and the best way to reduce TTFB is to:

Serve your content as geographically close to your users as possible
Cache that content so recently-requested content can be served again quickly.

The best way to do both of these things is to use a CDN. CDNs distribute your resources to edge servers, which are spread across the globe, thus limiting the distance those resources have to travel over the wire to your users. CDNs also usually have fine-grained caching controls that can be customized and optimized for your site's needs.

Many developers are familiar with using a CDN to host static assets, but CDNs can serve and cache HTML documents as well, even those that are dynamically generated.

According to the Web Almanac, only 29% of HTML document requests were served from a CDN, which means there is significant opportunity for sites to claim additional savings.

Some tips for configuring your CDNs are:

Consider increasing how long content is cached for (for example, is it actually critical that content is always fresh? Or can it be a few minutes stale?).
Consider maybe even caching content indefinitely, and then purging the cache if/when you make an update.
Explore whether you can move dynamic logic currently running on your origin server to the edge (a feature of most modern CDNs).

In general, any time you can serve content directly from the edge (avoiding a trip to your origin server) it's a performance win. And even in cases where you do have to make the journey all the way back to your origin server, CDNs are generally optimized to do that much more quickly, so it's a win either way.

Cumulative Layout Shift (CLS) #

The next set of recommendations are for Cumulative Layout Shift (CLS), which is a measure of visual stability on web pages. While CLS has improved a lot on the web since 2020, about a quarter of websites still do not meet the recommended threshold, so there remains a big opportunity for many sites to improve their user experience.

Set explicit sizes on any content loaded from the page #

Layout shifts usually happen when existing content moves after other content finishes loading. Therefore, the primary way to mitigate this is to reserve any required space in advance as much as possible.

The most straightforward way to fix layout shifts caused by unsized images is to explicitly set width and height attributes (or equivalent CSS properties). However, according to HTTP Archive, 72% of pages have at least one unsized image. Without an explicit size, browsers will initially set a default height of 0px and may cause a noticeable layout shift when the image is finally loaded and the dimensions are discovered. This represents both a huge opportunity for the collective web—and that opportunity requires much less effort than some of the other recommendations suggested in this article.

It's also important to keep in mind that images are not the only contributors to CLS. Layout shifts may be caused by other content that typically loads in after the page is initially rendered, including third-party ads or embedded videos. The aspect-ratio property can help combat this. It's a relatively new CSS feature that allows developers to explicitly provide an aspect ratio to images as well as non-image elements. This will allow you to set a dynamic width (for example based on screen size), and have the browser automatically calculate the appropriate height, in much the same way as they do for images with dimensions.

Sometimes it's not possible to know the exact size of dynamic content since it is, by its very nature, dynamic. However, even if you don't know the exact size, you can still take steps to reduce the severity of layout shifts. Setting a sensible min-height is almost always better than allowing the browser to use the default height of 0px for an empty element. Using a min-height is also usually an easy fix as it still allows the container to grow to the final content height if needed—it has just reduced that amount of growth from the full amount to a hopefully more tolerable level.

Ensure pages are eligible for bfcache #

Browsers use a navigation mechanism called the back/forward cache—or bfcache for short—to instantly load a page from earlier or later in the browser history directly from a memory snapshot.

The bfcache is a significant browser-level performance optimization, and it entirely eliminates the layout shifts during page load, which for many sites is where most of their CLS occurs. The introduction of the bfcache caused the biggest improvement in CLS that we saw in 2022.

Despite this, a significant number of websites are ineligible for the bfcache and so are missing out on this free web performance win for a significant number of navigations. Unless your page is loading sensitive information that you don't want to be restored from memory, you'll want to make sure that your pages are eligible.

Site owners should check that their pages are eligible for the bfcache and work on any reasons why they are not. Chrome already has a bfcache tester in DevTools and this year we plan to enhance tooling here with a new Lighthouse audit performing a similar test and an API to measure this in the field.

While we have included the bfcache in the CLS section, as we saw the biggest gains there so far, the bfcache will generally also improve other Core Web Vitals too. It is one of a number of instant navigations available to drastically improve page navigations.

Avoid animations/transitions that use layout-inducing CSS properties #

Another common source of layout shifts is when elements are animated. For example, cookie banners or other notification banners that slide in from the top or bottom are often a contributor to CLS. This is particularly problematic when these banners push other content out of the way, but even when they don't, animating them can still impact CLS.

While HTTP Archive data can't conclusively connect animations to layout shifts, the data does show that pages that animate any CSS property that could affect layout are 15% less likely to have "good" CLS than pages overall. Some properties are associated with worse CLS than others. For instance, pages that animate margin or border widths have "poor" CLS at almost twice the rate that pages overall are assessed as poor.

This is perhaps not surprising, because any time you transition or animate any layout-inducing CSS property, it will result in layout shifts, and if those layout shifts are not within 500 milliseconds of a user interaction, they will impact CLS.

What may be surprising to some developers is that this is true even in cases where the element is taken outside of the normal document flow. For example, absolutely positioned elements that animate top or left will cause layout shifts, even if they aren't pushing other content around. However, if instead of animating top or left you animate transform:translateX() or transform:translateY(), it won't cause the browser to update page layout and thus won't produce any layout shifts.

Preferring animation of CSS properties that can be updated on the browser's compositor thread has long been a performance best practice because it moves that work onto the GPU and off the main thread. And in addition to it being a general performance best practice, it can also help improve CLS.

As a general rule, never animate or transition any CSS property that requires the browser to update the page layout, unless you're doing it in response to a user tap or key press (though not hover). And whenever possible, prefer transitions and animations using the CSS transform property.

The Lighthouse audit Avoid non-composited animations will warn when a page animates potentially slow CSS properties.

First Input Delay (FID) #

Our last set of recommendations are for First Input Delay (FID), which is a measure of a page's responsiveness to user interactions. While most sites on the web currently score very well on FID, we've documented shortcomings of the FID metric in the past, and we believe there is still a lot of opportunity for sites to improve their overall responsiveness to user interactions.

Our new Interaction to Next Paint (INP) metric is a possible successor to FID, and all of the recommendations below apply equally well to both FID and INP. Given that sites perform worse on INP than FID, especially on mobile, we encourage developers to seriously consider these responsiveness recommendations, despite having "good" FID.

Avoid or break up long tasks #

Tasks are any piece of discrete work that the browser does. Tasks include rendering, layout, parsing, and compiling and executing scripts. When tasks become long tasks—that is, 50 milliseconds or longer—they block the main thread from being able to respond quickly to user inputs.

Per the Web Almanac, there's plenty of evidence to suggest that developers could be doing more to avoid or break up long tasks. While breaking up long tasks may not be as low of an effort as other recommendations in this article, it's less effort than other techniques not offered in this article.

While you should always strive to do as little work as possible in JavaScript, you can help the main thread quite a bit by breaking up long tasks into smaller ones. You can accomplish this by yielding to the main thread often so that rendering updates and other user interactions can occur more quickly.

Another option is to consider using APIs such as isInputPending and the Scheduler API. isInputPending is a function that returns a boolean value that indicates whether a user input is pending. If it returns true, you can yield to the main thread so it can handle the pending user input.

The Scheduler API is a more advanced approach, which allows you to schedule work based on a system of priorities that take into account whether the work being done is user-visible or backgrounded.

By breaking up long tasks, you're giving the browser more opportunities to fit in critical user-visible work, such as dealing with interactions and any resulting rendering updates.

Avoid unnecessary JavaScript #

There's no doubt about it: websites are shipping more JavaScript than ever before, and the trend doesn't look like it's changing any time soon. When you ship too much JavaScript, you're creating an environment where tasks are competing for the main thread's attention. This can definitely affect your website's responsiveness, especially during that crucial startup period.

This is not an unsolvable problem, however. You do have some options:

Use the coverage tool in Chrome DevTools to find unused code in your website's resources. By reducing the size of the resources you need during startup, you can ensure your website spends less time parsing and compiling code, which leads to a smoother initial user experience.
Sometimes the unused code you find using the coverage tool is marked "unused" because it wasn't executed during startup, but is still necessary for some functionality in the future. This is code that you can move to a separate bundle via code splitting.
If you're using a tag manager, be sure to periodically check your tags to make sure they are optimized, or even if they're still being used. Older tags with unused code can be cleared out to make your tag manager's JavaScript smaller and more efficient.

Avoid large rendering updates #

JavaScript isn't the only thing that can affect your website's responsiveness. Rendering can be a type of expensive work in its own right—and when large rendering updates happen, they can interfere with your website's ability to respond to user inputs.

Optimizing rendering work isn't a straightforward process, and it often depends on what you're trying to achieve. Even so, there are some things you can do to ensure that your rendering updates are reasonable, and don't sprawl into long tasks:

Avoid using requestAnimationFrame() for doing any non-visual work. requestAnimationFrame() calls are handled during the rendering phase of the event loop, and when too much work is done during this step, rendering updates can be delayed. It's essential that any work you're doing with requestAnimationFrame() is reserved strictly for tasks that involve rendering updates.
Keep your DOM size small. DOM size and the intensity of layout work are correlated. When the renderer has to update the layout for a very large DOM, the work required to recalculate its layout can increase significantly.
Use CSS containment. CSS containment relies on the CSS contain property, which gives instructions to the browser about how to do layout work for the container the contain property is set on, including even isolating the scope of layout and rendering to a specific root in the DOM. It's not always an easy process, but by isolating areas containing complex layouts, you can avoid doing layout and rendering work for them that isn't necessary.

Conclusion #

Improving page performance can seem like a daunting task, especially given that there is a mountain of guidance across the web to consider. By focusing on these recommendations, however, you can approach the problem with focus and purpose, and hopefully move the needle for your website's Core Web Vitals.

While the recommendations listed here are by no means exhaustive, we do believe—based on careful analysis of the state of the web—that these recommendations are the most effective ways that sites can improve their Core Web Vitals performance in 2023.

If you'd like to go beyond the recommendations listed here, check out these optimization guides for more information:

Here's to a new year, and a faster web for all! May your sites be fast for your users in all the ways that matter most.

Photo by Devin Avery

Lighthouse user flows

2021-11-03T00:00:00Z

Lighthouse is a fantastic tool for testing performance and best practices during initial page load. However, it's traditionally been difficult to use Lighthouse to analyze other aspects of the life of a page, such as:

Page loads with a warm cache
Pages with an activated Service Worker
Accounting for potential user interactions

This means that Lighthouse can miss vital information. The Core Web Vitals are based on all page loads, not just those with an empty cache. Additionally, metrics like Cumulative Layout Shift (CLS) are measurable for the entire time a page is open.

Lighthouse has a new user flow API that allows lab testing at any point within a page's lifespan. Puppeteer is used to script page loads and trigger synthetic user interactions, and Lighthouse can be invoked in multiple ways to capture key insights during those interactions. This means that performance can be measured during page load and during interactions with the page. Accessibility checks can be run in CI, not just on the initial view but deep within your checkout flow to make sure nothing regresses.

Almost any Puppeteer script written to ensure a working user flow can now have Lighthouse inserted at any point to measure performance and best practices throughout. This tutorial will walk through the new Lighthouse modes that can measure different parts of user flows: navigations, snapshots, and timespans.

Setup #

The user flow APIs are still in preview, but they are available in Lighthouse today. To try out the demos below, you'll need Node version 14 or later. Create an empty directory and in it run:

# Default to ES modules.
echo '{"type": "module"}' > package.json

# Init npm project without the wizard.
npm init -y

# Dependencies for these examples.
npm install lighthouse puppeteer open

Navigations #

The new Lighthouse "navigation" mode is actually giving a name to the (up until now) standard Lighthouse behavior: analyze the cold load of a page. This is the mode to use to monitor page load performance, but user flows also open up the possibility of new insights.

To script Lighthouse capturing a page load:

Use puppeteer to open the browser.
Start a Lighthouse user flow.
Navigate to the target URL.

import fs from 'fs';
import open from 'open';
import puppeteer from 'puppeteer';
import {startFlow} from 'lighthouse/lighthouse-core/fraggle-rock/api.js';

async function captureReport() {
  const browser = await puppeteer.launch({headless: false});
  const page = await browser.newPage();

  const flow = await startFlow(page, {name: 'Single Navigation'});
  await flow.navigate('https://web.dev/performance-scoring/');

  await browser.close();

  const report = await flow.generateReport();
  fs.writeFileSync('flow.report.html', report);
  open('flow.report.html', {wait: false});
}

captureReport();

This is the simplest flow. When opened, the report shows a summary view with only the single step. Clicking on that step will reveal a traditional Lighthouse report for that navigation.

See the report live

As is typical with Lighthouse, this page is loaded with any cache or local storage cleared first, but real users visiting a site will have a mixture of visits with cold and warm caches, and there can be a large performance difference between a cold load like this and a user returning to the page with a still-warm cache.

Capturing a warm load #

You can also add a second navigation to this script, this time disabling the clearing of cache and storage that Lighthouse does by default in navigations. This next example loads an article on web.dev itself to see how much it benefits from caching:

async function captureReport() {
  const browser = await puppeteer.launch({headless: false});
  const page = await browser.newPage();

  const testUrl = 'https://web.dev/performance-scoring/';
  const flow = await startFlow(page, {name: 'Cold and warm navigations'});
  await flow.navigate(testUrl, {
    stepName: 'Cold navigation'
  });
  await flow.navigate(testUrl, {
    stepName: 'Warm navigation',
    configContext: {
      settingsOverrides: {disableStorageReset: true},
    },
  });

  await browser.close();

  const report = await flow.generateReport();
  fs.writeFileSync('flow.report.html', report);
  open('flow.report.html', {wait: false});
}

captureReport();

The resulting flow report looks something like this:

See the report live

The combination of cold and warm loads offers a fuller picture of what real users are experiencing. If you have a site where users load many pages in the same visit, this may be able to give you a more realistic look at what they're experiencing in the field.

Snapshots #

Snapshots are a new mode that runs Lighthouse audits at a single point in time. Unlike a normal Lighthouse run, the page is not reloaded. This unlocks the ability to set up a page and test it in its exact state: with a drop-down open or a form partially filled in, for example.

For this example, suppose you want to check that some new UI for Advanced Settings within Squoosh passes the automated Lighthouse checks. These settings are only visible if an image has been loaded and the options menu is expanded to show the advanced settings.

The Squoosh advanced settings menu

This process is scriptable with Puppeteer and you can actually take a Lighthouse snapshot at each step:

async function captureReport() {
  const browser = await puppeteer.launch({headless: false});
  const page = await browser.newPage();

  const flow = await startFlow(page, {name: 'Squoosh snapshots'});

  await page.goto('https://squoosh.app/', {waitUntil: 'networkidle0'});

  // Wait for first demo-image button, then open it.
  const demoImageSelector = 'ul[class*="demos"] button';
  await page.waitForSelector(demoImageSelector);
  await flow.snapshot({stepName: 'Page loaded'});
  await page.click(demoImageSelector);

  // Wait for advanced settings button in UI, then open them.
  const advancedSettingsSelector = 'form label[class*="option-reveal"]';
  await page.waitForSelector(advancedSettingsSelector);
  await flow.snapshot({stepName: 'Demo loaded'});
  await page.click(advancedSettingsSelector);

  await flow.snapshot({stepName: 'Advanced settings opened'});

  browser.close();

  const report = await flow.generateReport();
  fs.writeFileSync('flow.report.html', report);
  open('flow.report.html', {wait: false});
}

captureReport();

The resulting report shows that results are generally good, but there may be some accessibility criteria that need to be checked out manually:

See the report live

Timespans #

One of the biggest differences between performance results in the field (like from CrUX) and in the lab (like from Lighthouse) is the lack of user input. This is where a timespan—the last user flow mode—can help.

A timespan runs Lighthouse audits over some period of time, which may or may not include a navigation. This is a great way to capture what's going on with a page during interactions. For instance, by default Lighthouse measures CLS during page load, but in the field, CLS is measured from initial navigation until the page is closed. If user interactions are the trigger of CLS, this is something Lighthouse previously wouldn't be able to catch and help fix.

To demonstrate this, here is a test site that simulates ads being injected into an article during scroll without space having been reserved for them. In a long series of cards, an occasional red square is added when its slot enters the viewport. Since space was not reserved for these red squares, the cards below them are shifted out of the way, causing layout shifts.

A regular Lighthouse navigation will have a CLS of 0. However, once scrolled, the page will have problematic layout shifts and the CLS value will rise.

Try the demo site

The following script will produce a user flow report with both actions, to show the difference.

async function captureReport() {
  const browser = await puppeteer.launch({headless: false});
  const page = await browser.newPage();
  // Get a session handle to be able to send protocol commands to the page.
  const session = await page.target().createCDPSession();

  const testUrl = 'https://pie-charmed-treatment.glitch.me/';
  const flow = await startFlow(page, {name: 'CLS during navigation and on scroll'});

  // Regular Lighthouse navigation.
  await flow.navigate(testUrl, {stepName: 'Navigate only'});

  // Navigate and scroll timespan.
  await flow.startTimespan({stepName: 'Navigate and scroll'});
  await page.goto(testUrl, {waitUntil: 'networkidle0'});
  // We need the ability to scroll like a user. There's not a direct puppeteer function for this, but we can use the DevTools Protocol and issue a Input.synthesizeScrollGesture event, which has convenient parameters like repetitions and delay to somewhat simulate a more natural scrolling gesture.
  // https://chromedevtools.github.io/devtools-protocol/tot/Input/#method-synthesizeScrollGesture
  await session.send('Input.synthesizeScrollGesture', {
    x: 100,
    y: 0,
    yDistance: -2500,
    speed: 1000,
    repeatCount: 2,
    repeatDelayMs: 250,
  });
  await flow.endTimespan();

  await browser.close();

  const report = await flow.generateReport();
  fs.writeFileSync('flow.report.html', report);
  open('flow.report.html', {wait: false});
}

captureReport();

This generates a report comparing a regular navigation to a timespan which contains both a navigation and scrolling afterwards:

See the report live

Digging into each step, the navigation-only step shows a CLS of 0. Great site!

However the "Navigate and scroll" step tells a different story. Currently only Total Blocking Time and Cumulative Layout Shift are available in timespans, but the lazy-loaded content on this page clearly tanks the CLS for the site.

Formerly, Lighthouse would not be able to identify this problematic CLS behavior, though it would almost certainly show up in the experience of real users. Performance testing over scripted interactions improves lab fidelity significantly.

Looking for feedback #

The new user flow APIs in Lighthouse can do many new things, but it may still be complicated to measure the kind of scenarios your users encounter.

Please reach out with any questions in the Lighthouse discussion forums, and file any bugs or suggestions in the issue tracker.

Monitor your web page's total memory usage with `measureUserAgentSpecificMemory()`

2020-04-13T00:00:00Z

Browsers manage the memory of web pages automatically. Whenever a web page creates an object, the browser allocates a chunk of memory "under the hood" to store the object. Since memory is a finite resource, the browser performs garbage collection to detect when an object is no longer needed and to free the underlying memory chunk.

The detection is not perfect though, and it was proven that perfect detection is an impossible task. Therefore browsers approximate the notion of "an object is needed" with the notion of "an object is reachable". If the web page cannot reach an object via its variables and the fields of other reachable objects, then the browser can safely reclaim the object. The difference between these two notions leads to memory leaks as illustrated by the following example.

const object = {a: new Array(1000), b: new Array(2000)};
setInterval(() => console.log(object.a), 1000);

Here the larger array b is no longer needed, but the browser does not reclaim it because it is still reachable via object.b in the callback. Thus the memory of the larger array is leaked.

Memory leaks are prevalent on the Web. It is easy to introduce one by forgetting to unregister an event listener, by accidentally capturing objects from an iframe, by not closing a worker, by accumulating objects in arrays, and so on. If a web page has memory leaks, then its memory usage grows over time and the web page appears slow and bloated to the users.

The first step in solving this problem is measuring it. The new performance.measureUserAgentSpecificMemory() API allows developers to measure memory usage of their web pages in production and thus detect memory leaks that slip through local testing.

How is `performance.measureUserAgentSpecificMemory()` different from the legacy `performance.memory` API? #

If you are familiar with the existing non-standard performance.memory API, you might be wondering how the new API differs from it. The main difference is that the old API returns the size of the JavaScript heap whereas the new API estimates the memory used by the web page. This difference becomes important when Chrome shares the same heap with multiple web pages (or multiple instances of the same web page). In such cases, the result of the old API may be arbitrarily off. Since the old API is defined in implementation-specific terms such as "heap", standardizing it is hopeless.

Another difference is that the new API performs memory measurement during garbage collection. This reduces the noise in the results, but it may take a while until the results are produced. Note that other browsers may decide to implement the new API without relying on garbage collection.

Suggested use cases #

Memory usage of a web page depends on the timing of events, user actions, and garbage collections. That is why the memory measurement API is intended for aggregating memory usage data from production. The results of individual calls are less useful. Example use cases:

Regression detection during rollout of a new version of the web page to catch new memory leaks.
A/B testing a new feature to evaluate its memory impact and detect memory leaks.
Correlating memory usage with session duration to verify presence or absence of memory leaks.
Correlating memory usage with user metrics to understand the overall impact of memory usage.

Browser compatibility #

Browser support

Chrome 89, Supported 89
Firefox, Not supported
Edge 89, Supported 89
Safari, Not supported

Source

Currently the API is supported only in Chromium-based browsers, starting in Chrome 89. The result of the API is highly implementation dependent because browsers have different ways of representing objects in memory and different ways of estimating memory usage. Browsers may exclude some memory regions from accounting if proper accounting is too expensive or infeasible. Thus, results cannot be compared across browsers. It is only meaningful to compare the results for the same browser.

Using `performance.measureUserAgentSpecificMemory()` #

Feature detection #

The performance.measureUserAgentSpecificMemory function will be unavailable or may fail with a SecurityError if the execution environment does not fulfil the security requirements for preventing cross-origin information leaks. It relies on cross-origin isolation, which a web page can activate by setting COOP+COEP headers.

Support can be detected at runtime:

if (!window.crossOriginIsolated) {
  console.log('performance.measureUserAgentSpecificMemory() is only available in cross-origin-isolated pages');
} else if (!performance.measureUserAgentSpecificMemory) {
  console.log('performance.measureUserAgentSpecificMemory() is not available in this browser');
} else {
  let result;
  try {
    result = await performance.measureUserAgentSpecificMemory();
  } catch (error) {
    if (error instanceof DOMException && error.name === 'SecurityError') {
      console.log('The context is not secure.');
    } else {
      throw error;
    }
  }
  console.log(result);
}

Local testing #

Chrome performs the memory measurement during garbage collection, which means that the API does not resolve the result promise immediately and instead waits for the next garbage collection.

Calling the API forces a garbage collection after some timeout, which is currently set to 20 seconds, though may happen sooner. Starting Chrome with the --enable-blink-features='ForceEagerMeasureMemory' command-line flag reduces the timeout to zero and is useful for local debugging and testing.

Example #

The recommended usage of the API is to define a global memory monitor that samples memory usage of the whole web page and sends the results to a server for aggregation and analysis. The simplest way is to sample periodically, for example every M minutes. However, that introduces bias to the data because memory peaks may occur between the samples.

The following example shows how to do unbiased memory measurements using a Poisson process, which guarantees that samples are equally likely to occur at any point in time (demo, source).

First, define a function that schedules the next memory measurement using setTimeout() with a randomized interval.

function scheduleMeasurement() {
  // Check measurement API is available.
  if (!window.crossOriginIsolated) {
    console.log('performance.measureUserAgentSpecificMemory() is only available in cross-origin-isolated pages');
    console.log('See https://web.dev/coop-coep/ to learn more')
    return;
  }
  if (!performance.measureUserAgentSpecificMemory) {
    console.log('performance.measureUserAgentSpecificMemory() is not available in this browser');
    return;
  }
  const interval = measurementInterval();
  console.log(`Running next memory measurement in ${Math.round(interval / 1000)} seconds`);
  setTimeout(performMeasurement, interval);
}

The measurementInterval() function computes a random interval in milliseconds such that on average there is one measurement every five minutes. See Exponential distribution if you are interested in the math behind the function.

function measurementInterval() {
  const MEAN_INTERVAL_IN_MS = 5 * 60 * 1000;
  return -Math.log(Math.random()) * MEAN_INTERVAL_IN_MS;
}

Finally, the async performMeasurement() function invokes the API, records the result, and schedules the next measurement.

async function performMeasurement() {
  // 1. Invoke performance.measureUserAgentSpecificMemory().
  let result;
  try {
    result = await performance.measureUserAgentSpecificMemory();
  } catch (error) {
    if (error instanceof DOMException && error.name === 'SecurityError') {
      console.log('The context is not secure.');
      return;
    }
    // Rethrow other errors.
    throw error;
  }
  // 2. Record the result.
  console.log('Memory usage:', result);
  // 3. Schedule the next measurement.
  scheduleMeasurement();
}

Finally, begin measuring.

// Start measurements.
scheduleMeasurement();

The result may look as follows:

// Console output:
{
  bytes: 60_100_000,
  breakdown: [
    {
      bytes: 40_000_000,
      attribution: [{
        url: 'https://example.com/',
        scope: 'Window',
      }],
      types: ['JavaScript']
    },

    {
      bytes: 20_000_000,
      attribution: [{
          url: 'https://example.com/iframe',
          container: {
            id: 'iframe-id-attribute',
            src: '/iframe',
          },
          scope: 'Window',
      }],
      types: ['JavaScript']
    },

    {
      bytes: 100_000,
      attribution: [],
      types: ['DOM']
    },
  ],
}

The total memory usage estimate is returned in the bytes field. This value is highly implementation-dependent and cannot be compared across browsers. It may even change between different versions of the same browser. The value includes JavaScript and DOM memory of all iframes, related windows, and web workers in the current process.

The breakdown list provides further information about the used memory. Each entry describes some portion of the memory and attributes it to a set of windows, iframes, and workers identified by URL. The types field lists the implementation-specific memory types associated with the memory.

It is important to treat all lists in a generic way and to not hardcode assumptions based on a particular browser. For example, some browsers may return an empty breakdown or an empty attribution. Other browsers may return multiple entries in attribution indicating they could not distinguish which of these entries owns the memory.

Feedback #

The Web Performance Community Group and the Chrome team would love to hear about your thoughts and experiences with performance.measureUserAgentSpecificMemory().

Tell us about the API design #

Is there something about the API that doesn't work as expected? Or are there missing properties that you need to implement your idea? File a spec issue on the performance.measureUserAgentSpecificMemory() GitHub repo or add your thoughts to a existing issue.

Report a problem with the implementation #

Did you find a bug with Chrome's implementation? Or is the implementation different from the spec? File a bug at new.crbug.com. Be sure to include as much detail as you can, provide simple instructions for reproducing the bug, and have Components set to Blink>PerformanceAPIs. Glitch works great for sharing quick and easy repros.

Show support #

Are you planning to use performance.measureUserAgentSpecificMemory()? Your public support helps the Chrome team prioritize features and shows other browser vendors how critical it is to support them. Send a tweet to @ChromiumDev and let us know where and how you're using it.

Helpful links #

Acknowledgements #

Big thanks to Domenic Denicola, Yoav Weiss, Mathias Bynens for API design reviews, and Dominik Inführ, Hannes Payer, Kentaro Hara, Michael Lippautz for code reviews in Chrome. I also thank Per Parker, Philipp Weis, Olga Belomestnykh, Matthew Bolohan, and Neil Mckay for providing valuable user feedback that greatly improved the API.

Hero image by Harrison Broadbent on Unsplash

Brendan Kenny on web.dev

Using the Web Vitals extension to debug Core Web Vitals issues

Showing debug information in the console #

New debug information for each metric #

LCP debug information #

CLS debug information #

FID debug information #

INP debug information #

INP metric #

Interactions #

Filtering the console logs #

Conclusion #

Acknowledgements #

Our top Core Web Vitals recommendations for 2023

Largest Contentful Paint (LCP) #

Ensure the LCP resource is discoverable from the HTML source #

Ensure the LCP resource is prioritized #

Use a CDN to optimize document and resource TTFB #

Cumulative Layout Shift (CLS) #

Set explicit sizes on any content loaded from the page #

Ensure pages are eligible for bfcache #

Avoid animations/transitions that use layout-inducing CSS properties #

First Input Delay (FID) #

Avoid or break up long tasks #

Avoid unnecessary JavaScript #

Avoid large rendering updates #

Conclusion #

Lighthouse user flows

Setup #

Navigations #

Capturing a warm load #

Snapshots #

Timespans #

Looking for feedback #

Monitor your web page's total memory usage with `measureUserAgentSpecificMemory()`

How is performance.measureUserAgentSpecificMemory() different from the legacy performance.memory API? #

Suggested use cases #

Browser compatibility #

Using performance.measureUserAgentSpecificMemory() #

Feature detection #

Local testing #

Example #

Feedback #

Tell us about the API design #

Report a problem with the implementation #

Show support #

Helpful links #

Acknowledgements #

How is `performance.measureUserAgentSpecificMemory()` different from the legacy `performance.memory` API? #

Using `performance.measureUserAgentSpecificMemory()` #