diff --git a/files/en-us/web/api/performance_api/diagram.svg b/files/en-us/web/api/performance_api/diagram.svg new file mode 100644 index 000000000000000..5ccb0cefecbc6b2 --- /dev/null +++ b/files/en-us/web/api/performance_api/diagram.svg @@ -0,0 +1 @@ +
PerformanceEntry
PerformanceMark
PerformanceMeasure
PerformancePaintTiming
PerformanceResourceTiming
PerformanceNavigationTiming
PerformanceElementTiming
PerformanceLongTaskTiming
PerformanceEventTiming
TaskAttributionTiming
LargestContentfulPaint
Performance
PerformanceObserverText is not SVG - cannot display \ No newline at end of file diff --git a/files/en-us/web/api/performance_api/index.md b/files/en-us/web/api/performance_api/index.md index d29058d055c5a1d..dd67c4fd9c4dba1 100644 --- a/files/en-us/web/api/performance_api/index.md +++ b/files/en-us/web/api/performance_api/index.md @@ -3,70 +3,89 @@ title: Performance API slug: Web/API/Performance_API page-type: web-api-overview tags: - - Guide - - NeedsContent - Overview - Performance - Web Performance spec-urls: + - https://wicg.github.io/element-timing/ + - https://w3c.github.io/event-timing/ - https://w3c.github.io/hr-time/ + - https://w3c.github.io/largest-contentful-paint/ + - https://w3c.github.io/longtasks/ - https://w3c.github.io/navigation-timing/ + - https://w3c.github.io/paint-timing/ - https://w3c.github.io/performance-timeline/ - https://w3c.github.io/resource-timing/ + - https://w3c.github.io/server-timing/ - https://w3c.github.io/user-timing/ --- -{{DefaultAPISidebar("High Resolution Time")}} +{{DefaultAPISidebar("Performance API")}} -The [High Resolution Time](https://www.w3.org/TR/hr-time/) standard defines a {{domxref("Performance")}} interface that supports client-side latency measurements within applications. The {{domxref("Performance")}} interfaces are considered _high resolution_ because they are accurate to a thousandth of a millisecond (subject to hardware or software constraints). The interfaces support a number of use cases including calculating frame-rates (potentially important in animations) and benchmarking (such as the time to load a resource). +The Performance API is a group of standards used to measure the performance of web applications. -Since a platform's _system clock_ is subject to various _skews_ (such as NTP adjustments), the interfaces support a _monotonic clock_ i.e. a clock that is always increasing. As such, the `Performance` API defines a {{domxref("DOMHighResTimeStamp")}} type rather than using the {{jsxref("Date.now","Date.now()")}} interface. +## Concepts and usage -## DOMHighResTimeStamp +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 you 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. -The {{domxref("DOMHighResTimeStamp")}} type, as its name implies, represents a high resolution point in time. This type is a `double` and is used by the performance interfaces. The value could be a discrete point in time or the difference in time between two discrete points in time. +Each performance metric is represented by a single {{domxref("PerformanceEntry")}}. A performance entry has a `name`, a `duration`, a `startTime`, and a `type`. All performance metrics extend the `PerformanceEntry` interface and qualify it further. -The unit of `DOMHighResTimeStamp` is milliseconds and should be accurate to 5 µs (microseconds). However, If the browser is unable to provide a time value accurate to 5 microseconds (because, for example, due to hardware or software constraints), the browser can represent the value as a time in milliseconds accurate to a millisecond. +Most of the performance entries are recorded for you without you having to do anything, and are then accessible either through {{domxref("Performance.getEntries()")}} or (preferably) through {{domxref("PerformanceObserver")}}. For example, {{domxref("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 the {{domxref("PerformanceMark")}} and {{domxref("PerformanceMeasure")}} interfaces. -## Instance methods +The main {{domxref("Performance")}} interface is available for each global using {{domxref("performance_property", "self.performance")}} and enables you to add custom performance entries, to clear performance entries, and to retrieve performance entries. -The {{domxref("Performance")}} interface has two methods. The {{domxref("Performance.now","now()")}} method returns a {{domxref("DOMHighResTimeStamp")}} whose value that depends on the {{domxref("PerformanceTiming.navigationStart","navigation start")}} and scope. If the scope is a window, the value is the time the browser context was created and if the scope is a {{domxref("Worker","worker")}}, the value is the time the worker was created. +The {{domxref("PerformanceObserver")}} interface enables you to listen for various types of performance entry as they are recorded. -The {{domxref("Performance.toJSON","toJSON()")}} method returns a serialization of the {{domxref("Performance")}} object, for those attributes that can be serialized. - -## Instance properties - -The {{domxref("Performance")}} interface has two properties. The {{domxref("Performance.timing","timing")}} property returns a {{domxref("PerformanceTiming")}} object containing latency-related performance information such as the start of navigation time, start and end times for redirects, start and end times for responses, etc. - -The {{domxref("Performance.navigation","navigation")}} property returns a {{domxref("PerformanceNavigation")}} object representing the type of navigation that occurs in the given browsing context, such as the page was navigated to from history, the page was navigated to by following a link, etc. +![UML diagram of Performance APIs](diagram.svg) ## Interfaces -- {{domxref('Performance')}} - - : Provides methods and properties containing timing-related performance information for the given page. -- {{domxref('PerformanceEntry')}} - - : Provides methods and properties the encapsulate a single performance metric that is part of the performance timeline. -- {{domxref('PerformanceMark')}} - - : An abstract interface for [performance entries](/en-US/docs/Web/API/PerformanceEntry) with an [entry type](/en-US/docs/Web/API/PerformanceEntry/entryType) of "`mark`". Entries of this type are created by calling [`performance.mark()`](/en-US/docs/Web/API/Performance/mark) to add a named [`DOMHighResTimeStamp`](/en-US/docs/Web/API/DOMHighResTimeStamp) (the mark) to the browser's performance timeline. -- {{domxref('PerformanceMeasure')}} - - : An abstract interface for [performance entries](/en-US/docs/Web/API/PerformanceEntry) with an [entry type](/en-US/docs/Web/API/PerformanceEntry/entryType) of "`measure`". Entries of this type are created by calling [`performance.measure()`](/en-US/docs/Web/API/Performance/measure) to add a named [`DOMHighResTimeStamp`](/en-US/docs/Web/API/DOMHighResTimeStamp) (the measure) between two marks to the browser's performance timeline. -- {{domxref('PerformanceNavigationTiming')}} - - : Provides methods and properties to store and retrieve [high resolution timestamps](/en-US/docs/Web/API/DOMHighResTimeStamp) or metrics regarding the browser's document navigation events. -- {{domxref('PerformanceObserver')}} - - : Provides methods and properties used to observe performance measurement events and be notified of new [performance entries](/en-US/docs/Web/API/PerformanceEntry) as they are recorded in the browser's performance timeline. -- {{domxref('PerformanceResourceTiming')}} - - : Provides methods and properties for retrieving and analyzing detailed network timing data regarding the loading of an application's resources. +- {{domxref("EventCounts")}} + - : A read-only map returned by {{domxref("performance.eventCounts")}} containing the number of events which have been dispatched per event type. +- {{domxref("LargestContentfulPaint")}} + - : Measures the render time of the largest image or text block visible within the viewport, recorded from when the page first begins to load. +- {{domxref("Performance")}} + - : Main interface to access performance measurements. Available to window and worker contexts using {{domxref("performance_property", "self.performance")}}. +- {{domxref("PerformanceElementTiming")}} + - : Measures rendering timestamps of specific elements. +- {{domxref("PerformanceEntry")}} + - : An entry on the performance timeline encapsulating a single performance metric. All performance metrics inherit from this interface. +- {{domxref("PerformanceEventTiming")}} + - : Measures latency of events and first input delay (FID). +- {{domxref("PerformanceLongTaskTiming")}} + - : Detects long tasks that occupy rendering and block other tasks from being executed. +- {{domxref("PerformanceMark")}} + - : Custom marker for your own entry on the performance timeline. +- {{domxref("PerformanceMeasure")}} + - : Custom time measurement between two performance entries. +- {{domxref("PerformanceNavigationTiming")}} + - : Measures document navigation events, like how much time it takes to load a document. +- {{domxref("PerformanceObserver")}} + - : Listens for new performance entries as they are recorded in the performance timeline. +- {{domxref("PerformanceObserverEntryList")}} + - : List of entries that were observed in a performance observer. +- {{domxref("PerformancePaintTiming")}} + - : Measures render operations during web page construction. +- {{domxref("PerformanceResourceTiming")}} + - : Measures 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. +- {{domxref("PerformanceServerTiming")}} + - : Surfaces server metrics that are sent with the response in the {{HTTPHeader("Server-Timing")}} HTTP header. +- {{domxref("TaskAttributionTiming")}} + - : Identifies the type of task and the container that is responsible for the long task. + +## Guides and tutorials + +- [Using the Performance API](/en-US/docs/Web/API/Performance_API/Using_the_Performance_API) +- [Using Performance Timeline](/en-US/docs/Web/API/Performance_Timeline/Using_Performance_Timeline) +- [Using the User Timing API](/en-US/docs/Web/API/User_Timing_API/Using_the_User_Timing_API) +- [Using Navigation Timing](/en-US/docs/Web/API/Navigation_timing_API/Using_Navigation_Timing) +- [Using the Resource Timing API](/en-US/docs/Web/API/Resource_Timing_API/Using_the_Resource_Timing_API) ## Specifications {{Specifications}} -## Implementation status - -As shown in the {{domxref("Performance")}} interface's [Browser Compatibility](/en-US/docs/Web/API/Performance#browser_compatibility) table, most of these interfaces are broadly implemented by desktop browsers. - -To test your browser's support for the {{domxref("Performance")}} interface, run the [`perf-api-support`](https://mdn.github.io/dom-examples/performance-apis/perf-api-support.html) application. - ## See also -- [A Primer for Web Performance Timing APIs](https://w3c.github.io/perf-timing-primer/) +- [Web performance](/en-US/docs/Web/Performance) +- [Learn: Web performance](/en-US/docs/Learn/Performance)