Copyright
©
2012
©
2013
W3C
®
®
(
MIT
,
ERCIM
,
Keio
,
Beihang
),
All
Rights
Reserved.
W3C
liability
,
trademark
and
document
use
rules
apply.
This specification defines an unified interface to store and retrieve performance metric data. This specification does not cover individual performance metric interfaces.
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.
This
is
the
W3C
Proposed
Recommendation
of
"Performance
Timeline
Specification".
W3C
publishes
a
Candidate
technical
report
as
a
Proposed
Recommendation
to
indicate
that
the
document
is
believed
to
be
stable
and
to
encourage
implementation
by
the
developer
community.
The
entrance
criteria
a
mature
technical
report
that
has
received
wide
review
for
this
document
technical
soundness
and
implementability
and
to
enter
request
final
endorsement
from
the
W3C
Advisory
Committee.
Proposed
Recommendation
stage
status
is
to
have
a
minimum
of
two
independent
and
interoperable
user
agents
that
implementation
all
the
features
of
this
specification,
which
will
be
determined
by
passing
the
user
agent
tests
defined
described
in
section
7.1.1
of
the
test
suite
developed
by
the
Working
Group.
Process
Document
.
The
Working
Group
does
not
expect
to
advance
to
Proposed
Recommendation
prior
to
1
November
2012
.
A
preliminary
implementation
report
is
available
W3C
Membership
and
will
be
updated
during
other
interested
parties
are
invited
to
review
the
Candidate
Recommendation
period.
This
is
a
work
in
progress
document
and
may
change
without
any
notices.
The
Working
Group
intends
to
gain
implementation
experience
before
recommending
that
implementations
remove
their
vendor
prefixes.
Please
send
comments
to
public-web-perf@w3.org
(
archived
)
with
[PerformanceTimeline]
at
the
start
of
the
subject
line
by
1
through
.
Advisory
Committee
Representatives
should
consult
their
WBS
questionnaires
.
A diff document with the previous draft is also available.
By publishing this Proposed Recommendation, W3C expects that the functionality specified in this specification will not be affected by changes to Web IDL as that specification proceeds to Recommendation.
Please send comments to public-web-perf@w3.org ( archived ) with [PerformanceTimeline] at the start of the subject line.
This
document
is
produced
by
the
Web
Performance
Working
Group.
The
Web
Performance
Working
Group
is
part
of
the
Rich
Web
Clients
Activity
in
the
W3C
Interaction
Domain
.
You
can
find
the
latest
Editor's
Draft
of
this
document
in
the
W3C's
Mercurial
repository
,
which
is
updated
on
a
regular
basis.
Publication
as
a
Candidate
Proposed
Recommendation
does
not
imply
endorsement
by
the
W3C
Membership.
This
is
a
draft
document
and
may
be
updated,
replaced
or
obsoleted
by
other
documents
at
any
time.
It
is
inappropriate
to
cite
this
document
as
other
than
work
in
progress.
This document was produced by a group operating under the 5 February 2004 W3C Patent Policy . W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy .
This section is non-normative.
Accurately measuring performance characteristics of web applications is an important aspect of making web applications faster. [Navigation Timing] , [Resource Timing] , and [User Timing] are examples of specifications that define timing information related to the navigation of the document, resources on the page, and developer scripts, respectively.
Together these interfaces, and potentially others created in the future, define performance metrics that describe the performance timeline of a web application. This specification provides an unifying interface to access and retrieve these various performance metrics from the performance timeline of a web application.
The
following
script
shows
how
a
developer
can
use
the
PerformanceEntry
interface
to
obtain
timing
data
related
to
the
navigation
of
the
document,
resources
on
the
page
and
developer
scripts.
<!doctype html> <html> <head> </head> <body onload="init()"> <img id="image0" src="http://w3c-test.org/webperf/image0.png" /> <script> function init() { performance.mark("startWork"); // see doWork(); // Some developer code performance.mark("endWork"); measurePerf(); } function measurePerf() { var perfEntries = performance.getEntries(); for (var i = 0; i < perfEntries.length; i++) { if (window.console) console.log("Name: " + perfEntries[i].name + " Entry Type: " + perfEntries[i].entryType + " Start Time: " + perfEntries[i].startTime + " Duration: " + perfEntries[i].duration + "\n"); } } </script> </body> </html>
All diagrams, examples, and notes in this specification are non-normative, as are all sections explicitly marked non-normative. Everything else in this specification is normative.
The key words "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in the normative parts of this document are to be interpreted as described in RFC 2119 . For readability, these words do not appear in all uppercase letters in this specification.
Requirements phrased in the imperative as part of algorithms (such as "strip any leading space characters" or "return false and abort these steps") are to be interpreted with the meaning of the key word ("must", "should", "may", etc) used in introducing the algorithm.
Some conformance requirements are phrased as requirements on attributes, methods or objects. Such requirements are to be interpreted as requirements on user agents.
Conformance requirements phrased as algorithms or specific steps may be implemented in any manner, so long as the end result is equivalent. (In particular, the algorithms defined in this specification are intended to be easy to follow, and not intended to be performant.)
The IDL fragments in this specification must be interpreted as required for conforming IDL fragments, as described in the Web IDL specification. [Web IDL]
The
construction
"a
Foo
object",
where
Foo
is
actually
an
interface,
is
sometimes
used
instead
of
the
more
accurate
"an
object
implementing
the
interface
Foo
".
Throughout this work, all time values are measured in milliseconds since the start of navigation of the document. For example, the start of navigation of the document occurs at time 0. The term current time refers to the number of milliseconds since the start of navigation of the document until the current moment in time. This definition of time is based on the High Resolution Time specification [ High Resolution Time ] and is different from the definition of time used in the Navigation Timing specification [ Navigation Timing ], where time is measured in milliseconds since midnight of January 1, 1970 (UTC).
All
interfaces
that
participate
in
the
Performance
Timeline
,
such
as
the
PerformanceResourceTiming
[Resource
Timing]
,
PerformanceMark
,
and
PerformanceMeasure
[User
Timing]
interfaces,
must
adhere
to
the
following
rules:
PerformanceEntry
interface
getEntries
,
getEntriesByType
,
and
getEntriesByName
methods
PerformanceEntry
interface
interface PerformanceEntry { readonly attribute DOMString name; readonly attribute DOMString entryType; readonly attribute DOMHighResTimeStamp startTime; readonly attribute DOMHighResTimeStamp duration; };
name
attribute
The
name
attribute
must
return
the
identifier
for
this
PerformanceEntry
object.
This
identifier
does
not
have
to
be
unique.
entryType
attribute
The
entryType
attribute
must
return
a
DOMString
that
describes
the
type
of
the
interface
represented
by
this
PerformanceEntry
object.
The
Web
Performance/entryType
wiki
page
lists
all
of
the
known
entryType
values.
startTime
attribute
The
startTime
attribute
must
return
a
DOMHighResTimeStamp
that
contains
the
time
value
of
the
first
recorded
timestamp
of
this
performance
metric.
duration
attribute
The
duration
attribute
must
return
a
DOMHighResTimeStamp
that
contains
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
.
A
performance
metric
may
choose
to
return
a
duration
of
0,
if
the
duration
concept
doesn't
apply.
Performance
interface
partial interface Performance { PerformanceEntryList getEntries(); PerformanceEntryList getEntriesByType(DOMString entryType); PerformanceEntryList getEntriesByName(DOMString name, optional DOMString entryType); }; typedef sequence <PerformanceEntry> PerformanceEntryList;
The
window.performance
attribute
provides
a
hosting
area
for
performance
measurement
related
attributes
and
methods
using
the
Performance
interface
[Navigation
Timing]
.
getEntries
method
The
getEntries
method
returns
a
PerformanceEntryList
object
that
contains
a
copy
of
all
PerformanceEntry
objects
in
chronological
order
with
respect
to
startTime
.
getEntriesByType
method
The
getEntriesByType
method
returns
a
PerformanceEntryList
object
that
contains
a
copy
of
all
PerformanceEntry
objects,
in
chronological
order
with
respect
to
startTime
,
that
have
the
same
value
for
the
entryType
attribute
of
PerformanceEntry
as
the
entryType
parameter.
Parameter
DOMString
entryType
A
PerformanceEntryList
object
that
contains
a
copy
of
PerformanceEntry
objects
that
have
the
same
value
for
the
entryType
attribute
of
PerformanceEntry
as
the
entryType
parameter.
If
no
such
PerformanceEntry
objects
exist,
the
PerformanceEntryList
must
be
empty.
Return value
A
PerformanceEntryList
object.
No exceptions
getEntriesByName
method
The
getEntriesByName
method
returns
a
PerformanceEntryList
object
that
contains
a
copy
of
PerformanceEntry
objects,
in
chronological
order
with
respect
to
startTime
,
that
have
the
same
value
for
the
name
attribute
of
PerformanceEntry
as
the
name
parameter
and,
if
specified,
have
the
same
value
for
the
entryType
attribute
of
PerformanceEntry
as
the
entryType
parameter.
Parameter
DOMString
name
The
PerformanceEntryList
object
that
contains
a
copy
of
PerformanceEntry
objects
that
have
the
same
value
for
the
name
attribute
of
PerformanceEntry
as
the
name
parameter.
If
no
such
PerformanceEntry
objects
exist,
the
PerformanceEntryList
must
be
empty.
DOMString
entryType
The
PerformanceEntryList
object
that
only
contains
a
copy
of
PerformanceEntry
objects
that
have
the
same
value
for
the
entryType
attribute
of
PerformanceEntry
as
the
entryType
parameter
and
have
the
same
value
for
the
name
attribute
of
PerformanceEntry
as
the
name
parameter.
If
no
such
PerformanceEntry
objects
exist,
the
PerformanceEntryList
must
be
empty.
Return value
A
PerformanceEntryList
object.
No exceptions
If
a
vendor-specific
proprietary
user
agent
extension
is
needed
to
create
experimental
PerformanceEntry
objects,
on
getting
the
entryType
IDL
attribute,
vendors
MUST
return
a
DOMString
that
uses
the
following
convention:
[vendorprefix]-[entrytype]
Where,
[vendorprefix]
is
a
non-capitalized
name
that
identifies
the
vendor,
[entrytype]
is
a
non-capitalized
name
given
to
the
type
of
the
interface
represented
by
this
PerformanceEntry
object,
We would like to offer our sincere thanks to all the people that we have been in touch with regarding this draft for their reviews and feedback.