From 2fbad3b22ac7f73be4bbd3628bd9edfd7f954bf7 Mon Sep 17 00:00:00 2001 From: Chris Mills Date: Mon, 23 Mar 2026 09:35:19 +0000 Subject: [PATCH 1/2] 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 2930c97255e06a61659a9cec95ca95216d1dee06 Mon Sep 17 00:00:00 2001 From: Chris Mills Date: Fri, 27 Mar 2026 16:38:57 +0000 Subject: [PATCH 2/2] 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