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, 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.

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

• keydown

• mousedown

• pointerdown which is followed by pointerup

• click

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;
        // 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 are sample use cases that could be achieved by using this API:

• Gather FID data (see firstInputDelay on the example above) 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;
    [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.

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 type → numEvents. 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.

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.

3.3. Initialize event timing

3.4. Finalize event timing

3.5. 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 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.