Performance Timeline Level 2

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

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

Note

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.

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

Each PerformanceObserver has these associated concepts:

• A PerformanceObserverCallback set on creation.
• A PerformanceEntryList object called the observer buffer that is initially empty.
• A DOMString observer type which is initially "undefined".

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

A registered performance observer is a struct consisting of an observer member (a PerformanceObserver object) and an options list member (a list of PerformanceObserverInit dictionaries).

callback PerformanceObserverCallback = void (PerformanceObserverEntryList entries,
                                             PerformanceObserver observer);
[Constructor(PerformanceObserverCallback callback), Exposed=(Window,Worker)]
interface PerformanceObserver {
  void observe (PerformanceObserverInit options);
  void disconnect ();
  PerformanceEntryList takeRecords();
  [SameObject] static readonly attribute FrozenArray<DOMString> supportedEntryTypes;
};

dictionary PerformanceObserverInit {
  sequence<DOMString> entryTypes;
  DOMString type;
};

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

4.1 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. Let entryType be new entry’s entryType value.
3. For each registered performance observer (regObs):
   1. If regObs's options list contains a PerformanceObserverInit item whose entryTypes member includes entryType or whose type member equals to entryType, append regObs's observer to interested observers.
4. For each observer in interested observers:
   1. Append new entry to observer's observer buffer.
5. If the add to performance entry buffer flag is set, add new entry to the performance entry buffer.
6. If the performance observer task queued flag is set, terminate these steps.
7. Set performance observer task queued flag.
8. 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 for the relevant global object.
   2. Let notify list be a copy of relevant global object'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.

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