High precision timing
The Performance API allows high precision measurements that are based on time in potential sub-millisecond resolution and a stable monotonic clock that is not subject to system clock skew or adjustments.The high resolution timers are needed for accurate benchmarking instead of the less precise and non-monotonicDate timestamps.
This page provides an overview about how high precision time works within the Performance API and how it compares toDate timestamps.
DOMHighResTimeStamp
High precision timing is achieved by using theDOMHighResTimeStamp type for time values. The unit is milliseconds and should be accurate to 5 µs (microseconds). However, if the browser is unable to provide a time value accurate to 5 microseconds, the browser can represent the value as a time in milliseconds accurate to a millisecond. This might occur because of hardware/software constraints, or security and privacy reasons. For more information, see the section onreduced precision below.
All timestamps in the Performance API use theDOMHighResTimeStamp type. Previously, the Performance API (and other Web APIs) used theEpochTimeStamp type (previously known asDOMTimeStamp). These types are now discouraged.
Performance.now() vs.Date.now()
JavaScript definesDate.now() as the number of milliseconds elapsed since theepoch, which is defined as the midnight at the beginning of January 1, 1970, UTC. Theperformance.now() method on the other hand is relative to thePerformance.timeOrigin property. For more information, see thetime origins section below.
JavaScriptDate times are subject to system clock skew or adjustments. This means that the value of time may not always be monotonically increasing. The main purpose ofDate objects is to display time and date information to the user and so many operating systems run a daemon which regularly synchronizes time. It might be that the clock is tweaked a few milliseconds several times per hour.
Theperformance.now() method (and all otherDOMHighResTimeStamp values) provide monotonically increasing time values and aren't subject to clock adjustments. This means that it is guaranteedDOMHighResTimeStamp values will be at least equal to, if not greater than, the last time you accessed it.
Date.now(); // 1678889977578performance.now(); // 233936For measuring performance, calculating precise frame rates (FPS), animation loops, etc., use monotonically increasing high resolution time available withPerformance.now() instead of JavaScript'sDate.now().
To summarize:
| - | Performance.now() | Date.now() |
|---|---|---|
| Resolution | sub-milliseconds | milliseconds |
| Origin | Performance.timeOrigin | Unix Epoch (January 1, 1970, UTC) |
| Use clock adjustments | No | Yes |
| Monotonically increasing | Yes | No |
Time origins
The Performance API uses thePerformance.timeOrigin property to determine the baseline for performance-related timestamps. AllDOMHighResTimeStamp times are relative to thetimeOrigin property.
In Window contexts, this time origin is the time when navigation has started. InWorker andServiceWorker contexts, the time origin is the time when the worker is run.
In the previous version of the specification (Level 1), theperformance.now() method used to be relative toperformance.timing.navigationStart property from the Navigation Timing specification. However, this changed in a later version of the specification (Level 2) andperformance.now() is now relative toPerformance.timeOrigin which avoids clock change risks when comparing timestamps across webpages.
// Level 1 (clock change risks)currentTime = performance.timing.navigationStart + performance.now();// Level 2 (no clock change risks)currentTime = performance.timeOrigin + performance.now();Synchronizing time origins between contexts
To account for the different time origins in window and worker contexts, you should translate the timestamps coming from worker scripts with the help of thetimeOrigin property, so the timings synchronize for the entire application. See the examples section on thePerformance.timeOrigin page for example code to synchronize time.
Reduced precision
To offer protection against timing attacks andfingerprinting,DOMHighResTimeStamp types are coarsened based on site isolation status.
- Resolution in isolated contexts: 5 microseconds
- Resolution in non-isolated contexts: 100 microseconds
To apply cross-origin isolation to your site, use theCross-Origin-Opener-Policy (COOP) andCross-Origin-Embedder-Policy (COEP) headers:
Cross-Origin-Opener-Policy: same-originCross-Origin-Embedder-Policy: require-corpThese headers ensure a top-level document does not share a browsing context group withcross-origin documents.Cross-Origin-Opener-Policy process-isolates your document and potential attackerscan't access to your global object if they were opening it in a popup, preventing a setof cross-origin attacks dubbedXS-Leaks.