Movatterモバイル変換

This specification defines an interface to help web developers measure the performance of their applications by giving them access to high precision timestamps.

This User Timing specification is intended to supersede [[USER-TIMING-2]] and includes:

• Ability to execute marks and measures across arbitrary timestamps.
• Support for reporting arbitrary metadata along with marks and measures.

Introduction

Web developers need the ability to assess and understand the performance characteristics of their applications. While JavaScript [[ECMA-262]] provides a mechanism to measure application latency (retrieving the current timestamp from theDate.now() method), the precision of this timestamp varies between user agents.

This document defines thePerformanceMark andPerformanceMeasure interfaces, and extensions to thePerformance interface, which expose a high precision, monotonically increasing timestamp so that developers can better measure the performance characteristics of their applications.

        async function run() {          performance.mark("startTask1");          await doTask1(); // Some developer code          performance.mark("endTask1");          performance.mark("startTask2");          await doTask2(); // Some developer code          performance.mark("endTask2");          // Log them out          const entries = performance.getEntriesByType("mark");          for (const entry of entries) {            console.table(entry.toJSON());          }        }        run();

        element.addEventListener("click", e => {          const component = getComponent(element);          fetch(component.url).then(() => {            element.textContent = "Updated";            const updateMark = performance.mark("update_component", {              detail: {component: component.name},            });            performance.measure("click_to_update_component", {              detail: {component: component.name},              start: e.timeStamp,              end: updateMark.startTime,            });          });        });

Some conformance requirements are phrased as requirements on attributes, methods or objects. Such requirements are to be interpreted as requirements on user agents.

The IDL fragments in this specification MUST be interpreted as required for conforming IDL fragments, as described in the Web IDL specification. [[WEBIDL]]

User Timing

        dictionary PerformanceMarkOptions {            any detail;            DOMHighResTimeStamp startTime;        };        dictionary PerformanceMeasureOptions {            any detail;            (DOMString or DOMHighResTimeStamp) start;            DOMHighResTimeStamp duration;            (DOMString or DOMHighResTimeStamp) end;        };        partial interface Performance {            PerformanceMark mark(DOMString markName, optional PerformanceMarkOptions markOptions = {});            undefined clearMarks(optional DOMString markName);            PerformanceMeasure measure(DOMString measureName, optional (DOMString or PerformanceMeasureOptions) startOrMeasureOptions = {}, optional DOMString endMark);            undefined clearMeasures(optional DOMString measureName);        };

        [Exposed=(Window,Worker)]        interface PerformanceMark : PerformanceEntry {          constructor(DOMString markName, optional PerformanceMarkOptions markOptions = {});          readonly attribute any detail;        };

        [Exposed=(Window,Worker)]        interface PerformanceMeasure : PerformanceEntry {          readonly attribute any detail;        };

Processing

A user agent implementing the User Timing API would need to include"mark" and"measure" in supportedEntryTypes. This allows developers to detect support for User Timing.

Recommended mark names

Developers are encouraged to use the following recommended mark names to mark common timings. Theuser agent does not validate that the usage of these names is appropriate or consistent with its description.

Adding such recommended mark names can help performance tools tailor guidance to a site. These mark names can also help real user monitoring providers and user agents collect web developer signals regarding their application's performance at scale, and surface this information to developers without requiring any site-specific work.

"mark_fully_loaded"

The time when the page is considered fully loaded as marked by the developer in their application.

In this example, the page asynchonously initializes a chat widget, a searchbox, and a newsfeed upon loading. When finished, the "mark_fully_loaded" mark name enables lab tools and analytics providers to automatically show the timing.

                window.addEventListener("load", (event) => {                  Promise.all([                    loadChatWidget(),                    initializeSearchAutocomplete(),                    initializeNewsfeed()]).then(() => {                      performance.mark('mark_fully_loaded');                  });                });

"mark_fully_visible"

The time when the page is considered fully visible to an end-user as marked by the developer in their application.

"mark_interactive"

The time when the page is considered interactive to an end-user as marked by the developer in their application.

"mark_feature_usage"

Mark the usage of a feature which may impact performance so that tooling and analytics can take it into account. Thedetail metadata can contain any useful information about the feature, including:

feature

The name of the feature used.

framework

If applicable, the underlying framework the feature is intended for, such as a JavaScript framework, content management system, or e-commerce platform.

In this example, the ImageOptimizationComponent for FancyJavaScriptFramework is used to size images for optimal performance. The code notes this feature's usage so that lab tools and analytics can measure whether it helped improve performance.

            performance.mark('mark_feature_usage', {              'detail': {                'feature': 'ImageOptimizationComponent',                'framework': 'FancyJavaScriptFramework'              }            })

Privacy and Security

The interfaces defined in this specification expose potentially sensitive timing information on specific JavaScript activity of a page. Please refer to [[HR-TIME-2]] for privacy and security considerations of exposing high-resolution timing information.

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 the same page, regardless of the origin of either scripts, the interfaces defined by this specification do not place any restrictions on recording or retrieval of recorded timing information - i.e. a user timing mark or measure recorded by any script included on the page can be read by any other script running on the same page, regardless of origin.

Acknowledgments

Thanks to James Simonsen, Jason Weber, Nic Jansma, Philippe Le Hegaret, Karen Anderson, Steve Souders, Sigbjorn Vik, Todd Reifsteck, and Tony Gentilcore for their contributions to this work.