This specification defines an interface to help web developers measure the performance of their applications by giving them access to frame performance data to facilitate smoothness (i.e. Frames per Second and Time to Frame) measurements.
This is a work in progress and may change without any notices.
Web developers need the ability to assess and understand the performance characteristics of their applications. While JavaScript [[ECMA-262]] provides a mechanism to approximate application Frames per Second (FPS) and Time to Frame (TTF) (by calling a nearly empty requestAnimationFrame
[[Animation-Timing]] in a loop), the precision of this method has a high variance. Some example situations where this returns misleading results are:
requestAnimationFrame
requestAnimationFrame
requestAnimationFrame
event even though the new content has not yet been displayed to the user.
This document defines the PerformanceRenderTiming
and PerformanceCompositeTiming
interfaces, and extensions to the Performance
interface, which expose frame performance data to be used for smoothness measurements.
Requirements phrased in the imperative as part of algorithms (such as "strip any leading space characters" or "return false and abort these steps") are to be interpreted with the meaning of the key word ("MUST", "SHOULD", "MAY", etc) used in introducing the algorithm.
Some conformance requirements are phrased as requirements on attributes, methods or objects. Such requirements are to be interpreted as requirements on user agents.
Conformance requirements phrased as algorithms or specific steps may be implemented in any manner, so long as the end result is equivalent. (In particular, the algorithms defined in this specification are intended to be easy to follow, and not intended to be performant.)
The IDL fragments in this specification MUST be interpreted as required for conforming IDL fragments, as described in the Web IDL specification. [[!WebIDL]]
The construction "a Foo
object", where Foo
is actually an interface, is sometimes used instead of the more accurate "an object implementing the interface Foo".
The term "JavaScript" is used to refer to ECMAScript [[ECMA-262]], rather than the official term ECMAScript, since the term JavaScript is more widely known.
The PerformanceRenderTiming and PerformanceCompositeTiming interfaces, and extensions to the Performance interface, enable web developers to measure the performance of their applications by giving them access to frame performance data to facilitate smoothness (i.e. FPS and TTF) measurements:
The relationship between PerformanceRenderTiming and PerformanceCompositeTiming events will vary based on the workload, and architecture and configuration of the user agent. For example, the user agent may report many PerformanceCompositeTiming events corresponding to a single PerformanceRenderTiming event due to a CSS animation, composite thread scrolling, or similar activities. Other workloads may result in 1:1 mapping of PerformanceRenderTiming and PerformanceCompositeTiming events, and the exact relationship is also subject to user agent architecture and configuration.
Performance
Interface
clearFrameTimings
clears the buffer used to store the current list of PerformanceRenderTiming resources.
setFrameTimingBufferSize
method, when invoked, MUST set the maximum number of PerformanceRenderTiming resources that may be stored in the buffer to the value of the maxSize
parameter.
frametimingbufferfull
event. Immediately after the buffer used to store the list of PerformanceRenderTiming and PerformanceCompositeTiming
resources becomes full, the User Agent MUST fire a simple event named frametimingbufferfull
that bubbles, isn't cancelable, has no default action, at the
Performance object [[!Navigation-Timing-2]].
PerformanceRenderTiming
InterfaceThe PerformanceRenderTiming interface participates in the Performance Timeline and extends the following attributes of the PerformanceEntry interface [[!Performance-Timeline]]:
name
entryType
DOMString
"render
".
startTime
DOMHighResTimeStamp
with current frame's beginning time value, which is the time that the requestAnimationFrame
callback (see [[!Animation-Timing]]) would have fired for the frame. [[!HR-Time]].
duration
DOMHighResTimeStamp
with the difference between the end of the frame and the startTime
of the frame. The end of the frame is defined as what the beginning time of the next frame's requestAnimationFrame
callback (see [[!Animation-Timing]]) would have been, had one been scheduled in the current frame. If a requestAnimationFrame
is already requested, its beginning time SHOULD be used.
PerformanceRenderTiming
and PerformanceCompositeTiming
events to measure time-to-frame delays.
PerformanceCompositeTiming
InterfaceThe PerformanceCompositeTiming interface participates in the Performance Timeline and extends the following attributes of the PerformanceEntry interface [[!Performance-Timeline]]:
name
entryType
DOMString
"composite
".
startTime
DOMHighResTimeStamp
with the event's time value [[!HR-Time]].
duration
duration
attribute MUST return a DOMHighResTimeStamp
of value 0.
PerformanceRenderTiming
and PerformanceCompositeTiming
events to measure time-to-frame delays.
The time values stored within the interface MUST monotonically increase to ensure they are not affected by adjustments to the system clock. The difference between any two chronologically recorded time values MUST never be negative. The user agent MUST record the system clock at the beginning of the navigation and define subsequent time values in terms of a monotonic clock measuring time elapsed from the beginning of the navigation.
The interfaces defined in this specification expose potentially sensitive timing information on specific JavaScript activity of a page. However, unlike other interfaces defined in the Performance Timeline, the interfaces defined in this specification do not have any restrictions on sharing timing information through script. This is 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 that page regardless of the origin of the script.
Thanks to Enne Walker, Rick Byers and Chris Harrelson for their helpful comments.