Debug background services

Kayce Basques

Sofia Emelianova

The Background services section of Chrome DevTools is a collection of tools for the JavaScript APIs that enables your website to send and receive updates even when a user does not have your website open. A background service is functionally similar to a background process.

The Background services section lets you debug the following background services:

• Background fetch
• Background sync
• Notifications
• Speculative loads
• Push messages

Chrome DevTools can log fetch, sync, and notification events for three days, even when DevTools is not open. This can help you make sure that events are being sent and received as expected.

In addition to background service events, DevTools can:

• Show you reports that Chrome already sent or is about to send using the Reporting API.
• Let you debug and test back/forward cache with a click.

Background fetch

The Background Fetch API enables a service worker to reliably download large resources, like movies or podcasts, as a background service. To log background fetch events for three days, even when DevTools isn't open:

1. Open DevTools, for example, on this demo page.

2. Navigate to Application > Background services > Background fetch, and click Record.

   

3. On the demo page, click Store assets locally. This triggers some background fetch activity. DevTools logs the events to the table.

   

4. Click an event to view its details in the space below the table.

5. You can close DevTools and leave the recording run for up to three days. To stop recording, click Stop.

Background sync

The Background Sync API enables an offline service worker to send data to a server once it has re-established a reliable internet connection. To log background sync events for three days, even when DevTools isn't open:

1. Open DevTools, for example, on this demo page.

2. Navigate to Application > Background services > Background sync and click Record.

   

3. On the demo page, click Register background sync to register the respective service worker and click Allow when prompted.

   Note: To learn how to debug service workers in DevTools, see Service workers.

   Service worker registration is a background sync activity. DevTools logs the events to the table.

   

4. Click an event to view its details in the space below the table.

5. You can close DevTools and leave the recording run for up to three days. To stop recording, click Stop.

(Experimental) Bounce tracking mitigations

Note: This is an experimental feature available from Chrome version 115.

Bounce tracking mitigations experiment in Chrome lets you identify and delete the state of sites that appear to perform cross-site tracking using the bounce tracking technique. You can manually force tracking mitigations and see a list of sites whose states were deleted.

To force tracking mitigations:

1. Block third-party cookies in Chrome. Navigate to and enable > Settings > Privacy and security > Cookies and other site data > Block third-party cookies.
2. In chrome://flags, set the Bounce tracking mitigations experiment to Enabled With Deletion.
3. Open DevTools, for example, on demo page, and navigate to Application > Background services > Bounce tracking mitigations.
4. On the demo page, click a bounce link and wait (10 seconds) for Chrome to record the bounce. The Issues tab warns you about the upcoming state deletion.
5. Click Force run to delete the state immediately.

Notifications

After a service worker has received a Push Message from a server, the service worker uses the Notifications API to display the data to a user. To log Notifications for three days, even when DevTools isn't open:

1. Open DevTools, for example, on this demo page.

2. Navigate to Application > Background services > Notifications and click Record.

   

3. On the demo page, click Schedule Notification and Allow when prompted.

4. Wait for the notification to appear. DevTools logs the notification events to the table.

   

5. Click an event to view its details in the space below the table.

6. You can close DevTools and leave the recording run for up to three days. To stop recording, click Stop.

Speculative loads

Speculative loads allow a near-instant page load based on speculation rules that you define. This lets your website prefetch and prerender most navigated-to pages.

Prefetch fetches a resource in advance and prerender goes a step beyond and renders the whole page in a hidden background renderer process.

You can debug speculative loads in the Application > Background services > Speculative loads section. The section contains three views:

• Speculative loads. Contains the speculative status for the current page, current URL, pages that the current page attempts to load speculatively, and their statuses.
• Rules. Contains the rule sets on the current page in the Elements panel and the overall status of speculations.
• Speculations. Contains a table with information on speculative loading attempts and their statuses. If an attempt failed, you can click it in the table to see detailed information and failure reason.

Try debugging speculative loads on this demo page:

1. Open DevTools on the page and navigate to Application > Background services > Speculative loads. If you can't see any speculative loads initiated by the page, reload it.

   

2. The starting page of the demo prerenders two pages and fails to prerender one. Click View all speculations.

3. In Speculations, select the speculation with the Failure status to see the Failure reason the section with detailed information at the bottom.

   

   In this case, the prerender failed because there's no /next3.html page on the website.

4. Open the Rules section and click the Status to see the rule set at the bottom. Clicking on the Rule set link takes you to the Elements panel and shows you where the speculation rule is defined.

   

   Tip: You can't fix the rule on this screen or in the Elements panel because DevTools doesn't persist arbitrary DOM changes across page loads. You have to fix the rule at the source by setting up a workspace or mock the change by overriding the content.

For a more detailed walkthrough, see Debugging speculation rules.

Push messaging

To display a push notification to a user, a service worker must first use the Push Message API to receive data from a server. When the service worker is ready to display the notification, it uses the Notifications API. To log push messages for three days, even when DevTools isn't open:

1. Open DevTools, for example, on this demo page.

2. Navigate to Application > Background services > Push Messaging and click Record.

   

3. On the demo page, toggle Enable push notifications, click Allow when prompted, type a message, and send it. DevTools logs push notification events to the table.

   

   Note: Additionally, in Application > Service Workers, you can click Push to send test notifications from DevTools.

4. Click an event to view its details in the space below the table.

5. You can close DevTools and leave the recording run for up to three days. To stop recording, click Stop.

Reporting API

Some errors happen only in production. You never see them locally or during development because real users, networks, and devices change the game.

For example, say your new site relies on third-party software that uses document.write() to load critical scripts. New users all over the world open your site but they might have slower connections than you tested with. Unknown to you, your site starts breaking for them because Chrome intervenes against document.write() on slow networks. Alternatively, you might want to keep an eye on deprecated or soon-to-be-deprecated APIs your codebase may be using.

The Reporting API is designed to help you monitor deprecated API calls, security violations of your page, and more. You can set up reporting as described in Monitor your web application with the Reporting API.

To view the reports generated by a page:

1. Go to chrome://flags/#enable-experimental-web-platform-features, set Experimental Web Platform features to Enabled, and restart Chrome.

2. Open DevTools and navigate to Application > Background services > Reporting API. For example, you can check out reports on this demo page.

   

The Reporting API tab is divided into three parts:

• The Reports table with the following information on each report:
  • URL that caused the report generation
  • Violation Type
  • Report Status
  • Destination endpoint
  • Generated at timestamp
  • Report Body
• The Report body preview section. To preview a report body, click a report in the table of reports.
• The Endpoints section with an overview of all the endpoints configured in the Reporting-Endpoints header.

Report status

The Status column tells you whether Chrome sent the report successfully, is about to send it, or failed.

Status	Description
Success	The browser has sent the report and the endpoint replied with a success code (200 or another success response code 2xx).
Pending	The browser is making an attempt to send the report.
Queued	The report has been generated and the browser is not trying to send it yet. A report appears as Queued in one of these two cases: The report is new and the browser is waiting to see if more reports arrive before trying to send it. The report is not new; the browser has already tried to send this report and has failed, and is waiting before trying again.
MarkedForRemoval	After retrying for a while (Queued), the browser has stopped trying to send the report and will soon remove it from its list of reports to send.

Reports are removed after a while, whether or not they're successfully sent.

Key point: The Queued status isn't always informative, because it doesn't precisely indicate whether sending has failed or has not been attempted yet. Using short reporting delays helps: a report that remains Queued in that case likely indicates that sending is failing.