Event Timing API

1. Introduction

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.

Note: mousemove, pointermove, pointerrawupdate, touchmove, wheel, and drag are excluded because these are "continuous" events. The current API does not have enough guidance on how to count and aggregate these events to obtain meaningful performance metrics based on entries. Therefore, these event types are not exposed.

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"]});
    ...
    // We can also directly query the first input information.
    new PerformanceObserver(function(list, obs) {
        const firstInput = list.getEntries()[0];

        // Measure the delay to begin processing the first input event.
        const firstInputDelay = firstInput.processingStart - firstInput.startTime;
        // Measure the duration of processing the first input event.
        // Only use when the important event handling work is done synchronously in the handlers.
        const firstInputDuration = firstInput.duration;
        // Obtain some information about the target of this event, such as the id.
        const targetId = firstInput.target ? firstInput.target.id : 'unknown-target';
        // Process the first input delay and perhaps its duration...

        // Disconnect this observer since callback is only triggered once.
        obs.disconnect();
    }).observe({type: 'first-input', buffered: true});

}

The following example computes a dictionary mapping interactionId to the maximum duration of any of its events. This dictionary can later be aggregated and reported to analytics.

let maxDurations = {};
new PerformanceObserver(list => {
    list.getEntries().forEach(entry => {
        if (entry.interactionId > 0) {
            let id = entry.interactionId;
            if (!maxDurations[id]) {
                maxDurations[id] = entry.duration;
            } else {
                maxDurations[id] = Math.max(maxDurations[id], entry.duration);
            }
        }
    })
}).observe({type: 'event', buffered: true, durationThreshold: 16});

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

• Gather first input delay data on a website and track its performance over time.

• Clicking a button changes the sorting order on a table. Measure how long it takes from the click until we display reordered content.

• A user drags a slider to control volume. Measure the latency to drag the slider.

• Hovering a menu item triggers a flyout menu. Measure the latency for the flyout to appear.

• Measure the 75’th percentile of the latency of the first user click (whenever click happens to be the first user interaction).

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;
    readonly attribute Node? target;
    readonly attribute unsigned long long interactionId;
    [Default] object toJSON();
};

Each PerformanceEventTiming object has an associated eventTarget, which is initially set to null.

The target attribute’s getter returns the result of the get an element algorithm, passing this’s eventTarget and null as inputs.

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.

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;
    readonly attribute unsigned long long interactionCount;
};

The eventCounts attribute’s getter returns this’s relevant global object’s eventCounts.

The interactionCount attribute’s getter returns this’s relevant global object’s interactionCount.

3. Processing model

3.1. Modifications to the DOM specification

This section will be removed once [DOM] has been modified.

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 [HTML] has been modified.

Each Window has the following associated concepts:

• entries to be queued, a list that stores PerformanceEventTiming objects, which will initially be empty.

• pending first pointer down, a pointer to a PerformanceEventTiming entry which is initially null.

• has dispatched input event, a boolean which is initially set to false.

• user interaction value, an integer which is initially set to a random integer between 100 and 10000.

  Note: the user interaction value is set to a random integer instead of 0 so that developers do not rely on it to count the number of interactions in the page. By starting at a random value, developers are less likely to use it as the source of truth for the number of interactions that have occurred in the page.

• pending key downs, a map of integers to PerformanceEventTimings which is initially empty.

• pointer interaction value map, a map of integers which is initially empty.

• pointer is drag set, a set of integers which is initially empty.

• pending pointer downs, a map of integers to PerformanceEventTimings which is initially empty.

• eventCounts, a map with entries of the form type → numEvents. This means that there have been numEvents dispatched such that their type attribute value is equal to type. Upon construction of a Performance object whose relevant global object is a Window, its eventCounts must be initialized to a map containing 0s for all event types that the user agent supports from the list described in § 1.1 Events exposed.

• interactionCount, an integer which counts the total number of distinct user interactions, for which there was a unique interactionId computed via computing interactionId.

3.3. Modifications to the Performance Timeline specification

This section will be removed once [PERFORMANCE-TIMELINE-2] had been modified.

The PerformanceObserverInit dictionary is augmented:

partial dictionary PerformanceObserverInit {
    DOMHighResTimeStamp durationThreshold;
};

3.4. Should add PerformanceEventTiming

Note: The following algorithm is used in the [PERFORMANCE-TIMELINE-2] specification to determine when a PerformanceEventTiming entry needs to be added to the buffer of a PerformanceObserver or to the performance timeline, as described in the registry.

3.5. Increasing interaction count

3.6. Computing interactionId

Note: the algorithm attempts to assign events to the corresponding interactiond IDs. For keyboard events, a keydown triggers a new interaction ID, whereas a keyup has to match its ID with a previous keydown. For pointer events, when we get a pointerdown we have to wait until pointercancel or pointerup occur to know its interactionId. We try to match click with a previous interaction ID from a pointerdown. If pointercancel or pointerup happens, we’ll be ready to set the interactionId for the stored entry corresponding to pointerdown. If it is pointercancel, this means we do not want to assign a new interaction ID to the pointerdown. If it is pointerup, we compute a new interaction ID and set it on both the pointerdown and the pointerup (and later, the click if it occurs).

The user interaction value is increased by a small number chosen by the user agent instead of 1 to discourage developers from considering it as a counter of the number of user interactions that have occurred in the web application. A user agent may choose to increase it by a small random integer every time. A user agent must not pick a global random integer and increase the user interaction values of all Windows by that amount because this could introduce cross origin leaks.

3.7. Initialize event timing

3.8. Finalize event timing

3.9. Dispatch pending Event Timing entries

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 default 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 within 100ms and will likely negatively impact user experience.

The choice of 16ms as the minimum value allowed for durationThreshold is because it enables the typical use-case of making sure that the response is smooth. In 120Hz displays, a response that skips more than a single frame will be at least 16ms, so the entry corresponding to this user input will be surfaced in the API under the minimum value.