Skip to content

Commit

Permalink
Add navigationId to PerformanceEntry (#192)
Browse files Browse the repository at this point in the history 
Add id and navigationId fields to PerformanceEntry. These are integers, used to uniquely identify timeline entries,
so that they can be referred to in other entries. The initial use case for this is to track navigation-like events within
a page's lifetime. For this, the navigationId field is used, in each entry, to refer to the most recent navigation (or
back-forward-cache restoration, or soft navigation) which had occurred in the page.

---------

Co-authored-by: Marcos Cáceres <marcos@marcosc.com>
  • Loading branch information
@clelland @marcoscaceres
clelland and marcoscaceres authored Oct 11, 2023
1 parent 3984a34 commit f6a67dc
Show file tree
Hide file tree
Showing 2 changed files with 103 additions and 0 deletions.
16 changes: 16 additions & 0 deletions explainer.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -55,10 +55,12 @@ In order to prevent the user agent from storing too much performance data in mem
This specification defines the `PerformanceEntry` interface, which is used to host performance data of the web application.
A single `PerformanceEntry` object corresponds to one nugget of information about the performance of the website.
The entry has the following attributes:
* `id`: an integer identifying this `PerformanceEntry` object.
* `name`: a string identifier for the object, also used to filter entries in the `getEntriesByName()` method.
* `entryType`: a string representing the type of performance data being exposed. It is also used to filter entries in the `getEntriesByType()` method and in the `PerformanceObserver`.
* `startTime`: a timestamp representing the starting point for the performance data being recorded. The semantics of this attribute depend on the `entryType`.
* `duration`: a time duration representing the duration of the performance data being recorded. The semantics of this one also depend on the `entryType`.
* `navigationId`: an integer identifying (by `id`) the `PerformanceEntry` object corresponding to last navigation or navigation-like event that had occurred in the document at the time that this `PerformanceEntry` object was recorded.

If these sound abstract, it’s because they are.
A specification whose goal is to expose new measurements to web developers will define a new interface which extends `PerformanceEntry`.
Expand Down Expand Up @@ -150,6 +152,20 @@ For entryTypes with a fixed amount of entries, like Paint Timing, using the poll
At the same time, the callback is more useful for cases where there is varying amount of entries of the given entryType, like in Resource Timing.
The web performance monitoring service can process all the performance information while the page is still running and only has to do very minimal work when the data needs to be reported.

## Page lifetime issues
When this API was originally designed, documents had a relatively simple lifecycle: they were
loaded when the user navigated to them, and unloaded when the user navigated away, with the
JavaScript environment being torn down at that time. Since then, the sitution has become more
complex, with many browsers introducing a back-forward cache, with which a user can return to
a document which they have previously navigated away from. The web has also seen a rise in
popularity of Single Page Apps, where what appears to the user to be a navigation is actually
just a change in state of a running page. In both of these situations, a navigation (or what
appears to the user as a navigation) can occur without the performance timeline being reset.
In order to allow developers to reason about such events during the life of a page, some
PerformanceEntry objects mark navigations, or navigation-like events. All PerformanceEntry
objects include a navigation ID field, which ties each PerformanceEntry to the most recent
navigation entry which had occurred before the entry was generated.

# Standards Status
The Performance Timeline specification is widely approved.
There are differences in what kinds of performance data is exposed on different user agents, but this specification does not concern itself with that, and that is delegated to the new specifications that describe new data.
Expand Down
87 changes: 87 additions & 0 deletions index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -67,6 +67,9 @@
</li>
<li>Exposes {{PerformanceEntry}} in Web Workers [[WORKERS]];
</li>
<li>Formalizes support for multiple navigation events over a document's
lifetime.
</li>
<li>Adds support for {{PerformanceObserver}}.
</li>
</ul>
Expand Down Expand Up @@ -243,6 +246,15 @@ <h2><dfn>Performance Timeline</dfn></h2>
<li>An integer <dfn>dropped entries count</dfn> that is initially 0.</li>
</ul>
</li>
<li>An integer <dfn>last performance entry id</dfn> that is initially set
to a random integer between 100 and 10000.
</li>
</ul>
<p>Each <a>Document</a> has:</p>
<ul>
<li>A <dfn>most recent navigation</dfn>, which is a <a>PerformanceEntry</a>,
initially unset.
</li>
</ul>
<p>In order to get the <dfn>relevant performance entry tuple</dfn>, given
<var>entryType</var> and <var>globalObject</var> as input, run the
Expand Down Expand Up @@ -301,13 +313,19 @@ <h2>The <dfn>PerformanceEntry</dfn> interface</h2>
<pre class='idl'>
[Exposed=(Window,Worker)]
interface PerformanceEntry {
readonly attribute unsigned long long id;
readonly attribute DOMString name;
readonly attribute DOMString entryType;
readonly attribute DOMHighResTimeStamp startTime;
readonly attribute DOMHighResTimeStamp duration;
readonly attribute unsigned long long navigationId;
[Default] object toJSON();
};</pre>
<dl>
<dt><dfn>id</dfn></dt>
<dd>
This attribute MUST return the value of <a>this</a>'s <a>id</a>.
</dd>
<dt><dfn>name</dfn></dt>
<dd>
This attribute MUST return an identifier for this
Expand Down Expand Up @@ -341,6 +359,10 @@ <h2>The <dfn>PerformanceEntry</dfn> interface</h2>
duration concept doesn't apply, a performance metric may choose to
return a `duration` of <code>0</code>.
</dd>
<dt><dfn>navigationId</dfn></dt>
<dd>
This attribute MUST return the value of <a>this</a>'s <a>navigationId</a>.
</dd>
</dl>
<p>When <dfn>toJSON</dfn> is called, run [[WebIDL]]'s <a>default toJSON
steps</a>.</p>
Expand Down Expand Up @@ -660,6 +682,12 @@ <h2>Queue a <code>PerformanceEntry</code></h2>
<p>To <dfn class="export">queue a PerformanceEntry</dfn> (<var>newEntry</var>), run
these steps:</p>
<ol>
<li>If <var>newEntry</var>'s {{PerformanceEntry/id}} is unset:
<ol>
<li>Let <var>id</var> be the result of running <a>generate an id</a> for <var>newEntry</var>.</li>
<li>Set <var>newEntry</var>'s {{PerformanceEntry/id}} to <var>id</var>.</li>
</ol>
</li>
<li>Let <var>interested observers</var> be an initially empty set of
<a>PerformanceObserver</a> objects.
</li>
Expand All @@ -669,6 +697,15 @@ <h2>Queue a <code>PerformanceEntry</code></h2>
<li>Let <var>relevantGlobal</var> be <var>newEntry</var>'s <a>relevant
global object</a>.
</li>
<li>If <var>relevantGlobal</var> has an [=associated document=]:
<ol>
<li>Set <var>newEntry</var>'s <a
data-lt="PerformanceEntry.navigationId">navigationId</a> to the value of
<var>relevantGlobal</var>'s [=associated document=]'s [=most recent navigation=]'s {{PerformanceEntry/id}}.</li>
</ol>
</li>
<li>Otherwise, set <var>newEntry</var>'s <a
data-lt="PerformanceEntry.navigationId">navigationId</a> to null.</li>
<li>For each <a>registered performance observer</a> <var>regObs</var> in
<var>relevantGlobal</var>'s <a>list of registered performance observer objects</a>:
<ol>
Expand Down Expand Up @@ -714,6 +751,25 @@ <h2>Queue a <code>PerformanceEntry</code></h2>
</li>
</ol>
</section>
<section data-link-for="PerformanceObserver">
<h2>Queue a navigation <code>PerformanceEntry</code></h2>
<p>To <dfn class="export">queue a navigation PerformanceEntry</dfn> (<var>newEntry</var>), run
these steps:</p>
<ol>
<li>Let <var>id</var> be the result of running <a>generate an id</a> for <var>newEntry</var>.</li>
<li>Let <var>relevantGlobal</var> be <var>newEntry</var>'s <a>relevant
global object</a>.
</li>
<li>Set <var>newEntry</var>'s {{PerformanceEntry/id}} to <var>id</var>.</li>
<li>Set <var>newEntry</var>'s {{PerformanceEntry/navigationId}} to <var>id</var>.</li>
<li>If <var>relevantGlobal</var> has an [=associated document=]:
<ol>
<li>Set <var>relevantGlobal</var>'s [=associated document=]'s [=most recent navigation=] to <var>newEntry</var>.</li>
</ol>
</li>
<li><a>Queue a PerformanceEntry</a> with <var>newEntry</var> as input.</li>
</ol>
</section>
<section data-link-for="PerformanceObserver">
<h2>Queue the PerformanceObserver task</h2>
<p>When asked to <dfn>queue the PerformanceObserver task</dfn>, given
Expand Down Expand Up @@ -883,6 +939,28 @@ <h2>Determine if a performance entry buffer is full</h2>
<li>Return true.</li>
</ol>
</section>
<section data-link-for="PerformanceEntry">
<h2>Generate a Performance Entry id</h2>
<p>When asked to <dfn class="export">generate an id</dfn> for a
<a>PerformanceEntry</a> <var>entry</a>, run the following steps:</p>
<ol>
<li>Let <var>relevantGlobal</var> be <var>entry</var>'s <a>relevant
global object</a>.
<li>Increase <var>relevantGlobal</var>'s <a>last performance entry
id</a> by a small number chosen by the user agent.</li>
<li>Return <var>relevantGlobal</var>'s <a>last performance entry id</a>.
</ol>
<p>A user agent may choose to increase the <a>last performance entry
id</a>it by a small random integer every time. A user agent must not pick
a single global random integer and increase the <a>last performance entry
id</a> of all global objects by that amount because this could introduce
cross origin leaks.
</p>
<p class="note">The <a>last performance entry id</a> 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.</p>
</section>
</section>
<section id="privacy">
<h3>Privacy Considerations</h3>
Expand All @@ -891,6 +969,15 @@ <h3>Privacy Considerations</h3>
refer to [[HR-TIME-3]] for privacy considerations of exposing high-resoluting timing
information. Each new specification introducing new performance entries should have its own
privacy considerations as well.</p>
<p>The <a>last performance entry id</a> is deliberately initialized to a
random value, and is incremented by another small value every time a new
{{PerformanceEntry}} is queued. User agents may choose to use a consistent
increment for all users, or may pick a different increment for each
<a>global object</a>, or may choose a new random increment for each
{{PerformanceEntry}}. However, in order to prevent cross-origin leaks, and
ensure that this does not enable fingerprinting, user agents must not just
pick a unique random integer, and use it as a consistent increment for all
{{PerformanceEntry}} objects across all <a>global objects</a>.
</section>
<section id="security">
<h3>Security Considerations</h3>
Expand Down

0 comments on commit f6a67dc

Please sign in to comment.