Editorial review: Document PerformanceNavigationTiming.confidence

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 free from external system load unrelated to the page.
+
+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.
+
+## 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")}}

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 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}}

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"
+  }
 }
 ```
 

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

@@ -0,0 +1,101 @@
+---
+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 free from external system load unrelated to the page.
+
+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 {{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
+
+- {{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")}}

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")}}

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")}}

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 free from external system load unrelated to the page.
+
+## 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")}}