PerformanceTimingConfidence
Performance API
Performance API
The PerformanceTimingConfidence interface provides access to information that indicates whether a performance record reflects typical application performance, or is likely affected by external factors.
The PerformanceTimingConfidence object for each navigation timing entry is accessed via the PerformanceNavigationTiming interface's confidence property.
Instance properties
- PerformanceTimingConfidence.randomizedTriggerRate
- : A number indicating how often noise is applied when exposing the
value. - PerformanceTimingConfidence.value
- : 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
- PerformanceTimingConfidence.toJSON()
- : Returns a JSON-serializable plain object representing the
PerformanceTimingConfidenceobject. Automatically called by JSON.stringify().
Description
If a website has loaded after a browser "cold start" or session restore, its pages may load more slowly as a result. This can cause a significant difference between real-world dashboard metrics and performance observations in page profiling tools, making it hard for a developer to understand whether a performance issue is a legitimate concern or an outlier caused by external factors.
The PerformanceTimingConfidence interface allows developers to compensate for this problem by returning a browser estimate (in the value property) of the likelihood that a returned performance record represents typical application performance.
This is a value of either "low" or "high", indicating the browser's confidence in the measurement.
[!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.
To reduce the possibility of using the value for fingerprinting, noise is added to the estimate, meaning the value will deliberately be wrong for some proportion of results.
The trigger rate for the noise is given in the randomizedTriggerRate property.
Since this can vary across records, per-record weighting is needed to recover unbiased aggregates, to improve data consistency, reduce the number of compound errors, and generally to produce a baseline against which the measured results can be evaluated.
Using the data
You should use the data as follows to extract meaningful information from the randomized values:
- When collecting PerformanceNavigationTiming records, collect randomizedTriggerRate and value for each record.
- When computing statistics such as 75th-percentile Largest contentful paint (LCP) or mean page load time, apply the weighting formulas explained below instead of a plain average — this gives you separate, corrected metrics for "typical" loads vs. "degraded" loads.
- Use the "high" confidence mean/percentile as your "real" performance baseline, and use the "low" one to understand what typical data looks like in cold-start scenarios.
The procedures below illustrate how weighting based on value can be applied before computing summary statistics based on the confidence data.
Computing debiased means
To compute debiased means for both high and low values:
- For each record:
- Let
pbe the record's randomizedTriggerRate. - Letcbe the record's value. - LetRbe1whencishigh, otherwise0. - Compute per-record weight
wbased onc: - For estimating thehighmean:w = (R - (p / 2)) / (1 - p). - For estimating thelowmean:w = ((1 - R) - (p / 2)) / (1 - p). > [!NOTE] >wmay be negative for some records; you should keep every record. - Letweighted_duration = duration * w(see duration). - Let
total_weighted_durationbe the sum of theweighted_durationvalues across all records. - Let
sum_weightsbe the sum of thewvalues across all records. - Let
debiased_mean = total_weighted_duration / sum_weights, providedsum_weightsis not near zero.
Computing debiased percentiles
To compute debiased percentiles for both high and low:
- Follow the computing debiased means steps to compute a per-record weight
w. - Let
sum_weightsbe the sum of thewvalues across all records. - Let
sorted_recordsbe all records sorted by duration in ascending order. - For a desired percentile (0-100), compute
q = percentile / 100.0. - Walk
sorted_recordsand for each record: - Compute cumulative weightcwper-record:cw = sum_{i: duration_i <= duration_j} w_i. - Compute debiased cumulative distribution function per-record:cdf = cw / sum_weights. - Find the first index
idxwherecdf >= q. - Ifidxis0, returndurationforsorted_records[0]. - If no suchidxexists, returndurationforsorted_records[n]. - Compute interpolation fraction:
- Let
lower_cdfbecdfforsorted_records[idx-1]. - Letupper_cdfbecdfforsorted_records[idx]. - iflower_cdf = upper_cdf, returndurationforsorted_records[idx]. - Otherwise:- Let
ifrac = (q - lower_cdf) / (upper_cdf - lower_cdf). - Let
lower_durationbedurationforsorted_records[idx-1]. - Let
upper_durationbedurationforsorted_records[idx]. - Return
lower_duration + (upper_duration - lower_duration) * ifrac.
- Let
Examples
Basic usage
This example uses a PerformanceObserver to retrieve confidence data from observed PerformanceNavigationTiming entries.
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
Browser compatibility
See also
- PerformanceNavigationTiming