Unified Timing Proposal

Hello public-web-perf,

One of the things that's bothered me about the various timing specs is that
each has its own separate interface, despite each basically doing the same
thing. I've come up with a proposal for unifying Navigation Timing, Resource
Timing, and User Timing under a single interface. Take a look and let me
know what you think.

Thanks,
James


Concept Base the design on measures and marks from User Timing. Every mark
must be associated with a measure. Navigation Timing and Resource Timing
become measures.

For Resource Timing, each resource becomes a measure. The name of the
measure is the URI of the resource. The marks within the measure are the
fields from the Resource Timing spec (fetchStart, domainLookupStart,
responseEnd, etc.).

For Navigation Timing, all of the existing metrics become marks in a new
measure called “Document.” The old interface’s performance.timing object is
retained for backwards compatibility, but obsolete.

User Timing is relatively unchanged. A new requirement is that all marks
must belong to a measure. If no measure is specified, a default one is
chosen, which is created if it doesn’t exist.

API interface PerformanceTiming {
  PerformanceMeasure getMeasure(in DOMString measureName);
  Array getMeasures();
  void clearMeasures(in optional DOMString measureName);

  // User Timing
  void measure(in DOMString markName,
               in optional DOMString measureName);
};

interface PerformanceMeasure {
  long long getMark(in DOMString markName);
  void clearMarks(in optional DOMString markName);
  long long getDuration();
};
Examples Read navigationStart
getMeasure(“Document”).getMark(“navigationStart”);
-> 123
Dump Navigation Timing getMeasure(“Document”);
-> {“navigationStart”: 123, “responseStart”: 456, …}
Resource Load Time
getMeasure(document.getElementById(“myImage”).src).getDuration();
-> 75
Dump Everything getMeasures();
-> {“Document”: {“navigationStart”: 123, “responseStart”: 456, …},
   “http://resource/1”: {“fetchStart”: 700, “responseStart”: 800, …},
   “fetchEmail”: {“start”: 1000, “loadedHeaders”: 1200, “end”: 1400}}
User Timing measure(“start”, “fetchEmail”);
measure(“loadedHeaders”, “fetchEmail”);
measure(“end”, “fetchEmail”);
getMeasure(“fetchEmail”).getDuration();
-> {“start”: 1000, “loadedHeaders”: 1200, “end”: 1400}
Implementation Details

   - Every mark must belong to a measure.
   - If no measure is specified, a default is chosen (document or
   “unknown”).
   - Measures can contain one or many marks.
   - The start and end of a measure is dictated by its earliest and latest
   occurring marks.
   - Navigation Timing and Resource Timing marks and measures are created by
   the UA.
   - Marks must have unique names within a measure.
   - Measures must have unique names.
   - Repeated mark handling TBD. (raise an exception or overwrite?)


Abandoned Features Select Resources by ID or Type Resource Timing contains
functions to access resource timing information by ID, URL, or resource
type. As far as the network layer is concerned, URL is the only identifier
that makes a resource unique. Based on this, URL will become the primary key
used to look up resources in Resource Timing.

The other identification methods, ID and type, have already been implemented
by the DOM. Rather than duplicating their behavior, we will just use the
existing DOM functions to fetch the URL needed for Unified Timing.

For instance, ID can be converted to URL via:
getElementById(id).src;

Type can be converted to URL via:
for (var elem in getElementsByTagName(type)) {
  elem.url;
}

If this is unacceptable, we can still use the other look up methods, but
they would just be a layer on top of the underlying URL based system.
Repeated Marks User Timing allows the same mark to occur many times. All of
the interfaces need to accommodate this by returning arrays. This means that
even simple cases have to index into an array. Instead, the burden has been
shifted to the user collecting several marks with the same name. Each must
have a unique name.

If this is unacceptable, we can return arrays from the interface.
Primary Benefits Single Interface This unifies the 3 existing timing
specifications into a single interface.
Future Compatible Adding additional timing information to the interface
should be just a matter of adding new measures or marks to the model. For
example, one future proposal is to include paint times. Each element can
have its own measure with marks for layouts and paints.
Waterfall View The waterfall view found in the Web Inspector is considered
the model for the timing specifications. This proposal structures the data
in the same way it appears in the waterfall.
Other Considerations Opt-in It would be easy to flood the user with a
massive array of measures and marks for every detail the UA can record. Most
users won’t record every single detail all of the time and we should
discourage them from doing so. Instead, users should opt-in to the data
they’d like collected. This becomes more important as we measure more
things.
Variations Measure Types Each measure has an associated type: document,
resource, or user. These correspond to the 3 timing specifications. The UA
assigns the type when creating a measure. Users can filter measures based on
type.
Explicit Measures For simplicity, it may be better to just require users to
specify a measure when using User Timing.