From 56042f387607a172298caad9de2b4a6d4713aa4d Mon Sep 17 00:00:00 2001 From: Chris Mills Date: Mon, 23 Mar 2026 09:35:19 +0000 Subject: [PATCH 1/5] Document PerformanceNavigationTiming.confidence --- .../confidence/index.md | 52 +++++++++++++++ .../api/performancenavigationtiming/index.md | 2 + .../tojson/index.md | 6 +- .../api/performancetimingconfidence/index.md | 59 +++++++++++++++++ .../randomizedtriggerrate/index.md | 33 ++++++++++ .../tojson/index.md | 65 +++++++++++++++++++ .../value/index.md | 33 ++++++++++ 7 files changed, 249 insertions(+), 1 deletion(-) create mode 100644 files/en-us/web/api/performancenavigationtiming/confidence/index.md create mode 100644 files/en-us/web/api/performancetimingconfidence/index.md create mode 100644 files/en-us/web/api/performancetimingconfidence/randomizedtriggerrate/index.md create mode 100644 files/en-us/web/api/performancetimingconfidence/tojson/index.md create mode 100644 files/en-us/web/api/performancetimingconfidence/value/index.md diff --git a/files/en-us/web/api/performancenavigationtiming/confidence/index.md b/files/en-us/web/api/performancenavigationtiming/confidence/index.md new file mode 100644 index 000000000000000..446f10430445a34 --- /dev/null +++ b/files/en-us/web/api/performancenavigationtiming/confidence/index.md @@ -0,0 +1,52 @@ +--- +title: "PerformanceNavigationTiming: confidence property" +short-title: confidence +slug: Web/API/PerformanceNavigationTiming/confidence +page-type: web-api-instance-property +status: + - experimental +browser-compat: api.PerformanceNavigationTiming.confidence +--- + +{{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. + +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. + +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. + +## Value + +A {{domxref("PerformanceTimingConfidence")}} object. + +## Examples + +### Basic usage + +This example uses a {{domxref("PerformanceObserver")}} to retrieve confidence data from observed {{domxref("PerformanceNavigationTiming")}} entries. The {{domxref("PerformanceTimingConfidence.value", "value")}} property is an enumerated value of `low` or `high`, indicating a broad confidence measure, whereas the {{domxref("PerformanceTimingConfidence.randomizedTriggerRate", "randomizedTriggerRate")}} property is a number inside the interval `0` to `1` inclusive, representing a percentage value that indicates how often noise is applied when exposing the `value`. + +```js +const observer = new PerformanceObserver((list) => { + list.getEntries().forEach((entry) => { + console.log( + `${entry.name} confidence: ${entry.confidence.value}`, + `Trigger rate: ${entry.confidence.randomizedTriggerRate}`, + ); + }); +}); + +observer.observe({ type: "navigation", buffered: true }); +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- {{domxref("PerformanceTimingConfidence")}} diff --git a/files/en-us/web/api/performancenavigationtiming/index.md b/files/en-us/web/api/performancenavigationtiming/index.md index 1cc97a6b8e268ff..3d8bd252d528af3 100644 --- a/files/en-us/web/api/performancenavigationtiming/index.md +++ b/files/en-us/web/api/performancenavigationtiming/index.md @@ -40,6 +40,8 @@ The interface also supports the following properties: - {{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. - {{domxref('PerformanceNavigationTiming.criticalCHRestart')}} {{ReadOnlyInline}} {{experimental_inline}} - : A {{domxref("DOMHighResTimeStamp")}} representing the time at which the connection restart occurred due to {{HTTPHeader("Critical-CH")}} HTTP response header mismatch. - {{domxref('PerformanceNavigationTiming.domComplete')}} {{ReadOnlyInline}} diff --git a/files/en-us/web/api/performancenavigationtiming/tojson/index.md b/files/en-us/web/api/performancenavigationtiming/tojson/index.md index 107dfd0898a3d73..2d54b3cc0abf397 100644 --- a/files/en-us/web/api/performancenavigationtiming/tojson/index.md +++ b/files/en-us/web/api/performancenavigationtiming/tojson/index.md @@ -88,7 +88,11 @@ This would log a JSON object like so: "loadEventEnd": 227.60000002384186, "type": "navigate", "redirectCount": 1, - "activationStart": 0 + "activationStart": 0, + "confidence": { + "randomizedTriggerRate": 0.4994798, + "value": "high" + } } ``` diff --git a/files/en-us/web/api/performancetimingconfidence/index.md b/files/en-us/web/api/performancetimingconfidence/index.md new file mode 100644 index 000000000000000..10009b7450035ea --- /dev/null +++ b/files/en-us/web/api/performancetimingconfidence/index.md @@ -0,0 +1,59 @@ +--- +title: PerformanceTimingConfidence +slug: Web/API/PerformanceTimingConfidence +page-type: web-api-interface +browser-compat: api.PerformanceTimingConfidence +--- + +{{APIRef("Performance API")}} + +The **`PerformanceTimingConfidence`** interface provides access to 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. + +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. + +The `PerformanceTimingConfidence` object for each navigation timing entry is accessed via the {{domxref("PerformanceNavigationTiming")}} interface's `confidence` property. + +## Instance properties + +- {{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. + +## Instance methods + +- {{domxref("PerformanceTimingConfidence.toJSON()")}} + - : Returns a JSON representation of the `PerformanceTimingConfidence` object. + +## Examples + +### Basic usage + +This example uses a {{domxref("PerformanceObserver")}} to retrieve confidence data from observed {{domxref("PerformanceNavigationTiming")}} entries. + +```js +const observer = new PerformanceObserver((list) => { + list.getEntries().forEach((entry) => { + console.log( + `${entry.name} confidence: ${entry.confidence.value}`, + `Trigger rate: ${entry.confidence.randomizedTriggerRate}`, + ); + }); +}); + +observer.observe({ type: "navigation", buffered: true }); +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- {{domxref("PerformanceNavigationTiming")}} diff --git a/files/en-us/web/api/performancetimingconfidence/randomizedtriggerrate/index.md b/files/en-us/web/api/performancetimingconfidence/randomizedtriggerrate/index.md new file mode 100644 index 000000000000000..8fab5e57b442e68 --- /dev/null +++ b/files/en-us/web/api/performancetimingconfidence/randomizedtriggerrate/index.md @@ -0,0 +1,33 @@ +--- +title: "PerformanceTimingConfidence: randomizedTriggerRate property" +short-title: randomizedTriggerRate +slug: Web/API/PerformanceTimingConfidence/randomizedTriggerRate +page-type: web-api-instance-property +status: + - experimental +browser-compat: api.PerformanceTimingConfidence.randomizedTriggerRate +--- + +{{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")}}. + +## Value + +A number inside the interval `0` to `1` inclusive. + +## Examples + +See the main {{domxref("PerformanceTimingConfidence")}} page for an example. + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- {{domxref("PerformanceTimingConfidence")}} diff --git a/files/en-us/web/api/performancetimingconfidence/tojson/index.md b/files/en-us/web/api/performancetimingconfidence/tojson/index.md new file mode 100644 index 000000000000000..7a437c306f78ae4 --- /dev/null +++ b/files/en-us/web/api/performancetimingconfidence/tojson/index.md @@ -0,0 +1,65 @@ +--- +title: "PerformanceTimingConfidence: toJSON() method" +short-title: toJSON() +slug: Web/API/PerformanceTimingConfidence/toJSON +page-type: web-api-instance-method +browser-compat: api.PerformanceTimingConfidence.toJSON +--- + +{{APIRef("Performance API")}} + +The **`toJSON()`** method of the {{domxref("PerformanceTimingConfidence")}} interface is a {{Glossary("Serialization","serializer")}} that returns a JSON representation of the {{domxref("PerformanceTimingConfidence")}} object. + +## Syntax + +```js-nolint +toJSON() +``` + +### Parameters + +None. + +### Return value + +A {{jsxref("JSON")}} object that is the serialization of the {{domxref("PerformanceTimingConfidence")}} object. + +## Examples + +### Using the toJSON method + +This example uses a {{domxref("PerformanceObserver")}} to retrieve a JSON serialization of the confidence data for observed {{domxref("PerformanceNavigationTiming")}} entries. + +```js +const observer = new PerformanceObserver((list) => { + list.getEntries().forEach((entry) => { + console.log(entry.confidence.toJSON()); + }); +}); + +observer.observe({ type: "navigation", buffered: true }); +``` + +This would log a JSON object like so: + +```json +{ + "randomizedTriggerRate": 0.4994798, + "value": "high" +} +``` + +To get a JSON string, you can use [`JSON.stringify(entry)`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify) directly; it will call `toJSON()` automatically. + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- {{domxref("PerformanceTimingConfidence")}} +- {{jsxref("JSON")}} diff --git a/files/en-us/web/api/performancetimingconfidence/value/index.md b/files/en-us/web/api/performancetimingconfidence/value/index.md new file mode 100644 index 000000000000000..9133d83e588df33 --- /dev/null +++ b/files/en-us/web/api/performancetimingconfidence/value/index.md @@ -0,0 +1,33 @@ +--- +title: "PerformanceTimingConfidence: value property" +short-title: value +slug: Web/API/PerformanceTimingConfidence/value +page-type: web-api-instance-property +status: + - experimental +browser-compat: api.PerformanceTimingConfidence.value +--- + +{{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. + +## Value + +An enumerated value of `low` or `high`, indicating low or high confidence, respectively. + +## Examples + +See the main {{domxref("PerformanceTimingConfidence")}} page for an example. + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- {{domxref("PerformanceTimingConfidence")}} From 8348ef2a3f882f8c40f4b0ed04ba156ccff4518b Mon Sep 17 00:00:00 2001 From: Chris Mills Date: Fri, 27 Mar 2026 16:38:57 +0000 Subject: [PATCH 2/5] Fixes for technical review comments --- .../confidence/index.md | 4 +- .../api/performancenavigationtiming/index.md | 2 +- .../api/performancetimingconfidence/index.md | 48 +++++++++++++++++-- .../value/index.md | 2 +- 4 files changed, 49 insertions(+), 7 deletions(-) diff --git a/files/en-us/web/api/performancenavigationtiming/confidence/index.md b/files/en-us/web/api/performancenavigationtiming/confidence/index.md index 446f10430445a34..ecce405e955e648 100644 --- a/files/en-us/web/api/performancenavigationtiming/confidence/index.md +++ b/files/en-us/web/api/performancenavigationtiming/confidence/index.md @@ -10,9 +10,9 @@ browser-compat: api.PerformanceNavigationTiming.confidence {{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 free from external system load unrelated to the page. -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. +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. diff --git a/files/en-us/web/api/performancenavigationtiming/index.md b/files/en-us/web/api/performancenavigationtiming/index.md index 3d8bd252d528af3..3d6d3d15413793a 100644 --- a/files/en-us/web/api/performancenavigationtiming/index.md +++ b/files/en-us/web/api/performancenavigationtiming/index.md @@ -41,7 +41,7 @@ The interface also supports the following properties: - {{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. + - : 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. - {{domxref('PerformanceNavigationTiming.criticalCHRestart')}} {{ReadOnlyInline}} {{experimental_inline}} - : A {{domxref("DOMHighResTimeStamp")}} representing the time at which the connection restart occurred due to {{HTTPHeader("Critical-CH")}} HTTP response header mismatch. - {{domxref('PerformanceNavigationTiming.domComplete')}} {{ReadOnlyInline}} diff --git a/files/en-us/web/api/performancetimingconfidence/index.md b/files/en-us/web/api/performancetimingconfidence/index.md index 10009b7450035ea..854da918c3360a2 100644 --- a/files/en-us/web/api/performancetimingconfidence/index.md +++ b/files/en-us/web/api/performancetimingconfidence/index.md @@ -7,13 +7,55 @@ browser-compat: api.PerformanceTimingConfidence {{APIRef("Performance API")}} -The **`PerformanceTimingConfidence`** interface provides access to information that indicates whether the user agent considers returned navigation metrics to be representative of the current user's device. +The **`PerformanceTimingConfidence`** interface provides access to information that indicates whether the user agent considers returned navigation metrics to be free from external system load unrelated to the page. -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. +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. -The `PerformanceTimingConfidence` object for each navigation timing entry is accessed via the {{domxref("PerformanceNavigationTiming")}} interface's `confidence` property. +The `PerformanceTimingConfidence` object for each navigation timing entry is accessed via the {{domxref("PerformanceNavigationTiming")}} interface's {{domxref("PerformanceNavigationTiming.confidence", "confidence")}} property. + +## 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. + +To compute debiased means for both [`high` and `low` values](/en-US/docs/Web/API/PerformanceTimingConfidence/value#value): + +1. For each record: + - Let `p` be the record's {{domxref("PerformanceTimingConfidence.randomizedTriggerRate", "randomizedTriggerRate")}}. + - Let `c` be the record's {{domxref("PerformanceTimingConfidence.value", "value")}}. + - Let `R` be `1` when `c` is `high`, otherwise `0`. +2. Compute per-record weight `w` based on `c`: + - For estimating the `high` mean: `w = (R - (p / 2)) / (1 - p)`. + - For estimating the `low` mean: `w = ((1 - R) - (p / 2)) / (1 - p)`. + > [!NOTE] + > `w` may be negative for some records; you should keep every record. + - Let `weighted_duration = duration * w` (see {{domxref("PerformanceEntry.duration", "duration")}}). +3. Let `total_weighted_duration` be the sum of the `weighted_duration` values across all records. +4. Let `sum_weights` be the sum of the `w` values across all records. +5. Let `debiased_mean = total_weighted_duration / sum_weights`, provided `sum_weights` is not near zero. + +To compute debiased percentiles for both `high` and `low`: + +1. Follow the _computing debiased means_ steps to compute a per-record weight `w`. +2. Let `sum_weights` be the sum of the `w` values across all records. +3. Let `sorted_records` be all records sorted by duration in ascending order. +4. For a desired percentile (0-100), compute `q = percentile / 100.0`. +5. Walk `sorted_records` and for each record: + - Compute cumulative weight `cw` per-record: `cw = sum_{i: duration_i <= duration_j} w_i`. + - Compute debiased cumulative distribution function per-record: `cdf = cw / sum_weights`. +6. Find the first index `idx` where `cdf >= q`. + - If `idx` is `0`, return `duration` for `sorted_records[0]`. + - If no such `idx` exists, return `duration` for `sorted_records[n]`. +7. Compute interpolation fraction: + - Let `lower_cdf` be `cdf` for `sorted_records[idx-1]`. + - Let `upper_cdf` be `cdf` for `sorted_records[idx]`. + - if `lower_cdf = upper_cdf`, return `duration` for `sorted_records[idx]`. + - Otherwise: + - Let `ifrac = (q - lower_cdf) / (upper_cdf - lower_cdf)`. + - Let `lower_duration` be `duration` for `sorted_records[idx-1]`. + - Let `upper_duration` be `duration` for `sorted_records[idx]`. + - Return `lower_duration + (upper_duration - lower_duration) * ifrac`. ## Instance properties diff --git a/files/en-us/web/api/performancetimingconfidence/value/index.md b/files/en-us/web/api/performancetimingconfidence/value/index.md index 9133d83e588df33..73de69f6374867c 100644 --- a/files/en-us/web/api/performancetimingconfidence/value/index.md +++ b/files/en-us/web/api/performancetimingconfidence/value/index.md @@ -10,7 +10,7 @@ browser-compat: api.PerformanceTimingConfidence.value {{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. +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. ## Value From 1eb2ea4b25707836b5f739aa4af46a5bcb85dea7 Mon Sep 17 00:00:00 2001 From: Chris Mills Date: Mon, 30 Mar 2026 12:38:33 +0100 Subject: [PATCH 3/5] Fixes for Hamish comments --- .../navigation_timing/index.md | 8 ++++ .../confidence/index.md | 2 +- .../api/performancenavigationtiming/index.md | 2 +- .../api/performancetimingconfidence/index.md | 45 +++++++++++-------- .../randomizedtriggerrate/index.md | 4 +- .../value/index.md | 2 +- 6 files changed, 40 insertions(+), 23 deletions(-) diff --git a/files/en-us/web/api/performance_api/navigation_timing/index.md b/files/en-us/web/api/performance_api/navigation_timing/index.md index c0352b03419dc31..b6d41d01811d54a 100644 --- a/files/en-us/web/api/performance_api/navigation_timing/index.md +++ b/files/en-us/web/api/performance_api/navigation_timing/index.md @@ -29,6 +29,14 @@ The document navigation timestamps (in addition to those from [Resource Timing]( 8. {{domxref("PerformanceNavigationTiming.loadEventStart","loadEventStart")}}: timestamp immediately before the current document's [`load`](/en-US/docs/Web/API/Window/load_event) event handler starts. 9. {{domxref("PerformanceNavigationTiming.loadEventEnd","loadEventEnd")}}: timestamp immediately after the current document's [`load`](/en-US/docs/Web/API/Window/load_event) event handler completes. +## Performance timing confidence + +The {{domxref("PerformanceNavigationTiming.confidence")}} property returns a {{domxref("PerformanceTimingConfidence")}} object containing information that indicates whether a performance record reflects typical application performance, or is likely affected by external factors. + +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. See {{domxref("PerformanceTimingConfidence")}} for more information. + ## Other properties The {{domxref("PerformanceNavigationTiming")}} interface provides additional properties such as {{domxref("PerformanceNavigationTiming.redirectCount","redirectCount")}} returning the number of redirects and {{domxref("PerformanceNavigationTiming.type","type")}} indicating the type of navigation. diff --git a/files/en-us/web/api/performancenavigationtiming/confidence/index.md b/files/en-us/web/api/performancenavigationtiming/confidence/index.md index ecce405e955e648..32858067856729e 100644 --- a/files/en-us/web/api/performancenavigationtiming/confidence/index.md +++ b/files/en-us/web/api/performancenavigationtiming/confidence/index.md @@ -10,7 +10,7 @@ browser-compat: api.PerformanceNavigationTiming.confidence {{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. +The **`confidence`** read-only property of the {{domxref("PerformanceNavigationTiming")}} interface returns a {{domxref("PerformanceTimingConfidence")}} object containing information that indicates whether a performance record reflects typical application performance, or is likely affected by external factors. 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. diff --git a/files/en-us/web/api/performancenavigationtiming/index.md b/files/en-us/web/api/performancenavigationtiming/index.md index 3d6d3d15413793a..d8c67b475e7111d 100644 --- a/files/en-us/web/api/performancenavigationtiming/index.md +++ b/files/en-us/web/api/performancenavigationtiming/index.md @@ -41,7 +41,7 @@ The interface also supports the following properties: - {{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. + - : A {{domxref("PerformanceTimingConfidence")}} object containing information that indicates whether a performance record reflects typical application performance, or is likely affected by external factors. - {{domxref('PerformanceNavigationTiming.criticalCHRestart')}} {{ReadOnlyInline}} {{experimental_inline}} - : A {{domxref("DOMHighResTimeStamp")}} representing the time at which the connection restart occurred due to {{HTTPHeader("Critical-CH")}} HTTP response header mismatch. - {{domxref('PerformanceNavigationTiming.domComplete')}} {{ReadOnlyInline}} diff --git a/files/en-us/web/api/performancetimingconfidence/index.md b/files/en-us/web/api/performancetimingconfidence/index.md index 854da918c3360a2..b982d88e892f32c 100644 --- a/files/en-us/web/api/performancetimingconfidence/index.md +++ b/files/en-us/web/api/performancetimingconfidence/index.md @@ -7,17 +7,36 @@ browser-compat: api.PerformanceTimingConfidence {{APIRef("Performance API")}} -The **`PerformanceTimingConfidence`** interface provides access to information that indicates whether the user agent considers returned navigation metrics to be free from external system load unrelated to the page. +The **`PerformanceTimingConfidence`** interface provides access to information that indicates whether a performance record reflects typical application performance, or is likely affected by external factors. -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. +The `PerformanceTimingConfidence` object for each navigation timing entry is accessed via the {{domxref("PerformanceNavigationTiming")}} interface's {{domxref("PerformanceNavigationTiming.confidence", "confidence")}} property. + +## Instance properties + +- {{domxref("PerformanceTimingConfidence.randomizedTriggerRate")}} {{ReadOnlyInline}} + - : A number indicating how often noise is applied when exposing the `value`. +- {{domxref("PerformanceTimingConfidence.value")}} {{ReadOnlyInline}} + - : An enumerated value indicating a broad confidence measure of whether a performance record reflects typical application performance, or is likely affected by external factors. + +## Instance methods + +- {{domxref("PerformanceTimingConfidence.toJSON()")}} + - : Returns a JSON representation of the `PerformanceTimingConfidence` object. + +## Description + +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")}} is 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. + +> [!NOTE] +> Device factors such as CPU do not contribute to the performance assessment. Other factors than browser "cold start" and session restore may be taken into account in future updates. 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. -The `PerformanceTimingConfidence` object for each navigation timing entry is accessed via the {{domxref("PerformanceNavigationTiming")}} interface's {{domxref("PerformanceNavigationTiming.confidence", "confidence")}} property. +### Interpreting confidence data -## Interpreting confidence data +Since the {{domxref("PerformanceTimingConfidence.randomizedTriggerRate", "randomizedTriggerRate")}} can vary across records, per-record weighting is needed to recover unbiased aggregates. The procedures below illustrate how weighting based on {{domxref("PerformanceTimingConfidence.value", "value")}} can be applied before computing summary statistics. -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. +#### Computing debiased means To compute debiased means for both [`high` and `low` values](/en-US/docs/Web/API/PerformanceTimingConfidence/value#value): @@ -35,9 +54,11 @@ To compute debiased means for both [`high` and `low` values](/en-US/docs/Web/API 4. Let `sum_weights` be the sum of the `w` values across all records. 5. Let `debiased_mean = total_weighted_duration / sum_weights`, provided `sum_weights` is not near zero. +#### Computing debiased percentiles + To compute debiased percentiles for both `high` and `low`: -1. Follow the _computing debiased means_ steps to compute a per-record weight `w`. +1. Follow the [computing debiased means](#computing_debiased_means) steps to compute a per-record weight `w`. 2. Let `sum_weights` be the sum of the `w` values across all records. 3. Let `sorted_records` be all records sorted by duration in ascending order. 4. For a desired percentile (0-100), compute `q = percentile / 100.0`. @@ -57,18 +78,6 @@ To compute debiased percentiles for both `high` and `low`: - Let `upper_duration` be `duration` for `sorted_records[idx]`. - Return `lower_duration + (upper_duration - lower_duration) * ifrac`. -## Instance properties - -- {{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. - -## Instance methods - -- {{domxref("PerformanceTimingConfidence.toJSON()")}} - - : Returns a JSON representation of the `PerformanceTimingConfidence` object. - ## Examples ### Basic usage diff --git a/files/en-us/web/api/performancetimingconfidence/randomizedtriggerrate/index.md b/files/en-us/web/api/performancetimingconfidence/randomizedtriggerrate/index.md index 8fab5e57b442e68..6ae3e18e3974d05 100644 --- a/files/en-us/web/api/performancetimingconfidence/randomizedtriggerrate/index.md +++ b/files/en-us/web/api/performancetimingconfidence/randomizedtriggerrate/index.md @@ -10,11 +10,11 @@ browser-compat: api.PerformanceTimingConfidence.randomizedTriggerRate {{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")}}. +The **`randomizedTriggerRate`** read-only property of the {{domxref("PerformanceTimingConfidence")}} interface is a number indicating how often noise is applied when exposing the {{domxref("PerformanceTimingConfidence.value")}}. ## Value -A number inside the interval `0` to `1` inclusive. +A number between `0` to `1`, inclusive, which represents a percentage value. ## Examples diff --git a/files/en-us/web/api/performancetimingconfidence/value/index.md b/files/en-us/web/api/performancetimingconfidence/value/index.md index 73de69f6374867c..49051ec6d35ab3e 100644 --- a/files/en-us/web/api/performancetimingconfidence/value/index.md +++ b/files/en-us/web/api/performancetimingconfidence/value/index.md @@ -10,7 +10,7 @@ browser-compat: api.PerformanceTimingConfidence.value {{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. +The **`value`** read-only property of the {{domxref("PerformanceTimingConfidence")}} interface is an enumerated value indicating a broad confidence measure of whether a performance record reflects typical application performance, or is likely affected by external factors. ## Value From 2aa082ca72b15dbafcbc9a7695e839591cd1c585 Mon Sep 17 00:00:00 2001 From: Chris Mills Date: Fri, 1 May 2026 18:23:07 +0100 Subject: [PATCH 4/5] Updates to answer last couple of review questions --- files/en-us/web/api/performancetimingconfidence/index.md | 2 +- .../randomizedtriggerrate/index.md | 6 ++++-- .../web/api/performancetimingconfidence/value/index.md | 2 +- 3 files changed, 6 insertions(+), 4 deletions(-) diff --git a/files/en-us/web/api/performancetimingconfidence/index.md b/files/en-us/web/api/performancetimingconfidence/index.md index b982d88e892f32c..5c93da8b0dcea47 100644 --- a/files/en-us/web/api/performancetimingconfidence/index.md +++ b/files/en-us/web/api/performancetimingconfidence/index.md @@ -34,7 +34,7 @@ This confidence measure is useful for developers when trying to determine whethe ### Interpreting confidence data -Since the {{domxref("PerformanceTimingConfidence.randomizedTriggerRate", "randomizedTriggerRate")}} can vary across records, per-record weighting is needed to recover unbiased aggregates. The procedures below illustrate how weighting based on {{domxref("PerformanceTimingConfidence.value", "value")}} can be applied before computing summary statistics. +Since the {{domxref("PerformanceTimingConfidence.randomizedTriggerRate", "randomizedTriggerRate")}} can vary across records, per-record weighting is needed to recover unbiased aggregates, to improve consistency of data, cut down on compound errors, and generally produce more realistic and reliable results. The procedures below illustrate how weighting based on {{domxref("PerformanceTimingConfidence.value", "value")}} can be applied before computing summary statistics based on the confidence data. #### Computing debiased means diff --git a/files/en-us/web/api/performancetimingconfidence/randomizedtriggerrate/index.md b/files/en-us/web/api/performancetimingconfidence/randomizedtriggerrate/index.md index 6ae3e18e3974d05..fccf8d28021a8b6 100644 --- a/files/en-us/web/api/performancetimingconfidence/randomizedtriggerrate/index.md +++ b/files/en-us/web/api/performancetimingconfidence/randomizedtriggerrate/index.md @@ -10,11 +10,13 @@ browser-compat: api.PerformanceTimingConfidence.randomizedTriggerRate {{APIRef("Performance API")}}{{SeeCompatTable}} -The **`randomizedTriggerRate`** read-only property of the {{domxref("PerformanceTimingConfidence")}} interface is a number indicating how often noise is applied when exposing the {{domxref("PerformanceTimingConfidence.value")}}. +The **`randomizedTriggerRate`** read-only property of the {{domxref("PerformanceTimingConfidence")}} interface indicates how often noise is applied when exposing the {{domxref("PerformanceTimingConfidence.value")}}. + +Noise is added to the data to improve privacy (so that each data item is less easily identifiable). When noise is added, a `low` or `high` confidence `value` is returned with equal probability, rather than the true `value`, to obfuscate the results. ## Value -A number between `0` to `1`, inclusive, which represents a percentage value. +A number between `0` to `1`, inclusive, which represents a percentage value. A value of `0` is equivalent to `0%`, which means that noise is never added, while `1` is equivalent to `100%`, meaning that noise is always added. ## Examples diff --git a/files/en-us/web/api/performancetimingconfidence/value/index.md b/files/en-us/web/api/performancetimingconfidence/value/index.md index 49051ec6d35ab3e..0a275234801a49a 100644 --- a/files/en-us/web/api/performancetimingconfidence/value/index.md +++ b/files/en-us/web/api/performancetimingconfidence/value/index.md @@ -10,7 +10,7 @@ browser-compat: api.PerformanceTimingConfidence.value {{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 a performance record reflects typical application performance, or is likely affected by external factors. +The **`value`** read-only property of the {{domxref("PerformanceTimingConfidence")}} interface is a broad confidence measure of whether a performance record reflects typical application performance, or is likely affected by external factors. ## Value From 9a130c851887054a9a727dc773c5a4fe6e8914f2 Mon Sep 17 00:00:00 2001 From: Chris Mills Date: Tue, 5 May 2026 08:40:53 +0100 Subject: [PATCH 5/5] A couple more additions --- files/en-us/web/api/performancetimingconfidence/index.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/files/en-us/web/api/performancetimingconfidence/index.md b/files/en-us/web/api/performancetimingconfidence/index.md index 5c93da8b0dcea47..d423aa6fe6159d6 100644 --- a/files/en-us/web/api/performancetimingconfidence/index.md +++ b/files/en-us/web/api/performancetimingconfidence/index.md @@ -30,12 +30,14 @@ If a website has loaded after a browser "cold start" or session restore, its pag > [!NOTE] > Device factors such as CPU do not contribute to the performance assessment. Other factors than browser "cold start" and session restore may be taken into account in future updates. -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. +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. There is often a significant difference between real-world dashboard metrics and performance observations in page profiling tools. ### Interpreting confidence data Since the {{domxref("PerformanceTimingConfidence.randomizedTriggerRate", "randomizedTriggerRate")}} can vary across records, per-record weighting is needed to recover unbiased aggregates, to improve consistency of data, cut down on compound errors, and generally produce more realistic and reliable results. The procedures below illustrate how weighting based on {{domxref("PerformanceTimingConfidence.value", "value")}} can be applied before computing summary statistics based on the confidence data. +Once you have debiased the data and computed realistic summary statistics, you can focus on measuring and improving performance for issues under your control. + #### Computing debiased means To compute debiased means for both [`high` and `low` values](/en-US/docs/Web/API/PerformanceTimingConfidence/value#value):