This specification defines an interface to help web developers measure the performance of their applications by giving them access to high precision timestamps.
User Timing Level 2 replaces the first version of [[USER-TIMING]] and includes:
PerformanceTiming
interface defined in [[NAVIGATION-TIMING-2]].Web developers need the ability to assess and understand the performance characteristics of their
applications. While JavaScript [ECMA262] provides a mechanism to measure application latency (retrieving the current
timestamp from the Date.now()
method), the precision of this timestamp varies between user agents.
This document defines the PerformanceMark and
PerformanceMeasure interfaces, and extensions to the
Performance
interface,
which expose a high precision, monotonically increasing timestamp so they can better measure the performance characteristics of their applications.
The following script shows how a developer can use the interfaces defined in this document to obtain timing data related to developer scripts.
<!doctype html> <html> <head> <title>User Timing example</title> </head> <body onload="init()"> <script> function init() { performance.mark("startTask1"); doTask1(); // Some developer code performance.mark("endTask1"); performance.mark("startTask2"); doTask2(); // Some developer code performance.mark("endTask2"); measurePerf(); } function measurePerf() { var perfEntries = performance.getEntriesByType("mark"); for (var i = 0; i < perfEntries.length; i++) { if (window.console) console.log("Name: " + perfEntries[i].name + " Entry Type: " + perfEntries[i].entryType + " Start Time: " + perfEntries[i].startTime + " Duration: " + perfEntries[i].duration + "\n"); } } </script> </body> </html>
[[PERFORMANCE-TIMELINE-2]] defines two mechanisms that
can be used to retrieve recorded metrics: getEntries()
and getEntriesByType()
methods, and the
PerformanceObserver
interface. The former is best suited
for cases where you want to retrieve a particular metric by name at a
single point in time, and the latter is optimized for cases where you
may want to receive notifications of new metrics as they become
available.
Some conformance requirements are phrased as requirements on attributes, methods or objects. Such requirements are to be interpreted as requirements on user agents.
The IDL fragments in this specification MUST be interpreted as required for conforming IDL fragments, as described in the Web IDL specification. [[!WebIDL]]
Performance
Interfacepartial interface Performance { void mark(DOMString markName); void clearMarks(optional DOMString markName); void measure(DOMString measureName, optional DOMString startMark, optional DOMString endMark); void clearMeasures(optional DOMString measureName); };
The mark(markName) method stores a timestamp with the associated name (a "mark"). It MUST run these steps:
Window
object and markName uses the same name as a read only attribute in the
PerformanceTiming
interface [[!NAVIGATION-TIMING-2]], throw a SyntaxError
.name
to markName.
entryType
to DOMString "mark"
.
startTime
to be the value that would be returned by the Performance
object's now()
method.duration
to 0
.PerformanceMark
object to the performance entry buffer.The clearMarks(markName) removes stored timestamp with the associated name. It MUST run these steps:
The measure(measureName, startMark, endMark) method stores the DOMHighResTimeStamp
duration between two marks along with the associated name (a "measure"). It MUST run these steps:
Performance
object's now()
method. Otherwise let end time be the value of the startTime
attribute from the most recent occurence PerformanceMark object in the performance entry buffer whose name
matches value endMark.startTime
attribute from the most recent occurence PerformanceMark object in the performance entry buffer whose name
matches value startMark.name
to measureName.
entryType
to DOMString "measure"
.
startTime
to start time.duration
to the duration from start time to end time. The resulting duration value MAY be negative.PerformanceMeasure
object to the performance entry buffer.The clearMeasures(measureName) removes stored timestamp with the associated name. It MUST run these steps:
name
matches measureName.PerformanceMark
InterfaceThe PerformanceMark interface also exposes marks created via the Performance.mark method to the Performance Timeline [[!PERFORMANCE-TIMELINE-2]].
[Exposed=(Window,Worker)] interface PerformanceMark : PerformanceEntry { };
The PerformanceMark interface extends the following attributes of the PerformanceEntry interface:
The name
attribute will return the mark's name.
The entryType
attribute will return the DOMString
"mark"
.
The startTime
attribute will return a DOMHighResTimeStamp
with the mark's time value [[!HR-TIME-2]].
The duration
attribute will return a DOMHighResTimeStamp
of value 0.
PerformanceMeasure
InterfaceThe PerformanceMeasure interface also exposes measures created via the Performance.measure method to the Performance Timeline [[!PERFORMANCE-TIMELINE-2]].
[Exposed=(Window,Worker)] interface PerformanceMeasure : PerformanceEntry { };
The PerformanceMeasure interface extends the following attributes of the PerformanceEntry interface:
The name
attribute will return the measure's name.
The entryType
attribute will return the DOMString
"measure"
.
The startTime
attribute will return a DOMHighResTimeStamp
with the measure's start mark [[!HR-TIME-2]].
The duration
attribute will return a DOMHighResTimeStamp
with the duration of the measure.
The interfaces defined in this specification expose potentially sensitive timing information on specific JavaScript activity of a page. Please refer to [[HR-TIME-2]] for privacy and security considerations of exposing high-resolution timing information.
Because the web platform has been designed with the invariant that any script included on a page has the same access as any other script included on the same page, regardless of the origin of either scripts, the interfaces defined by this specification do not place any restrictions on recording or retrieval of recorded timing information - i.e. a user timing mark or measure recorded by any script included on the page can be read by any other script running on the same page, regardless of origin.
Thanks to James Simonsen, Jason Weber, Nic Jansma, Philippe Le Hegaret, Karen Anderson, Steve Souders, Sigbjorn Vik, Todd Reifsteck, and Tony Gentilcore for their contributions to this work.