Extensions to the {{Performance}} interface

This extends the {{Performance}} interface from [[HR-TIME-3]] 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.

PerformanceObserverCallbackOptions dictionary

        dictionary PerformanceObserverCallbackOptions {
          unsigned long long droppedEntriesCount;
        };
      

droppedEntriesCount

An integer representing the dropped entries count for the entry types that the observer is observing when the PerformanceObserver's requires dropped entries is set.

observe() method

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

1. Let relevantGlobal be this's relevant global object.
2. If options's entryTypes and type members are both omitted, then [=exception/throw=] a {{"TypeError"}}.
3. If options's entryTypes is present and any other member is also present, then [=exception/throw=] a {{"TypeError"}}.
4. Update or check this's observer type by running these steps:
   1. If this's observer type is "undefined":
      1. If options's entryTypes member is present, then set this's observer type to "multiple".
      2. If options's type member is present, then set this's observer type to "single".
   2. If this's observer type is "single" and options's entryTypes member is present, then [=exception/throw=] an {{"InvalidModificationError"}}.
   3. If this's observer type is "multiple" and options's type member is present, then [=exception/throw=] an {{"InvalidModificationError"}}.
5. Set this's requires dropped entries to true.
6. If this's observer type is "multiple", run the following steps:
   1. Let entry types be options's entryTypes sequence.
   2. Remove all types from entry types that are not contained in relevantGlobal's frozen array of supported entry types. The user agent SHOULD notify developers if entry types is modified. For example, a console warning listing removed types might be appropriate.
   3. If the resulting entry types sequence is an empty sequence, abort these steps. The user agent SHOULD notify developers when the steps are aborted to notify that registration has been aborted. For example, a console warning might be appropriate.
   4. If the list of registered performance observer objects of relevantGlobal contains a registered performance observer whose observer is this, replace its options list with a list containing options as its only item.
   5. Otherwise, create and append a registered performance observer object to the list of registered performance observer objects of relevantGlobal, with observer set to this and options list set to a list containing options as its only item.
7. Otherwise, run the following steps:
   1. Assert that this's observer type is "single".
   2. If options's type is not contained in the relevantGlobal's frozen array of supported entry types, abort these steps. The user agent SHOULD notify developers when this happens, for instance via a console warning.
   3. If the list of registered performance observer objects of relevantGlobal contains a registered performance observer obs whose observer is this:
      1. If obs's options list contains a PerformanceObserverInit item currentOptions whose type is equal to options's type, replace currentOptions with options in obs's options list.
      2. Otherwise, append options to obs's options list.
   4. Otherwise, create and append a registered performance observer object to the list of registered performance observer objects of relevantGlobal, with observer set to the this and options list set to a list containing options as its only item.
   5. If options's buffered flag is set:
      1. Let tuple be the relevant performance entry tuple of options's type and relevantGlobal.

      2. For each entry in tuple's performance entry buffer:

         1. If should add entry with entry and options as parameters returns true, [=list/append=] entry to the observer buffer.
      3. Queue the PerformanceObserver task with relevantGlobal as input.

A PerformanceObserver object needs to always call observe() with options's entryTypes set OR always call observe() with options's type set. If one PerformanceObserver calls observe() with entryTypes and also calls observe with type, then an exception is thrown. This is meant to avoid confusion with how calls would stack. When using entryTypes, no other parameters in PerformanceObserverInit can be used. In addition, multiple observe() calls will override for backwards compatibility and because a single call should suffice in this case. On the other hand, when using type, calls will stack because a single call can only specify one type. Calling observe() with a repeated type will also override.

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

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

takeRecords() method

The takeRecords() method must return a copy of this's observer buffer, and also empty this's observer buffer.

disconnect() method

The disconnect() method must do the following:

1. Remove this from the list of registered performance observer objects of relevant global object.
2. Empty this's observer buffer.
3. Empty this's options list.

supportedEntryTypes attribute

Each global object has an associated frozen array of supported entry types, which is initialized to the FrozenArray created from the sequence of strings among the registry that are supported for the global object, in alphabetical order.

When supportedEntryTypes's attribute getter is called, run the following steps:

1. Let globalObject be the environment settings object's global object.
2. Return globalObject's frozen array of supported entry types.

This attribute allows web developers to easily know which entry types are supported by the user agent.

Queue a PerformanceEntry

To queue a PerformanceEntry (newEntry), run these steps:

1. If newEntry's {{PerformanceEntry/id}} is unset:
   1. Let id be the result of running generate an id for newEntry.
   2. Set newEntry's {{PerformanceEntry/id}} to id.
2. Let interested observers be an initially empty set of PerformanceObserver objects.
3. Let entryType be newEntry’s entryType value.
4. Let relevantGlobal be newEntry's relevant global object.
5. If relevantGlobal has an [=associated document=]:
   1. Set newEntry's navigationId to the value of relevantGlobal's [=associated document=]'s [=most recent navigation=]'s {{PerformanceEntry/id}}.
6. Otherwise, set newEntry's navigationId to null.
7. For each registered performance observer regObs in relevantGlobal's list of registered performance observer objects:

   1. If regObs's options list contains a PerformanceObserverInit options whose entryTypes member includes entryType or whose type member equals to entryType:

      1. If should add entry with newEntry and options returns true, append regObs's observer to interested observers.
8. For each observer in interested observers:
   1. Append newEntry to observer's observer buffer.
9. Let tuple be the relevant performance entry tuple of entryType and relevantGlobal.
10. Let isBufferFull be the return value of the determine if a performance entry buffer is full algorithm with tuple as input.
11. Let shouldAdd be the result of should add entry with newEntry as input.
12. If isBufferFull is false and shouldAdd is true, [=list/append=] newEntry to tuple's performance entry buffer.
13. Queue the PerformanceObserver task with relevantGlobal as input.

Queue a navigation PerformanceEntry

To queue a navigation PerformanceEntry (newEntry), run these steps:

1. Let id be the result of running generate an id for newEntry.
2. Let relevantGlobal be newEntry's relevant global object.
3. Set newEntry's {{PerformanceEntry/id}} to id.
4. Set newEntry's {{PerformanceEntry/navigationId}} to id.
5. If relevantGlobal has an [=associated document=]:
   1. Set relevantGlobal's [=associated document=]'s [=most recent navigation=] to newEntry.
6. Queue a PerformanceEntry with newEntry as input.

Queue the PerformanceObserver task

When asked to queue the PerformanceObserver task, given relevantGlobal as input, run the following steps:

1. If relevantGlobal's performance observer task queued flag is set, terminate these steps.
2. Set relevantGlobal's performance observer task queued flag.
3. 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 of relevantGlobal.
   2. Let notifyList be a copy of relevantGlobal's list of registered performance observer objects.
   3. For each registered performance observer object registeredObserver in notifyList, run these steps:
      1. Let po be registeredObserver's observer.
      2. Let entries be a copy of po’s observer buffer.
      3. If entries is empty, return.
      4. Empty po’s observer buffer.
      5. Let observerEntryList be a new {{PerformanceObserverEntryList}}, with its entry list set to entries.
      6. Let droppedEntriesCount be null.
      7. If po's requires dropped entries is set, perform the following steps:
         1. Set droppedEntriesCount to 0.
         2. For each PerformanceObserverInit item in registeredObserver's options list:
            1. For each DOMString entryType that appears either as item's type or in item's entryTypes:
               1. Let map be relevantGlobal's performance entry buffer map.
               2. Let tuple be the result of getting the value of entry on map given entryType as key.
               3. Increase droppedEntriesCount by tuple's dropped entries count.
         3. Set po's requires dropped entries to false.
      8. Let callbackOptions be a PerformanceObserverCallbackOptions with its droppedEntriesCount set to droppedEntriesCount if droppedEntriesCount is not null, otherwise unset.
      9. [=Invoke=] po’s observer callback with « observerEntryList, po, callbackOptions », "`report`", and po.

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 map by name and type

When asked to run the filter buffer map by name and type algorithm with optional name and type, run the following steps:

1. Let result be an initially empty list.
2. Let map be the performance entry buffer map associated with the relevant global object of this.
3. Let tuple list be an empty list.
4. If type is not null, append the result of getting the value of entry on map given type as key to tuple list. Otherwise, assign the result of get the values on map to tuple list.
5. For each tuple in tuple list, run the following steps:
   1. Let buffer be tuple's performance entry buffer.
   2. If tuple's availableFromTimeline is false, continue to the next tuple.
   3. Let entries be the result of running filter buffer by name and type with buffer, name and type as inputs.
   4. For each entry in entries, [=list/append=] entry to result.
6. Sort results's entries in chronological order with respect to startTime
7. Return result.

Filter buffer by name and type

When asked to run the filter buffer by name and type algorithm, with buffer, name, and type as inputs, run the following steps:

1. Let result be an initially empty list.
2. For each PerformanceEntry entry in buffer, run the following steps:
   1. If type is not null and if type is not identical to entry's entryType attribute, continue to next entry.
   2. If name is not null and if name is not identical to entry's name attribute, continue to next entry.
   3. [=list/append=] entry to result.
3. Sort results's entries in chronological order with respect to startTime
4. Return result.

Determine if a performance entry buffer is full

To determine if a performance entry buffer is full, with tuple as input, run the following steps:

1. Let num current entries be the size of tuple's performance entry buffer.
2. If num current entries is less than tuples's maxBufferSize, return false.
3. Increase tuple's dropped entries count by 1.
4. Return true.

Generate a Performance Entry id

When asked to generate an id for a PerformanceEntry entry, run the following steps:

1. Let relevantGlobal be entry's relevant global object.
2. Increase relevantGlobal's last performance entry id by a small number chosen by the user agent.
3. Return relevantGlobal's last performance entry id.

A user agent may choose to increase the last performance entry idit by a small random integer every time. A user agent must not pick a single global random integer and increase the last performance entry id of all global objects by that amount because this could introduce cross origin leaks.

The last performance entry id has an initial random value, and 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 entries that have been generated in the web application.