Event Timing API

Draft Community Group Report,

This version:
https://wicg.github.io/event-timing
Test Suite:
https://github.com/web-platform-tests/wpt/tree/master/event-timing
Issue Tracking:
GitHub
Editors:
(Google)
(Google)

Abstract

This document defines an API that provides web page authors with insights into the latency of certain events triggered by user interactions.

Status of this document

This specification was published by the Web Platform Incubator Community Group. It is not a W3C Standard nor is it on the W3C Standards Track. Please note that under the W3C Community Contributor License Agreement (CLA) there is a limited opt-out and other conditions apply. Learn more about W3C Community and Business Groups.

1. Introduction

This section is non-normative.

When a user engages with a website, they expect their actions to cause changes to the website quickly. In fact, research suggests that any user input that is not handled within 100ms is considered slow. Therefore, it is important to surface input events that could not achieve those guidelines.

A common way to monitor event latency consists of registering an event listener. The timestamp at which the event was created can be obtained via the event’s timeStamp. In addition, performance.now() could be called both at the beginning and at the end of the event handler logic. By subtracting the hardware timestamp from the timestamp obtained at the beginning of the event handler, the developer can compute the input delay: the time it takes for an input to start being processed. By subtracting the timestamp obtained at the beginning of the event handler from the timestamp obtained at the end of the event handler, the developer can compute the amount of synchronous work performed in the event handler.

This approach has several fundamental flaws. First, requiring event listeners precludes measuring event latency very early in the page load because listeners will likely not be registered yet at that point in time. Second, developers that are only interested in the input delay might be forced to add new listeners to events that originally did not have one. This adds unnecessary performance overhead to the event latency calculation. And lastly, it would be very hard to measure asynchronous work caused by the event via this approach.

This specification provides an alternative to event latency monitoring that solves some of these problems. Since the user agent computes the timestamps, there is no need for event listeners in order to measure performance. This means that even events that occur very early in the page load can be captured. This also enables visibility into slow events without requiring analytics providers to attempt to patch and subscribe to every conceivable event. In addition to this, the website’s performance will not suffer from the overhead of unneeded event listeners. Finally, this specification allows developers to obtain detailed information about the timing of the rendering that occurs right after the event has been processed. This can be useful to measure the overhead of website modifications that are triggered by events.

The very first user interaction has a disproportionate impact on user experience, and is often disproportionately slow. It’s slow because it’s often blocked on JavaScript execution that is not properly split into chunks during page load. The latency of the website’s response to the first user interaction can be considered a key responsiveness and loading metric. To that effect, this API surfaces all the timing information about this interaction, even when this interaction is not handled slowly. This allows developers to measure percentiles and improvements without having to register event handlers.

1.1. Events exposed

The Event Timing API exposes timing information for certain events. Certain types of events are considered, and timing information is exposed when the time difference between user input and paint operations that follow input processing exceeds a certain threshold.

Given an event, to determine if it should be considered for Event Timing, run the following steps:
  1. If event’s isTrusted attribute value is set to false, return false.

  2. If event’s type is one of the following: auxclick, click, dblclick, mousedown, mouseenter, mouseleave, mousemove, mouseout, mouseover, mouseup, pointerover, pointerenter, pointerdown, pointermove, pointerup, pointercancel, pointerout, pointerleave, gotpointercapture, lostpointercapture touchstart, touchend, touchmove, touchcancel, keydown, keyup, wheel, beforeinput, input, compositionstart, compositionupdate, compositionend, return true.

  3. Return false.

The Event Timing API also exposes timing information about the first user interaction among the following:

1.2. Usage example

    const observer = new PerformanceObserver(function(list) {
        const perfEntries = list.getEntries().forEach(entry => {
            const inputDelay = entry.processingStart - entry.startTime;
            // Report the input delay when the processing start was provided.
            // Also report the full input duration via entry.duration.
        });
    });
    // Register observer for event.
    observer.observe({entryTypes: ["event"]});
    ...
    // Later on, we can also directly query the first input information.
    const firstArray = performance.getEntriesByType('first-input');
    if (firstArray.length !== 0) {
        const firstInput = firstArray[0];
        // Process the first input event and report back...
    }
}

The following are sample use cases that could be achieved by using this API:

2. Event Timing

Event Timing adds the following interfaces:

2.1. PerformanceEventTiming interface

[Exposed=Window]
interface PerformanceEventTiming : PerformanceEntry {
    readonly attribute DOMHighResTimeStamp processingStart;
    readonly attribute DOMHighResTimeStamp processingEnd;
    readonly attribute boolean cancelable;
    [Default] object toJSON();
};

Note: A user agent implementing the Event Timing API would need to include "first-input" and "event" in supportedEntryTypes for Window contexts. This allows developers to detect support for event timing.

This remainder of this section is non-normative. The values of the attributes of PerformanceEventTiming are set in the processing model in § 3 Processing model. This section provides an informative summary of how they will be set.

Each PerformanceEventTiming object reports timing information about an associated Event.

PerformanceEventTiming extends the following attributes of the PerformanceEntry interface:

name
The name attribute’s getter provides the associated event’s type.
entryType
The entryType attribute’s getter returns "event" (for long events) or "first-input" (for the first user interaction).
startTime
The startTime attribute’s getter returns the associated event’s timeStamp.
duration
The duration attribute’s getter returns the difference between the time of the first update the rendering step occurring after associated event has been dispatched and the startTime, rounded to the nearest 8ms.

PerformanceEventTiming has the following additional attributes:

processingStart
The processingStart attribute’s getter returns a timestamp captured at the beginning of the event dispatch algorithm. This is when event handlers are about to be executed.
processingEnd
The processingEnd attribute’s getter returns a timestamp captured at the end of the event dispatch algorithm. This is when event handlers have finished executing. It’s equal to processingStart when there are no such event handlers.
cancelable
The cancelable attribute’s getter returns the associated event’s cancelable attribute value.

2.2. EventCounts interface

[Exposed=Window]
interface EventCounts {
    readonly maplike<DOMString, unsigned long long>;
};

The EventCounts object is a map where the keys are event types and the values are the number of events that have been dispatched that are of that type. Only events whose type is supported by PerformanceEventTiming entries (see section § 1.1 Events exposed) are counted via this map.

2.3. Extensions to the Performance interface

[Exposed=Window]
partial interface Performance {
    [SameObject] readonly attribute EventCounts eventCounts;
};

The eventCounts attribute’s getter returns a map with entries of the form typenumEvents. This means that there have been numEvents dispatched such that their type attribute value is equal to type.

3. Processing model

3.1. Modifications to the DOM specification

This section will be removed once the DOM specification has been modified.

We modify the event dispatch algorithm as follows.

Right after step 1, we add the following step:

Right before the returning step of that algorithm, add the following step:

Note: If a user agent skips the event dispatch algorithm, it can still choose to include an entry for that Event. In this case, it will estimate the value of processingStart and set the processingEnd to the same value.

3.2. Modifications to the HTML specification

This section will be removed once the HTML specification has been modified.

Each Window has pending event entries, a list that stores PerformanceEventTiming objects, which will initially be empty. Each Window also has pending pointer down, a pointer to a PerformanceEventTiming entry which is initially null. Finally, each Window has has dispatched input event, a boolean which is initially set to false.

In the update the rendering step of the event loop processing model, add a step right after the step that calls mark paint timing:
  1. For each fully active Document in docs, invoke the algorithm to dispatch pending Event Timing entries for that Document.

3.3. Initialize event timing

When asked to initialize event timing, with event and processingStart as inputs, run the following steps:
  1. If the algorithm to determine if event should be considered for Event Timing returns false, then return null.

  2. Let timingEntry be a new PerformanceEventTiming object.

  3. Set timingEntry’s name to event’s type attribute value.

  4. Set timingEntry’s entryType to "event".

  5. Set timingEntry’s startTime as follows:

    1. If event’s type attribute value is equal to "pointermove", set timingEntry’s startTime to the timeStamp attribute value of the first entry of the list returned by the getCoalescedEvents() algorithm applied to event.

    2. Otherwise, set timingEntry’s startTime to event’s timeStamp attribute value.

  6. Set timingEntry’s processingStart to processingStart.

  7. Set timingEntry’s cancelable to event’s cancelable attribute value.

  8. Return timingEntry.

3.4. Finalize event timing

When asked to to finalize event timing, with timingEntry, target, and processingEnd as inputs, run the following steps:
  1. If timingEntry is null, return.

  2. Let relevantGlobal be target’s relevant global object.

  3. If relevantGlobal does not implement Window, return.

  4. Set timingEntry’s processingEnd to processingEnd.

  5. Append timingEntry to relevantGlobal’s pending event entries.

3.5. Dispatch pending Event Timing entries

When asked to dispatch pending Event Timing entries for a Document doc, run the following steps:
  1. Let window be doc’s relevant global object.

  2. Let renderingTimestamp be the current high resolution time.

  3. For each timingEntry in window’s pending event entries:

    1. Let start be timingEntry’s startTime attribute value.

    2. Set timingEntry’s duration by running the following steps:

      1. Let difference be renderingTimestamp - start.

      2. Set timingEntry’s duration to the result of rounding difference to the nearest multiple of 8.

    3. Let name be timingEntry’s name attribute value.

    4. Perform the following steps to update the event counts:

      1. Let performance be window’s performance attribute value.

      2. If performance’s eventCounts attribute value does not contain a map entry whose key is name, then:

        1. Let mapEntry be a new map entry with key equal to name and value equal to 1.

        2. Add mapEntry to performance’s eventCounts attribute value.

      3. Otherwise, increase the map entry’s value by 1.

    5. If timingEntry’s duration attribute value is greater than or equal to 104, then queue timingEntry.

    6. If window’s has dispatched input event is false, run the following steps:

      1. If name is "pointerdown", run the following steps:

        1. Set window’s pending pointer down to a copy of timingEntry.

        2. Set the entryType of window’s pending pointer down to "first-input".

      2. Otherwise, run the following steps:

        1. If name is "pointerup" AND if window’s pending pointer down is not null, then:

          1. Set window’s has dispatched input event to true.

          2. Queue window’s pending pointer down.

        2. Otherwise, if name is one of "click", "keydown" or "mousedown", then:

          1. Set window’s has dispatched input event to true.

          2. Let newFirstInputDelayEntry be a copy of timingEntry.

          3. Set newFirstInputDelayEntry’s entryType to "first-input".

          4. Queue the entry newFirstInputDelayEntry.

4. Security & privacy considerations

We would not like to introduce more high resolution timers to the web platform due to the security concerns entailed by such timers. Event handler timestamps have the same accuracy as performance.now(). Since processingStart and processingEnd could be computed without using this API, exposing these attributes does not produce new attack surfaces. Thus, duration is the only one which requires further consideration.

The duration has an 8 millisecond granularity (it is computed as such by performing rounding). Thus, a high resolution timer cannot be produced from this timestamps. However, it does introduce new information that is not readily available to web developers: the time pixels draw after an event has been processed. We do not find security or privacy concerns on exposing the timestamp, especially given its granularity. In an effort to expose the minimal amount of new information that is useful, we decided to pick 8 milliseconds as the granularity. This allows relatively precise timing even for 120Hz displays.

The choice of 104ms as the cutoff value for the duration is just the first multiple of 8 greater than 100ms. An event whose rounded duration is greater than or equal to 104ms will have its pre-rounded duration greater than or equal to 100ms. Such events are not handled in accordance with the RAIL performance model, which suggests applications respond within 100ms to user input.

Conformance

Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this document are to be interpreted as described in RFC 2119. However, for readability, these words do not appear in all uppercase letters in this specification.

All of the text of this specification is normative except sections explicitly marked as non-normative, examples, and notes. [RFC2119]

Examples in this specification are introduced with the words “for example” or are set apart from the normative text with class="example", like this:

This is an example of an informative example.

Informative notes begin with the word “Note” and are set apart from the normative text with class="note", like this:

Note, this is an informative note.

Index

Terms defined by this specification

Terms defined by reference

References

Normative References

[DOM]
Anne van Kesteren. DOM Standard. Living Standard. URL: https://dom.spec.whatwg.org/
[HR-TIME-2]
Ilya Grigorik; James Simonsen; Jatinder Mann. High Resolution Time Level 2. 26 June 2019. CR. URL: https://www.w3.org/TR/hr-time-2/
[HTML]
Anne van Kesteren; et al. HTML Standard. Living Standard. URL: https://html.spec.whatwg.org/multipage/
[PAINT-TIMING]
Shubhie Panicker. Paint Timing 1. 7 September 2017. WD. URL: https://www.w3.org/TR/paint-timing/
[PERFORMANCE-TIMELINE-2]
Ilya Grigorik. Performance Timeline Level 2. 17 September 2019. WD. URL: https://www.w3.org/TR/performance-timeline-2/
[POINTEREVENTS]
Jacob Rossi; Matt Brubeck. Pointer Events. 4 April 2019. REC. URL: https://www.w3.org/TR/pointerevents/
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
[TOUCH-EVENTS]
Doug Schepers; et al. Touch Events. 10 October 2013. REC. URL: https://www.w3.org/TR/touch-events/
[UIEVENTS]
Gary Kacmarcik; Travis Leithead; Doug Schepers. UI Events. 30 May 2019. WD. URL: https://www.w3.org/TR/uievents/
[WebIDL]
Boris Zbarsky. Web IDL. 15 December 2016. ED. URL: https://heycam.github.io/webidl/

IDL Index

[Exposed=Window]
interface PerformanceEventTiming : PerformanceEntry {
    readonly attribute DOMHighResTimeStamp processingStart;
    readonly attribute DOMHighResTimeStamp processingEnd;
    readonly attribute boolean cancelable;
    [Default] object toJSON();
};

[Exposed=Window]
interface EventCounts {
    readonly maplike<DOMString, unsigned long long>;
};

[Exposed=Window]
partial interface Performance {
    [SameObject] readonly attribute EventCounts eventCounts;
};