Event Timing API

1. Introduction

1.1. Overview

1.2. Interactions

1.3. First Input

1.4. Events exposed

The Event Timing API exposes timing information only for certain events.

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.5. When events are measured

1.6. Usage example

const observer = new PerformanceObserver(function(list, obs) {
    for (let entry of list.getEntries()) {
        // Input Delay
        const inputDelay = entry.processingStart - entry.startTime;
        // Processing duration
        const processingDuration = entry.processingEnd - entry.processingStart;
        // Presentation Delay (approximate)
        const presentationDelay = Math.max(0, entry.startTime + entry.duration - entry.processingEnd);

        // Obtain some information about the target of this event, such as the id.
        const targetId = entry.target ? entry.target.id : 'unknown-target';

        console.log(entry.entryType, entry.name, entry.duration, { inputDelay, processingDuration, presentationDelay });
    }
});
observer.observe({ type: 'first-input', buffered: true });
observer.observe({ type: 'event', buffered: true, durationThreshold: 40 });

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 => {
    for (let entry of list.getEntries()) {
        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();
};

A PerformanceEventTiming object reports timing information about one associated Event.

Each PerformanceEventTiming object has these associated concepts, all of which are initially set to null:

• An eventTarget containing the associated Node.

The target attribute’s getter must perform the following steps:

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

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

• 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.4 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

Note: 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. This allows the user agent to choose to eagerly assign a user interaction value (i.e. at pointerdown) and then discard it (i.e. after pointercancel), rather than to lazily compute it.

A user agent may choose to increase it by a small random integer every time, or choose a constant. A user agent must not use a shared global user interaction values for all Windows, because this could introduce cross-origin leaks.

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

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.