Extensions to the Performance interface

This extends the Performance interface [[!HR-TIME-2]] and hosts performance related attributes and methods used to retrieve the performance metric data from the Performance Timeline.

      partial interface Performance {
        PerformanceEntryList getEntries ();
        PerformanceEntryList getEntriesByType (DOMString type);
        PerformanceEntryList getEntriesByName (DOMString name, optional DOMString type);
      };
      typedef sequence<PerformanceEntry> PerformanceEntryList;
      

The PerformanceEntryList represents a sequence of PerformanceEntry, providing developers with all the convenience methods found on JavaScript arrays.

The PerformanceEntry interface

The PerformanceEntry interface hosts the performance data of various metrics.

      [Exposed=(Window,Worker)]
      interface PerformanceEntry {
        readonly    attribute DOMString           name;
        readonly    attribute DOMString           entryType;
        readonly    attribute DOMHighResTimeStamp startTime;
        readonly    attribute DOMHighResTimeStamp duration;
        [Default] object toJSON();
      };

name

This attribute MUST return an identifier for this PerformanceEntry object. This identifier does not have to be unique.

entryType

This attribute MUST return the type of the interface represented by this PerformanceEntry object.

Example `entryType` values defined by other specifications include: "mark" and "measure" [[USER-TIMING-2]], "navigation" [[NAVIGATION-TIMING-2]], "resource" [[RESOURCE-TIMING-2]], and "longtask".

startTime

This attribute MUST return the time value of the first recorded timestamp of this performance metric. If the startTime concept doesn't apply, a performance metric may choose to return a `startTime` of 0.

duration

This attribute MUST return the time value of the duration of the entire event being recorded by this PerformanceEntry. Typically, this would be the time difference between the last recorded timestamp and the first recorded timestamp of this PerformanceEntry. If the duration concept doesn't apply, a performance metric may choose to return a `duration` of 0.

When toJSON is called, run [[!WebIDL]]'s default toJSON operation.

The PerformanceObserver interface

The PerformanceObserver interface can be used to observe the Performance Timeline to be notified of new performance metrics as they are recorded, and optionally buffered performance metrics.

Each PerformanceObserver has these associated concepts:

• A PerformanceObserverCallback set on creation.
• A list of PerformanceEntry objects called the observer buffer that is initially empty.

The `PerformanceObserver(callback)` constructor must create a new PerformanceObserver object with PerformanceObserverCallback set to callback and then return it.

A registered performance observer consists of an observer (a PerformanceObserver object) and options (a PerformanceObserverInit dictionary).

      callback PerformanceObserverCallback = void (PerformanceObserverEntryList entries,
                                                   PerformanceObserver observer);
      [Constructor(PerformanceObserverCallback callback), Exposed=(Window,Worker)]
      interface PerformanceObserver {
        void observe (PerformanceObserverInit options);
        void disconnect ();
      };
      

To keep the performance overhead to minimum the application should only subscribe to event types that it is interested in, and disconnect the observer once it no longer needs to observe the performance data. Filtering by name is not supported, as it would implicitly require a subscription for all event types — this is possible, but discouraged, as it will generate a significant volume of events.

The observe() method instructs the user agent to register the observer and must run these steps:

1. Remove all unsupported names from the entryTypes sequence.
2. If the resulting 'entryTypes' sequence is an empty sequence, abort these steps. The user agent SHOULD notify developers when the steps are aborted. A console warning listing ignored unsupported names in `entryTypes` might be appropriate, for example.
3. If the list of registered performance observer objects associated with the ECMAScript global environment of the interface object's contains a registered performance observer that is the context object, replace the context object's `options` with options.
4. Otherwise, append a new registered performance observer object to the list of registered performance observer objects associated with the ECMAScript global environment of the interface object, with the context object as `observer` and options as the `options`.
5. If _options'_ buffered flag is set, for each entryType of the `entryTypes` sequence:
   1. Let entries be the PerformanceEntryList object returned by the algorithm with buffer set to performance entry buffer, name set to `null` and type set to entryType.
   2. Append entries to the context object's observer buffer.

        dictionary PerformanceObserverInit {
          required sequence<DOMString> entryTypes;
          boolean buffered = false;
        };
        

        [Exposed=(Window,Worker)]
        interface PerformanceObserverEntryList {
          PerformanceEntryList getEntries();
          PerformanceEntryList getEntriesByType (DOMString type);
          PerformanceEntryList getEntriesByName (DOMString name, optional DOMString type);
        };
        

Queue a PerformanceEntry

To queue a PerformanceEntry (new entry) with an optional add to performance entry buffer flag, which is unset by default, run these steps:

1. Let interested observers be an initially empty set of PerformanceObserver objects.
2. For each registered performance observer (observer):
   1. If observer's PerformanceObserverInit entryTypes includes new entry’s entryType value, append observer to interested observers.
3. For each observer in interested observers:
   1. Append new entry to observer buffer.
4. If the add to performance entry buffer flag is set, add new entry to the performance entry buffer.
5. If the performance observer task queued flag is set, terminate these steps.
6. Set performance observer task queued flag.
7. Queue a task that consists of running the following substeps. The task source for the queued task is the performance timeline task source.
   1. Unset performance observer task queued flag.
   2. Let notify list be a copy of ECMAScript global environment's list of registered performance observer objects.
   3. For each PerformanceObserver object po in notify list, run these steps:
      1. Let entries be a copy of po’s observer buffer.
      2. Empty po’s observer buffer.
      3. If entries is non-empty, call po’s callback with entries as first argument and po as the second argument and callback this value. If this throws an exception, report the exception.

The performance timeline task queue is a low priority queue that, if possible, should be processed by the user agent during idle periods to minimize impact of performance monitoring code.

Filter buffer by name and type

Given a buffer and optional name and type string values this algorithm returns a PerformanceEntryList object that contains a list of PerformanceEntry objects sorted in chronological order with respect to startTime; objects with the same startTime have unspecified ordering.

1. Let the list of entry objects be the empty PerformanceEntryList.
2. For each PerformanceEntry object (entryObject) in the buffer, in chronological order with respect to startTime:
   1. If name is not `null` and entryObject's `name` attribute does not match name in a case-sensitive manner, go to next entryObject.
   2. If type is not `null` and entryObject's `type` attribute does not match type in a case-sensitive manner, go to next entryObject.
   3. Add entryObject to the list of entry objects.
3. Return the list of entry objects.