diff --git a/files/en-us/_redirects.txt b/files/en-us/_redirects.txt index 761aee2e0058d0a..cf8ded6be65fc70 100644 --- a/files/en-us/_redirects.txt +++ b/files/en-us/_redirects.txt @@ -8788,6 +8788,7 @@ /en-US/docs/Web/API/LockedFile/truncate /en-US/docs/Web/API/IDBFileHandle/truncate /en-US/docs/Web/API/LockedFile/write /en-US/docs/Web/API/IDBFileHandle/write /en-US/docs/Web/API/LongRange /en-US/docs/Web/API/MediaTrackConstraints +/en-US/docs/Web/API/Long_Tasks_API /en-US/docs/Web/API/PerformanceLongTaskTiming /en-US/docs/Web/API/MIDIAccess/onstatechange /en-US/docs/Web/API/MIDIAccess/statechange_event /en-US/docs/Web/API/MIDIInput/onmidimessage /en-US/docs/Web/API/MIDIInput/midimessage_event /en-US/docs/Web/API/MIDIPort/onstatechange /en-US/docs/Web/API/MIDIPort/statechange_event diff --git a/files/en-us/_wikihistory.json b/files/en-us/_wikihistory.json index d984fff24496509..57ff1002a1afb9e 100644 --- a/files/en-us/_wikihistory.json +++ b/files/en-us/_wikihistory.json @@ -45413,20 +45413,6 @@ "modified": "2020-10-15T22:07:42.503Z", "contributors": ["sideshowbarker", "Wuzzel", "jpmedley"] }, - "Web/API/Long_Tasks_API": { - "modified": "2020-10-15T21:54:38.944Z", - "contributors": [ - "bradley27783", - "Wind1808", - "wbamberg", - "Sheppy", - "estelle", - "greglockwood", - "fscholz", - "tocretpa", - "jpmedley" - ] - }, "Web/API/MIDIAccess": { "modified": "2020-10-15T21:35:25.882Z", "contributors": [ diff --git a/files/en-us/glossary/first_input_delay/index.md b/files/en-us/glossary/first_input_delay/index.md index f9fa6c302eaea39..3109b4cf0533560 100644 --- a/files/en-us/glossary/first_input_delay/index.md +++ b/files/en-us/glossary/first_input_delay/index.md @@ -10,7 +10,7 @@ tags: It is the length of time, in milliseconds, between the first user interaction on a web page and the browser's response to that interaction. Scrolling and zooming are not included in this metric. -The time between when content is painted to the page and when all the functionality becomes responsive to human interaction often varies based on the size and complexity of the JavaScript needing to be downloaded, parsed, and executed on the main thread, and on the device speed or lack thereof (think low end mobile devices). The longer the delay, the worse the user experience. Reducing site initialization time and eliminating [long tasks](/en-US/docs/Web/API/Long_Tasks_API) can help eliminate first input delays. +The time between when content is painted to the page and when all the functionality becomes responsive to human interaction often varies based on the size and complexity of the JavaScript needing to be downloaded, parsed, and executed on the main thread, and on the device speed or lack thereof (think low end mobile devices). The longer the delay, the worse the user experience. Reducing site initialization time and eliminating [long tasks](/en-US/docs/Web/API/PerformanceLongTaskTiming) can help eliminate first input delays. ## See also diff --git a/files/en-us/glossary/long_task/index.md b/files/en-us/glossary/long_task/index.md index 92078f5ff5b3ccf..fd4ead8cfbcaae4 100644 --- a/files/en-us/glossary/long_task/index.md +++ b/files/en-us/glossary/long_task/index.md @@ -13,4 +13,4 @@ It is an uninterrupted period where the [main UI thread](/en-US/docs/Glossary/Ma ## See also -- [Long task API](/en-US/docs/Web/API/Long_Tasks_API) +- [Long task API](/en-US/docs/Web/API/PerformanceLongTaskTiming) diff --git a/files/en-us/glossary/time_to_interactive/index.md b/files/en-us/glossary/time_to_interactive/index.md index 204b401500a8bcc..acaba7978ce6cfc 100644 --- a/files/en-us/glossary/time_to_interactive/index.md +++ b/files/en-us/glossary/time_to_interactive/index.md @@ -7,13 +7,13 @@ tags: - Web Performance --- -**Time to Interactive** (TTI) is a non-standardized web performance 'progress' metric defined as the point in time when the last [Long Task](/en-US/docs/Web/API/Long_Tasks_API) finished and was followed by 5 seconds of network and main thread inactivity. +**Time to Interactive** (TTI) is a non-standardized web performance 'progress' metric defined as the point in time when the last [Long Task](/en-US/docs/Web/API/PerformanceLongTaskTiming) finished and was followed by 5 seconds of network and main thread inactivity. TTI, proposed by the Web Incubator Community Group in 2018, is intended to provide a metric that describes when a page or application contains useful content and the main thread is idle and free to respond to user interactions, including having event handlers registered. #### Caveat -TTI is derived by leveraging information from the {{domxref("Long Tasks API")}}. Although available in some performance monitoring tools, TTI is not a part of any official web specification at the time of writing. +TTI is derived by leveraging information from the [Long Task API](/en-US/docs/Web/API/PerformanceLongTaskTiming). Although available in some performance monitoring tools, TTI is not a part of any official web specification at the time of writing. ## See also diff --git a/files/en-us/web/api/long_tasks_api/index.md b/files/en-us/web/api/long_tasks_api/index.md deleted file mode 100644 index 0c40b864d7a609a..000000000000000 --- a/files/en-us/web/api/long_tasks_api/index.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -title: Long Tasks API -slug: Web/API/Long_Tasks_API -page-type: web-api-overview -tags: - - API - - Experimental - - Landing - - Long Tasks API - - NeedsContent - - Overview - - Performance - - PerformanceLongTaskTiming - - Reference - - TaskAttributionTiming - - Web Performance -browser-compat: - - api.PerformanceLongTaskTiming - - api.TaskAttributionTiming ---- - -{{DefaultAPISidebar("Performance API")}} - -## Motivation - -The experimental Long Tasks API gives us visibility into tasks that take 50 milliseconds or more. -The 50 ms threshold comes from the [RAIL Model](https://web.dev/rail/), in particular the ["Response: process events in under 50 ms"](https://web.dev/rail/#response:-process-events-in-under-50ms) section. - -Tasks that block the main thread for 50 ms or more cause, among other issues: - -- Delayed "{{glossary("Time to interactive")}}". -- High/variable input latency. -- High/variable event handling latency. -- Janky animations and scrolling. - -## Concepts - -Some key terms or ideas that are utilized by the Long Tasks API. - -### Long task - -Any uninterrupted period where the main UI thread is busy for 50 ms or longer. Common examples include: - -- Long running event handlers. -- Expensive reflows and other re-renders. -- Work the browser does between different turns of the event loop that exceeds 50 ms. - -### Culprit browsing context container - -The "culprit browsing context container", or "the container" for short, is the top level page, iframe, embed or object that the task occurred within. - -### Attributions - -A list of containers that the task occurred within. For tasks that don't occur within the top level page, the `containerId`, `containerName` and `containerSrc` fields may provide information as to the source of the task. - -## Usage - -```js -const observer = new PerformanceObserver((list) => { - const perfEntries = list.getEntries(); - perfEntries.forEach((entry) => { - // Process long task notifications: - // report back for analytics and monitoring - }); -}); - -// Register observer for long task notifications -observer.observe({entryTypes: ["longtask"]}); -// Long script execution after this will result in queueing -// and receiving "longtask" entries in the observer. -``` - -## Interfaces - -- {{domxref('PerformanceLongTaskTiming')}} - - : Reports instances of long tasks. -- {{domxref("TaskAttributionTiming")}} - - : Returns information about the work involved in a long task and its associate frame context. - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- [GitHub repository](https://github.com/w3c/longtasks) contains documentation and some code samples. -- [PerfPlanet article](https://calendar.perfplanet.com/2017/tracking-cpu-with-long-tasks-api/) on Long Tasks API from 20th December 2017. diff --git a/files/en-us/web/api/performancelongtasktiming/attribution/index.md b/files/en-us/web/api/performancelongtasktiming/attribution/index.md index 9263b865f081476..a7015d92e522696 100644 --- a/files/en-us/web/api/performancelongtasktiming/attribution/index.md +++ b/files/en-us/web/api/performancelongtasktiming/attribution/index.md @@ -7,13 +7,27 @@ browser-compat: api.PerformanceLongTaskTiming.attribution {{SeeCompatTable}}{{APIRef("Performance API")}} -The **`attribution`** readonly property of the -{{domxref("PerformanceLongTaskTiming")}} interface returns a sequence of -{{domxref('TaskAttributionTiming')}} instances. +The **`attribution`** readonly property of the {{domxref("PerformanceLongTaskTiming")}} interface returns an array of {{domxref('TaskAttributionTiming')}} objects. ## Value -A sequence of {{domxref('TaskAttributionTiming')}} instances. +An {{jsxref("Array")}} of {{domxref('TaskAttributionTiming')}} objects. + +## Examples + +### Logging attributions for long tasks + +```js +const observer = new PerformanceObserver((list) => { + list.getEntries().forEach((entry) => { + entry.attribution.forEach((attributionEntry) => { + console.log(attributionEntry); + }); + }); +}); + +observer.observe({ type: "longtask", buffered: true }); +``` ## Specifications @@ -22,3 +36,7 @@ A sequence of {{domxref('TaskAttributionTiming')}} instances. ## Browser compatibility {{Compat}} + +## See also + +- {{domxref('TaskAttributionTiming')}} diff --git a/files/en-us/web/api/performancelongtasktiming/index.md b/files/en-us/web/api/performancelongtasktiming/index.md index 8f3009bfc884ef4..8797d179172f837 100644 --- a/files/en-us/web/api/performancelongtasktiming/index.md +++ b/files/en-us/web/api/performancelongtasktiming/index.md @@ -14,12 +14,57 @@ browser-compat: api.PerformanceLongTaskTiming {{SeeCompatTable}}{{APIRef("Performance API")}} -The **`PerformanceLongTaskTiming`** interface of the [Long Tasks API](/en-US/docs/Web/API/Long_Tasks_API) reports instances of long tasks. +The **`PerformanceLongTaskTiming`** interface provides information about tasks that occupy the UI thread for 50 milliseconds or more. + +## Description + +Long tasks that block the main thread for 50ms or more cause, among other issues: + +- Delayed {{glossary("Time to interactive")}} (TTI). +- High/variable input latency. +- High/variable event handling latency. +- Janky animations and scrolling. + +A long task is any uninterrupted period where the main UI thread is busy for 50ms or longer. Common examples include: + +- Long-running event handlers. +- Expensive reflows and other re-renders. +- Work the browser does between different turns of the event loop that exceeds 50 ms. + +Long tasks refer to "culprit browsing context container", or "the container" for short, which is the top-level page, {{HTMLElement("iframe")}}, {{HTMLElement("embed")}} or {{HTMLElement("object")}} that the task occurred within. + +For tasks that don't occur within the top-level page and for figuring out which container is responsible for the long task, the {{domxref("TaskAttributionTiming")}} interface provides the `containerId`, `containerName` and `containerSrc` properties, which may provide more information about the source of the task. + +## Inheritance + +`PerformanceLongTaskTiming` inherits from {{domxref("PerformanceEntry")}}. {{InheritanceDiagram}} ## Instance properties +This interface extends the following {{domxref("PerformanceEntry")}} properties for event timing performance entry types by qualifying them as follows: + +- {{domxref("PerformanceEntry.duration")}} {{ReadOnlyInline}} {{Experimental_Inline}} + - : Returns a {{domxref("DOMHighResTimeStamp")}} representing the elapsed time between the start and end of the task, with a 1ms granularity. +- {{domxref("PerformanceEntry.entryType")}} {{ReadOnlyInline}} {{Experimental_Inline}} + - : Always returns `"longtask"` +- {{domxref("PerformanceEntry.name")}} {{ReadOnlyInline}} {{Experimental_Inline}} + - : Returns one of the following strings referring to the browsing context or frame that can be attributed to the long task: + - `"cross-origin-ancestor"` + - `"cross-origin-descendant"` + - `"cross-origin-unreachable"` + - `"multiple-contexts"` + - `"same-origin-ancestor"` + - `"same-origin-descendant"` + - `"same-origin"` + - `"self"` + - `"unknown"` +- {{domxref("PerformanceEntry.startTime")}} {{ReadOnlyInline}} {{Experimental_Inline}} + - : Returns a {{domxref("DOMHighResTimeStamp")}} representing the time when the task started. + +This interface also supports the following properties: + - {{domxref("PerformanceLongTaskTiming.attribution")}} {{ReadOnlyInline}} {{Experimental_Inline}} - : Returns a sequence of {{domxref('TaskAttributionTiming')}} instances. @@ -28,6 +73,22 @@ The **`PerformanceLongTaskTiming`** interface of the [Long Tasks API](/en-US/doc - {{domxref("PerformanceLongTaskTiming.toJSON()")}} {{Experimental_Inline}} - : Returns a JSON representation of the `PerformanceLongTaskTiming` object. +## Examples + +### Getting long tasks + +To get long task timing information, create a {{domxref("PerformanceObserver")}} instance and then call its [`observe()`](/en-US/docs/Web/API/PerformanceObserver/observe) method, passing in `"longtasks"` as the value of the [`type`](/en-US/docs/Web/API/PerformanceEntry/entryType) option. You also need to set `buffered` to `true` to get access to long tasks the user agent buffered while constructing the document. The `PerformanceObserver` object's callback will then be called with a list of `PerformanceLongTaskTiming` objects which you can analyze. + +```js +const observer = new PerformanceObserver((list) => { + list.getEntries().forEach((entry) => { + console.log(entry); + }); +}); + +observer.observe({ type: "longtask", buffered: true }); +``` + ## Specifications {{Specifications}} @@ -35,3 +96,7 @@ The **`PerformanceLongTaskTiming`** interface of the [Long Tasks API](/en-US/doc ## Browser compatibility {{Compat}} + +## See also + +- {{domxref("TaskAttributionTiming")}} diff --git a/files/en-us/web/api/taskattributiontiming/containerid/index.md b/files/en-us/web/api/taskattributiontiming/containerid/index.md index 87c037af888dc38..d619c9d5a09f0cf 100644 --- a/files/en-us/web/api/taskattributiontiming/containerid/index.md +++ b/files/en-us/web/api/taskattributiontiming/containerid/index.md @@ -15,14 +15,12 @@ browser-compat: api.TaskAttributionTiming.containerId {{APIRef("Performance API")}}{{SeeCompatTable}} -The **`containerId`** readonly property of the -{{domxref("TaskAttributionTiming")}} interface returns the container's `id` -attribute. A container is the iframe, embed or object etc. that is being implicated, on -the whole, for a long task. +The **`containerId`** readonly property of the {{domxref("TaskAttributionTiming")}} interface returns the container's `id` +attribute. A container is the iframe, embed or object etc. that is being implicated, on the whole, for a long task. ## Value -A string containing the containers `id` attribute. +A string containing the container's [`id`](/en-US/docs/Web/HTML/Global_attributes/id) HTML content attribute. ## Specifications diff --git a/files/en-us/web/api/taskattributiontiming/containername/index.md b/files/en-us/web/api/taskattributiontiming/containername/index.md index 17c2436f8b42889..37af10f7cdf1dc1 100644 --- a/files/en-us/web/api/taskattributiontiming/containername/index.md +++ b/files/en-us/web/api/taskattributiontiming/containername/index.md @@ -15,14 +15,12 @@ browser-compat: api.TaskAttributionTiming.containerName {{APIRef("Performance API")}}{{SeeCompatTable}} -The **`containerName`** readonly property of the -{{domxref("TaskAttributionTiming")}} interface returns the container's `name` -attribute. A container is the iframe, embed or object etc. that is being implicated, on -the whole, for a long task. +The **`containerName`** readonly property of the {{domxref("TaskAttributionTiming")}} interface returns the container's `name` +attribute. A container is the iframe, embed or object etc. that is being implicated, on the whole, for a long task. ## Value -A string containing the container's `name` attribute. +A string containing the container's `name` HTML content attribute (e.g. [`