Editorial review: Document PerformanceNavigationTiming.confidence by chrisdavidmills · Pull Request #43528 · mdn/content

chrisdavidmills · 2026-03-23T09:56:02Z

Description

Chrome 145 adds support for the PerformanceNavigationTiming.confidence property, and the associated PerformanceTimingConfidence interface. See https://chromestatus.com/feature/5186950448283648.

This PR adds documentation for both features mentioned above.

Motivation

Additional details

Related issues and pull requests

github-actions · 2026-03-23T09:57:44Z

Preview URLs (7 pages)

(comment last updated: 2026-03-27 16:40:45)

hamishwillee · 2026-03-23T22:36:23Z

@chrisdavidmills This says "technical review". Is it ready for me to look at?

chrisdavidmills · 2026-03-24T08:22:22Z

@chrisdavidmills This says "technical review". Is it ready for me to look at?

@hamishwillee. Not yet; I requested a tech review from the browser engineers yesterday. Once it is ready, I'll flip it to "Editorial review".

mmocny

The docs look great, thanks for doing it!

I'm not the primary engineering contact for this, so hopefully Mike Jackson at Msft will have a change to take a look.

One detail that is missing from the docs: how should you use this value and interpret the data on the server? This feels like the most important part of the API, and also the harder to understand for developers.

Mike has done some presentations on this, and I see that he added a NOTE to the very bottom of this spection of the spec: https://www.w3.org/TR/navigation-timing-2/#sec-PerformanceNavigationTiming

This section is intended to help RUM providers and developers interpret confidence

...that section might be worth including in docs here?

Cheers.

mmocny · 2026-03-26T20:14:12Z

files/en-us/web/api/performancenavigationtiming/confidence/index.md

+
+{{APIRef("Performance API")}}{{SeeCompatTable}}
+
+The **`confidence`** read-only property of the {{domxref("PerformanceNavigationTiming")}} interface returns a {{domxref("PerformanceTimingConfidence")}} object containing information that indicates whether the user agent considers returned navigation metrics to be representative of the current user's device.


"representative of the current user's device"

I see that this wording comes from the navigation timing spec itself. Personally, I don't like that phrasing.

It's more like "known to have adverse conditions affecting performance" or something.

I think its fine to leave to match spec, but maybe Mike Jackson wants to take the chance to wordsmith?

Maybe something like: returned navigation metrics free from external system load unrelated to the page.

I like @mwjacksonmsft's wording; I'll update the wording to that in the places where it appears.

mmocny · 2026-03-26T20:15:17Z

files/en-us/web/api/performancenavigationtiming/confidence/index.md

+
+The **`confidence`** read-only property of the {{domxref("PerformanceNavigationTiming")}} interface returns a {{domxref("PerformanceTimingConfidence")}} object containing information that indicates whether the user agent considers returned navigation metrics to be representative of the current user's device.
+
+For example, if the browser has launched from a "cold start" before loading a website or has resource-intensive extensions running, or if other applications running on the user's device are taking up a lot of resource cycles, web pages may load more slowly as a result. In such cases, a `low` confidence {{domxref("PerformanceTimingConfidence.value", "value")}} would be returned.


Some of these are aspirational right now.

Should we make it clearer what is actually (I think cold startup?) vs might one day be affecting?

Mike is the expert.

At the moment, this works for cold start, and session restore. I'd prefer that we only highlight those items (or call out that the others are potential future cases and not currently implemented).

I've updated the wording on both pages it appears on to:

For example, if a website has loaded after a browser "cold start" or session restore, its pages may load more slowly as a result.

mwjacksonmsft · 2026-03-27T06:30:39Z

files/en-us/web/api/performancenavigationtiming/index.md

 - {{domxref('PerformanceNavigationTiming.activationStart')}} {{ReadOnlyInline}} {{experimental_inline}}
  - : A {{domxref("DOMHighResTimeStamp")}} representing the time between when a document starts prerendering and when it is activated.
+- {{domxref('PerformanceNavigationTiming.confidence')}} {{ReadOnlyInline}} {{experimental_inline}}
+  - : A {{domxref("PerformanceTimingConfidence")}} object containing information that indicates whether the user agent considers returned navigation metrics to be representative of the current user's device.


Should we adjust the language here as well to match confidence/index.md?

Good call; done.

mwjacksonmsft · 2026-03-27T06:31:40Z

files/en-us/web/api/performancetimingconfidence/value/index.md

+
+{{APIRef("Performance API")}}{{SeeCompatTable}}
+
+The **`value`** read-only property of the {{domxref("PerformanceTimingConfidence")}} interface is an enumerated value indicating a broad confidence measure of whether the user agent considers returned navigation metrics to be representative of the current user's device.


Same question here - should we update this to match the verbiage in confidence/index.md

chrisdavidmills · 2026-03-27T16:16:04Z

Mike has done some presentations on this, and I see that he added a NOTE to the very bottom of this section of the spec: https://www.w3.org/TR/navigation-timing-2/#sec-PerformanceNavigationTiming

This section is intended to help RUM providers and developers interpret confidence

...that section might be worth including in docs here?

This makes sense. For the moment, I've gone for including all the text in this section in the PerformanceTimingConfidence page, under a heading of "Interpreting confidence data". I've not made many changes, except for a few tweaks, and adding links to the different values.

Anyway, I'll include that in my next commit.

mwjacksonmsft

These changes LGTM. Thanks!

chrisdavidmills · 2026-03-27T17:21:38Z

Cool, thanks, @mwjacksonmsft. I'll move this to the editorial review stage.

@hamishwillee, ready for you to have a look, if you've still got time early next week.

hamishwillee · 2026-03-30T00:10:39Z

files/en-us/web/api/performancetimingconfidence/index.md

+For example, if a website has loaded after a browser "cold start" or session restore, its pages may load more slowly as a result. In such cases, a `low` confidence {{domxref("PerformanceTimingConfidence.value", "value")}} would be returned for an associated performance record. On the other hand, if the browser determines a returned performance record to be representative of typical application performance, a `high` confidence value is returned.
+
+This confidence measure is useful for developers when trying to determine whether a performance issue is a legitimate concern, or an outlier being caused by external factors.


If you have a lot to say, interface pages tend to push the discussion down to a description.
I would push this and the "Interpreting confidence data".

hamishwillee · 2026-03-30T00:11:24Z

files/en-us/web/api/performancetimingconfidence/index.md

+
+To compute debiased percentiles for both `high` and `low`:
+
+1. Follow the _computing debiased means_ steps to compute a per-record weight `w`.


This is unambiguous in the spec because " computing debiased means" would be a link.

hamishwillee · 2026-03-30T00:18:38Z

files/en-us/web/api/performancetimingconfidence/index.md

+
+## Interpreting confidence data
+
+Since the {{domxref("PerformanceTimingConfidence.randomizedTriggerRate", "randomizedTriggerRate")}} can vary across records, per-record weighting is needed to recover unbiased aggregates. The procedure below illustrates how weighting based on {{domxref("PerformanceTimingConfidence.value", "value")}} can be applied before computing summary statistics.


There is always an argument around what you should expect a developer to reasonably interpret and how much hand holding you should do. To my mind though, basic questions like "why do I need to do this have not been answered".

Let's start backwards. Why are summary statistics needed and how do I use those?
What is an unbiased aggregate? Why do I care to recover one? Blah blah.

To put it another way, I can see myself following these instructions and generating the data, but then not knowing what to do with it.

hamishwillee · 2026-03-30T00:31:13Z

files/en-us/web/api/performancenavigationtiming/confidence/index.md

+
+{{APIRef("Performance API")}}{{SeeCompatTable}}
+
+The **`confidence`** read-only property of the {{domxref("PerformanceNavigationTiming")}} interface returns a {{domxref("PerformanceTimingConfidence")}} object containing information that indicates whether the user agent considers returned navigation metrics to be free from external system load unrelated to the page.


IMO it's not so much "free from" as "likely to be affected by". Something like

Suggested change

The **`confidence`** read-only property of the {{domxref("PerformanceNavigationTiming")}} interface returns a {{domxref("PerformanceTimingConfidence")}} object containing information that indicates whether the user agent considers returned navigation metrics to be free from external system load unrelated to the page.

The **`confidence`** read-only property of the {{domxref("PerformanceNavigationTiming")}} interface returns a {{domxref("PerformanceTimingConfidence")}} object containing information that indicates whether the user agent considers returned navigation metrics to be affected by external system load (unrelated to the page).

YOu could also steal your own words from further down "considers a performance record to reflect typical application performance, or possibly be affected by external factors."

It's a mouthful anyway, and it might be reasonable to assume that it is the user-agent's assumptions. If we can make that assumption maybe

Suggested change

The **`confidence`** read-only property of the {{domxref("PerformanceNavigationTiming")}} interface returns a {{domxref("PerformanceTimingConfidence")}} object containing information that indicates whether the user agent considers returned navigation metrics to be free from external system load unrelated to the page.

The **`confidence`** read-only property of the {{domxref("PerformanceNavigationTiming")}} interface returns a {{domxref("PerformanceTimingConfidence")}} object containing information that indicates the likelihood that navigation metrics have been been affected by factors unrelated to the page, such as external system load.

hamishwillee · 2026-03-30T00:39:32Z

files/en-us/web/api/performancenavigationtiming/index.md

 - {{domxref('PerformanceNavigationTiming.activationStart')}} {{ReadOnlyInline}} {{experimental_inline}}
  - : A {{domxref("DOMHighResTimeStamp")}} representing the time between when a document starts prerendering and when it is activated.
+- {{domxref('PerformanceNavigationTiming.confidence')}} {{ReadOnlyInline}} {{experimental_inline}}
+  - : A {{domxref("PerformanceTimingConfidence")}} object containing information that indicates whether the user agent considers returned navigation metrics to be free from external system load unrelated to the page.


As above, not so sure of "Free from".

hamishwillee · 2026-03-30T00:42:46Z

files/en-us/web/api/performancetimingconfidence/randomizedtriggerrate/index.md

+
+{{APIRef("Performance API")}}{{SeeCompatTable}}
+
+The **`randomizedTriggerRate`** read-only property of the {{domxref("PerformanceTimingConfidence")}} interface is a number representing a percentage value that indicates how often noise is applied when exposing the {{domxref("PerformanceTimingConfidence.value")}}.


This is very complete and accurate, but it is hard to parse. Possibly it is not necessary to capture this all in one sentence here, since you should to that in the value.

Suggested change

The **`randomizedTriggerRate`** read-only property of the {{domxref("PerformanceTimingConfidence")}} interface is a number representing a percentage value that indicates how often noise is applied when exposing the {{domxref("PerformanceTimingConfidence.value")}}.

The **`randomizedTriggerRate`** read-only property of the {{domxref("PerformanceTimingConfidence")}} indicates how often noise is applied when exposing the {{domxref("PerformanceTimingConfidence.value")}}.

Either way

why do we add noise? We should say, and also state what a high rate actually means vs a low rate.

So 100% (1) would mean every PerformanceTimingConfidence has noise applied to the value.

If noise is applied does that flip the value.

Just trying to get a feel for what a developer might do or not do with this knowledge.

hamishwillee · 2026-03-30T00:48:39Z

files/en-us/web/api/performancetimingconfidence/randomizedtriggerrate/index.md

+
+## Value
+
+A number inside the interval `0` to `1` inclusive.


How you do this depends on whether you do anything like the suggestion in https://github.com/mdn/content/pull/43528/changes#r3007055024

But, I would use wording like this if you don't change anything above.

Suggested change

A number inside the interval `0` to `1` inclusive.

A number between `0` and `1`, inclusive.

hamishwillee · 2026-03-30T00:50:20Z

files/en-us/web/api/performancetimingconfidence/value/index.md

+
+{{APIRef("Performance API")}}{{SeeCompatTable}}
+
+The **`value`** read-only property of the {{domxref("PerformanceTimingConfidence")}} interface is an enumerated value indicating a broad confidence measure of whether the user agent considers returned navigation metrics to be free from external system load unrelated to the page.


A above...

Suggested change

The **`value`** read-only property of the {{domxref("PerformanceTimingConfidence")}} interface is an enumerated value indicating a broad confidence measure of whether the user agent considers returned navigation metrics to be free from external system load unrelated to the page.

The **`value`** read-only property of the {{domxref("PerformanceTimingConfidence")}} interface is an enumerated value indicating a broad confidence measure of whether the user agent considers returned navigation metrics to be affected by external system load unrelated to the page.

hamishwillee · 2026-03-30T00:53:22Z

files/en-us/web/api/performancetimingconfidence/index.md

+- {{domxref("PerformanceTimingConfidence.randomizedTriggerRate")}} {{ReadOnlyInline}}
+  - : A number representing a percentage value that indicates how often noise is applied when exposing the `value`.
+- {{domxref("PerformanceTimingConfidence.value")}} {{ReadOnlyInline}}
+  - : An enumerated value indicating a broad confidence measure of whether the user agent considers returned navigation metrics to be representative of the current user's device.


This isn't right. The spec explicitly states that the confidence must not consider specifics fo the user device. YOu might mean "of the application".

Note, I do think you should clearly state that what contributes to the assessement, and make it clear that CPU etc do not count.

hamishwillee

Looks pretty good. I have questions.

It might be nice to mention this in https://developer.mozilla.org/en-US/docs/Web/API/Performance_API/Navigation_timing

Document PerformanceNavigationTiming.confidence

2fbad3b

chrisdavidmills requested a review from a team as a code owner March 23, 2026 09:56

chrisdavidmills requested review from hamishwillee and removed request for a team March 23, 2026 09:56

github-actions bot added Content:WebAPI Web API docs size/m [PR only] 51-500 LoC changed labels Mar 23, 2026

chrisdavidmills changed the title ~~Document PerformanceNavigationTiming.confidence~~ Technical review: Document PerformanceNavigationTiming.confidence Mar 23, 2026

mmocny reviewed Mar 26, 2026

View reviewed changes

mwjacksonmsft reviewed Mar 27, 2026

View reviewed changes

Merge branch 'main' into performancenavigationtiming-confidence

cef856f

Fixes for technical review comments

2930c97

chrisdavidmills requested review from mmocny and mwjacksonmsft March 27, 2026 16:39

mwjacksonmsft reviewed Mar 27, 2026

View reviewed changes

chrisdavidmills changed the title ~~Technical review: Document PerformanceNavigationTiming.confidence~~ Editorial review: Document PerformanceNavigationTiming.confidence Mar 27, 2026

hamishwillee reviewed Mar 30, 2026

View reviewed changes


		{{APIRef("Performance API")}}{{SeeCompatTable}}

		The `confidence` read-only property of the {{domxref("PerformanceNavigationTiming")}} interface returns a {{domxref("PerformanceTimingConfidence")}} object containing information that indicates whether the user agent considers returned navigation metrics to be representative of the current user's device.


		The `confidence` read-only property of the {{domxref("PerformanceNavigationTiming")}} interface returns a {{domxref("PerformanceTimingConfidence")}} object containing information that indicates whether the user agent considers returned navigation metrics to be representative of the current user's device.

		For example, if the browser has launched from a "cold start" before loading a website or has resource-intensive extensions running, or if other applications running on the user's device are taking up a lot of resource cycles, web pages may load more slowly as a result. In such cases, a `low` confidence {{domxref("PerformanceTimingConfidence.value", "value")}} would be returned.


		{{APIRef("Performance API")}}{{SeeCompatTable}}

		The `value` read-only property of the {{domxref("PerformanceTimingConfidence")}} interface is an enumerated value indicating a broad confidence measure of whether the user agent considers returned navigation metrics to be representative of the current user's device.

		For example, if a website has loaded after a browser "cold start" or session restore, its pages may load more slowly as a result. In such cases, a `low` confidence {{domxref("PerformanceTimingConfidence.value", "value")}} would be returned for an associated performance record. On the other hand, if the browser determines a returned performance record to be representative of typical application performance, a `high` confidence value is returned.

		This confidence measure is useful for developers when trying to determine whether a performance issue is a legitimate concern, or an outlier being caused by external factors.


		To compute debiased percentiles for both `high` and `low`:

		1. Follow the _computing debiased means_ steps to compute a per-record weight `w`.


		## Interpreting confidence data

		Since the {{domxref("PerformanceTimingConfidence.randomizedTriggerRate", "randomizedTriggerRate")}} can vary across records, per-record weighting is needed to recover unbiased aggregates. The procedure below illustrates how weighting based on {{domxref("PerformanceTimingConfidence.value", "value")}} can be applied before computing summary statistics.


		{{APIRef("Performance API")}}{{SeeCompatTable}}

		The `randomizedTriggerRate` read-only property of the {{domxref("PerformanceTimingConfidence")}} interface is a number representing a percentage value that indicates how often noise is applied when exposing the {{domxref("PerformanceTimingConfidence.value")}}.

	A number inside the interval `0` to `1` inclusive.
	A number between `0` and `1`, inclusive.

Conversation

chrisdavidmills commented Mar 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Motivation

Additional details

Related issues and pull requests

Uh oh!

github-actions bot commented Mar 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

hamishwillee commented Mar 23, 2026

Uh oh!

chrisdavidmills commented Mar 24, 2026

Uh oh!

mmocny left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

chrisdavidmills Mar 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

chrisdavidmills commented Mar 27, 2026

Uh oh!

mwjacksonmsft left a comment

Choose a reason for hiding this comment

Uh oh!

chrisdavidmills commented Mar 27, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

hamishwillee Mar 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

hamishwillee Mar 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

hamishwillee Mar 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

hamishwillee Mar 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

hamishwillee Mar 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

hamishwillee left a comment

chrisdavidmills commented Mar 23, 2026 •

edited

Loading

github-actions bot commented Mar 23, 2026 •

edited

Loading

chrisdavidmills Mar 27, 2026 •

edited

Loading

hamishwillee Mar 30, 2026 •

edited

Loading

hamishwillee Mar 30, 2026 •

edited

Loading

hamishwillee Mar 30, 2026 •

edited

Loading

hamishwillee Mar 30, 2026 •

edited

Loading

hamishwillee Mar 30, 2026 •

edited

Loading