Copyright © 2015 W3C® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and document use rules apply.
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 section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.
This is a work in progress and may change without any notices.
This document was published by the Web Performance Working Group as a Working Draft.
This document is intended to become a W3C Recommendation.
If you wish to make comments regarding this document, please send them to
public-web-perf@w3.org
(subscribe,
archives)
with [Frame Timing] at the start of your email's subject.
All comments are welcome.
Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
This document is governed by the 1 September 2015 W3C Process Document.
This section is non-normative.
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:
requestAnimationFramerequestAnimationFramerequestAnimationFrame 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.
As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.
The key words MAY, MUST, and SHOULD are to be interpreted as described in [RFC2119].
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.
This section is non-normative.
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:
PerformanceRenderTiming captures the work performed by the
renderer to process the frame: DOM modification, JavaScript
execution, CSS calculation, and similar activities.
PerformanceCompositeTiming captures events performed by the
compositor to place rendered content onto the screen.
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 Interfacepartial interface Performance {
void clearFrameTimings ();
void setFrameTimingBufferSize (unsigned long maxSize);
attribute EventHandler onframetimingbufferfull;
};onframetimingbufferfull of type EventHandler, 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].
clearFrameTimingsclearFrameTimings clears the buffer used to
store the current list of PerformanceRenderTiming resources.
voidsetFrameTimingBufferSizesetFrameTimingBufferSize 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.
| Parameter | Type | Nullable | Optional | Description |
|---|---|---|---|---|
| maxSize | unsigned long | ✘ | ✘ | The maxSize parameter sets the maximum number of PerformanceRenderTiming resources that will be stored in the buffer. |
voidPerformanceRenderTiming InterfaceThe PerformanceRenderTiming interface participates in the
Performance
Timeline and extends the following attributes of the PerformanceEntry
interface [Performance-Timeline]:
nameentryTypeDOMString
"render".
startTimeDOMHighResTimeStamp
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].
durationDOMHighResTimeStamp
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.
interface PerformanceRenderTiming : PerformanceEntry {
readonly attribute unsigned long sourceFrameNumber;
serializer = {inherit, attribute};
};sourceFrameNumber of type unsigned long, readonly PerformanceRenderTiming and
PerformanceCompositeTiming events to measure time-to-frame
delays.Instances of this interface are serialized as a map with entries from the closest inherited interface and with entries for each of the serializable attributes.
PerformanceCompositeTiming InterfaceThe PerformanceCompositeTiming interface participates in the
Performance
Timeline and extends the following attributes of the PerformanceEntry
interface [Performance-Timeline]:
nameentryTypeDOMString
"composite".
startTimeDOMHighResTimeStamp
with the event's time value [HR-Time].
durationduration attribute MUST return a DOMHighResTimeStamp
of value 0.
interface PerformanceCompositeTiming : PerformanceEntry {
readonly attribute unsigned long sourceFrameNumber;
serializer = {inherit, attribute};
};sourceFrameNumber of type unsigned long, readonly PerformanceRenderTiming and
PerformanceCompositeTiming events to measure time-to-frame
delays.Instances of this interface are serialized as a map with entries from the closest inherited interface and with entries for each of the serializable attributes.
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.
This section is non-normative.
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, Chris Harrelson, Timothy Robert Ansell, Vladimir Levin, and Nat Duca for their helpful comments and contributions to this work.