Re: Unified Timing Proposal

On Fri, Mar 11, 2011 at 2:09 PM, James Simonsen <simonjam@chromium.org>wrote:

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

Tony and I spent some time cleaning up the Unified Timing proposal. We've
come up with an API that uses the same concepts, but is much cleaner. I
think this will make it a lot more appealing. Please take a look at it and
let us know what you think.

Thanks,
Tony and James

API
[Supplemental] interface Performance {
 readonly attribute PerformanceLog log;
};

interface PerformanceLog {
 const unsigned short LOG_ALL = 0;
 const unsigned short LOG_RESOURCE = 1;
 const unsigned short LOG_APP = 2;

 void record(in unsigned short type,
             in optional unsigned short maxLength);
 void stop(in unsigned short type);

 const DOMString MARK_FULLY_LOADED = “fullyLoaded”;
 void mark(in DOMString objectKey,
           in optional DOMString timingKey);

 void clear(in optional unsigned short type);

 Object getTimings(in optional DOMString objectKey);
 Object getDurations(in optional DOMString objectKey);
};

record

Starts or resumes recording of the given log type.

LOG_RESOURCE: An entry will be added to the log for every downloadable
resource requested after this method is called. The objectKey will be the
URL of the resource. A timingKey will always be added for fetchStart and
fetchEnd. If the domain of the resource is the same as the domain of the
root document, an additional timingKey will be added for: redirectStart,
redirectEnd, domainLookupStart, domainLookupEnd, connectStart, connectEnd,
secureConnectionStart, requestStart, responseStart, responseEnd.

LOG_APP: The mark() method behaves as described below.

LOG_ALL: Represents the union of LOG_RESOURCE and LOG_APP.

The number of entries returned by getTimings() and getDurations() is limited
to maxLength. If maxLength isn’t specified, the default is 1,000 entries.

By default, the log starts in LOG_APP mode.

stop

Stops recording of the given log type.

LOG_RESOURCE: An entry for each downloadable resources requested after this
method is called will no longer be added to the log.

LOG_APP: The mark() method becomes a no-op.

LOG_ALL: Represents the union of LOG_RESOURCE and LOG_APP.

mark

Adds an entry of type LOG_APP to the log. The objectKey is the name of the
key of the entry. This method may be called multiple times with the same
key.

If a timingKey is not given, it will default to “value”. The timestamp
associated with this key will be the current time accurate to within 1ms.

clear

Removes all entries of type from the log.

getTimings

Returns an Object in JavaScript Object Notation (JSON) form consisting of
all entries in the log. If an objectKey is given, only the matching entry is
returned. The returned object adheres to the following JSON specificationn.

{

 “objectKey1”: [{

   “timingKey1”: Integer,

   “timingKey2”: Integer,

   ...

 }],

 “objectKey2”: [{

   “timingKey1”: Integer,

   “timingKey2”: Integer,

   ...

 }],

 ...

}

getDurations

Returns an Object in JavaScript Object Notation (JSON) form consisting of
the value of the minimum timingKey subtracted from the maximum timingKey for
each entry in the log. If an objectKey is given, only the matching entry is
returned. The returned object adheres to the following JSON specification.

{

 “objectKey1”: Integer,

 “objectKey2”: Integer,

 ...

}
Examples
Resource timing

<script>
 performance.log.record(performance.log.LOG_RESOURCE);
</script>
<img src="http://example.com/foo.gif">
<script src="http://example.com/foo.js"></script>

> performance.log.getTimings()
{
 "http://example.com/foo.gif": [{fetchStart: 100, fetchEnd: 200}],
 "http://example.com/foo.js": [{fetchStart: 101, fetchEnd: 201}]
}
> performance.log.getTimings("http://example.com/foo.gif")
[{fetchStart: 100, fetchEnd: 200}]
> performance.log.getDurations()
{
 "http://example.com/foo.gif": [100],
 "http://example.com/foo.js": [100]
}
> performance.log.getDurations("http://example.com/foo.gif")
[100]

User timing (measure style)

<script>
 performance.log.mark("readEmail", "start");
 readEmail();
 performance.log.mark("readEmail", "stop");
</script>

> performance.log.getTimings()
{"readEmail": [{start: 123, end: 456}]}
> performance.log.getDurations()
{"readEmail": [333]}
> performance.log.getDurations("readEmail")
[333]

User timing (mark style)

<script>
 document.onclick = function() {
   performance.log.mark("clickTime")
 }
</script>

> performance.log.getTimings()
{“clickTime”: [{value: 123}, {value: 234}]}
> performance.log.getTimings(“clickTime”)
[{value: 123}, {value: 234}]
> performance.log.getDurations()
{“clickTime”: [0, 0]}