Frame Timing API
This is an experimental technology
Because this technology's specification has not stabilized, check the compatibility table for usage in various browsers. Also note that the syntax and behavior of an experimental technology is subject to change in future versions of browsers as the specification changes.
PerformanceFrameTiming interface provides frame timing data about the browser's event loop. A frame represents the amount of work a browser does in one event loop iteration such as processing DOM events, resizing, scrolling, rendering, CSS animations, etc. A frame rate of 60 fps (frames per second) for a 60 Hz refresh rate is a common target for a good responsive user experience. This means the browser should process a frame in about 16.7 ms.
An application can register a
PerformanceObserver for "
performance entry types. The observer (callback) will be notified when new "
frame" events are added to the browser's performance timeline and the frame's
duration (length of time) will be available. This data can be used to help identify areas that take too long to provide a good user experience.
Example code of the interfaces described in this document is included in Using the Frame Timing API.
PerformanceFrameTiming interface extends the following
PerformanceEntry properties (for "
performance entry types) by qualifying and constrainting the properties as follows:
- Set to "
- Set to the document's address.
- Set to the
DOMHighResTimeStampwhen the frame was started.
- Set to a
timestampindicating the difference between the
startTimes of two successive frames.
This data, particularly the
duration timestamp, can be used to help identify performance problems.
The performance observer interfaces allow an application to register an observer for specific
performance event types. When one of those event types is recorded in the browser's performance timeline, the application is notified of the event via the observer's callback function that was specified when the observer was created.
To observe "
frame" performance entry types, the application first creates a
PerformanceObserver object with a specific frame observer callback (function). Next,
PerformanceObserver.observe() is used to specify the set of performance events to observe - in this case, just the "
frame" event type. When the browser adds a new frame to the performance timeline, the specified observer callback will be invoked.
Accessing frame data
When a frame
observer is invoked, frame
performance entries can be retrieved by calling
PerformanceObserverEntryList.getEntriesByType() with an argument of "
frame". This method returns a list of "
PerformanceEntry objects. Each frame object's
duration property returns the timestamp of two consecutive frames. If this value is greater than the time needed to provide a good user experience, further analysis might be warranted.
As shown in the
PerformanceFrameTiming interface's Browser Compatibility table, this interface has no implementations.
© 2016 Mozilla Contributors
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.