Performance APIs
Note: This feature is available inWeb Workers.
The Performance API is a group of standards used to measure the performance of web applications.
Concepts and usage
To ensure web applications are fast, it's important to measure and analyze various performance metrics. The Performance API provides important built-in metrics and the ability to add your own measurements to the browser's performance timeline. The performance timeline contains high precision timestamps and can be displayed in developer tools. You can also send its data to analytics end points to record performance metrics over time.
Each performance metric is represented by a singlePerformanceEntry. A performance entry has aname, aduration, astartTime, and atype. All performance metrics extend thePerformanceEntry interface and qualify it further.
Most of the performance entries are recorded for you without you having to do anything, and are then accessible either throughPerformance.getEntries() or (preferably) throughPerformanceObserver. For example,PerformanceEventTiming entries are recorded for events that take longer than a set threshold. But the Performance API also enables you to define and record your own custom events, using thePerformanceMark andPerformanceMeasure interfaces.
The mainPerformance interface is available in bothWindow andWorker global scopes, and enables you to add custom performance entries, to clear performance entries, and to retrieve performance entries.
ThePerformanceObserver interface enables you to listen for various types of performance entry as they are recorded.
For more conceptual information, see thePerformance API guides below.
Reference
The following interfaces are present in the Performance API:
EventCountsA read-only map returned by
performance.eventCountscontaining the number of events which have been dispatched per event type.LargestContentfulPaintMeasures the render time of the largest image or text block visible within the viewport, recorded from when the page first begins to load.
LayoutShiftProvides insights into the layout stability of web pages based on movements of the elements on the page.
LayoutShiftAttributionProvides debugging information about elements which have shifted.
NotRestoredReasonDetailsRepresents a single reason why a navigated page was blocked from using the back/forward cache (bfcache).
NotRestoredReasonsProvides report data containing reasons why the current document was blocked from using the back/forward cache (bfcache) on navigation.
PerformanceMain interface to access performance measurements. Available to window and worker contexts using
Window.performanceorWorkerGlobalScope.performance.PerformanceElementTimingMeasures rendering timestamps of specific elements.
PerformanceEntryAn entry on the performance timeline encapsulating a single performance metric. All performance metrics inherit from this interface.
PerformanceEventTimingMeasures latency of events andInteraction to Next Paint (INP).
PerformanceLongAnimationFrameTimingProvides metrics onlong animation frames (LoAFs) that occupy rendering and block other tasks from being executed.
PerformanceLongTaskTimingProvides metrics onlong tasks that occupy rendering and block other tasks from being executed.
PerformanceMarkCustom marker for your own entry on the performance timeline.
PerformanceMeasureCustom time measurement between two performance entries.
PerformanceNavigationTimingMeasures document navigation events, like how much time it takes to load a document.
PerformanceObserverListens for new performance entries as they are recorded in the performance timeline.
PerformanceObserverEntryListList of entries that were observed in a performance observer.
PerformancePaintTimingMeasures render operations during web page construction.
PerformanceResourceTimingMeasures network loading metrics such as redirect start and end times, fetch start, DNS lookup start and end times, response start and end times for resources such as images, scripts, fetch calls, etc.
PerformanceScriptTimingProvides metrics on individual scripts causinglong animation frames (LoAFs).
PerformanceServerTimingSurfaces server metrics that are sent with the response in the
Server-TimingHTTP header.TaskAttributionTimingIdentifies the type of task and the container that is responsible for the long task.
VisibilityStateEntryMeasures the timing of page visibility state changes, i.e., when a tab changes from the foreground to the background or vice versa.
Guides
The following guides help you to understand key concepts of the Performance API and provide an overview about its abilities:
- Performance data: Collecting, accessing, and working with performance data.
- High precision timing: Measuring with high precision time and monotonic clocks.
- Resource timing: Measuring network timing for fetched resources, such as images, CSS, and JavaScript.
- Navigation timing: Measuring navigation timing of a document.
- User timing: Measuring and recording performance data custom to your application.
- Server timing: Collecting server-side metrics.
- Long animation frame timing: Collecting metrics on long animation frames (LoAFs) and their causes.
- Monitoring bfcache blocking reasons: Reporting on why the current document was blocked from using the back/forward cache (bfcache).