Copyright
©
2012
©
2013
W3C
®
®
(
MIT
,
ERCIM
,
Keio
,
Beihang
),
All
Rights
Reserved.
W3C
liability
,
trademark
and
document
use
rules
apply.
This specification defines an interface to help web developers measure the performance of their applications by giving them access to high precision timestamps.
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
"User
Timing
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
[UserTiming]
at
the
start
of
the
subject
line
by
1
through
.
Advisory
Committee
Representatives
should
consult
their
WBS
questionnaires
.
Following
feedback
during
the
Last
Call
phase,
the
Working
Group
did
the
following
changes:
getMarks
,
getMeasures
got
removed
(duplicating
features
with
getEntriesByType
and
getEntriesByName
[Performance
Timeline]
)
added
a
section
on
privacy/security
Updated
references
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 [UserTiming] 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.
Web
developers
need
the
ability
to
assess
and
understand
the
performance
characteristics
of
their
applications.
While
JavaScript
[ECMA262]
provides
a
mechanism
to
measure
application
latency
(retrieving
the
current
timestamp
from
the
Date.now()
method),
the
precision
of
this
timestamp
varies
between
user
agents.
This
document
defines
the
PerformanceMark
and
PerformanceMeasure
interfaces,
and
extensions
to
the
Performance
interface,
which
expose
a
high
precision
timestamp
to
developers
so
they
can
better
measure
the
performance
of
their
applications.
The following script shows how a developer can use the interfaces defined in this document to obtain timing data related to developer scripts.
<!doctype html> <html> <head> <title>User Timing example</title> </head> <body onload="init()"> <script> function init() { performance.mark("startTask1"); doTask1(); // Some developer code performance.mark("endTask1"); performance.mark("startTask2"); doTask2(); // Some developer code performance.mark("endTask2"); measurePerf(); } function measurePerf() { var perfEntries = performance.getEntriesByType("mark"); 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 RFC2119. For readability, these words do not appear in all uppercase letters in this specification. [RFC2119]
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
".
The term "JavaScript" is used to refer to ECMAScript [ECMA262] , rather than the official term ECMAScript, since the term JavaScript is more widely known.
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).
This section is non-normative
The
PerformanceMark
and
PerformanceMeasure
interfaces,
and
extensions
to
the
Performance
interface,
give
web
developers
access
to
a
high
precision,
monotonically
increasing
timestamp
so
they
can
better
measure
the
performance
characteristics
of
their
applications.
Performance
Interface
partial interface Performance { void mark(DOMString markName); void clearMarks(optional DOMString markName); void measure(DOMString measureName, optional DOMString startMark, optional DOMString endMark); void clearMeasures(optional DOMString measureName); };
mark
method
This method stores a timestamp with the associated name (a "mark").
Parameters
in
markName
type
of
DOMString
The name associated with the timestamp.
Mark
names
may
be
re-used
within
the
same
document.
Each
call
to
the
mark()
method
stores
a
new
timestamp
under
the
specified
mark
name.
The
mark
name
cannot
be
the
same
name
as
any
of
the
attributes
in
the
PerformanceTiming
interface
[Navigation
Timing]
.
Recommended Mark Names
Developers are encouraged to use the following Recommended Mark Names to mark common interactions. The user agent is responsible for storing a new timestamp under the specified mark name for Recommended Mark Names, just like any user specified mark name. The user agent does not validate that the usage of the Recommended Mark Name is appropriate or consistent with its description.
"mark_fully_loaded"
The time when the page is considered fully loaded as marked by the developer in their application.
"mark_fully_visible"
The time when the page is considered completely visible to an end-user as marked by the developer in their application.
"mark_above_the_fold"
The time when all of the content in the visible viewport has been presented to the end-user as marked by the developer in their application.
"mark_time_to_user_action"
The time of the first user interaction with the page during or after a navigation, such as scroll or click, as marked by the developer in their application.
No Return Value
Exceptions
Throws
a
SYNTAX_ERR
exception
if
the
markName
argument
is
the
same
name
as
an
attribute
in
the
PerformanceTiming
interface.
clearMarks
method
If
the
markName
argument
is
not
specified,
this
method
removes
all
marks
and
their
associated
DOMHighResTimeStamp
time
values.
If
the
markName
argument
is
specified,
this
method
removes
all
DOMHighResTimeStamp
time
values
for
the
given
mark
name.
If the markName argument is specified but the specified markName does not exist, this method will do nothing.
Parameters
in
markName
type
of
DOMString
[optional]
The
name
of
the
mark
whose
DOMHighResTimeStamp
time
values
should
be
cleared.
If
not
specified,
all
marks
will
be
cleared.
No Return Value
No Exceptions
measure
method
This
method
stores
the
DOMHighResTimeStamp
duration
between
two
marks
along
with
the
associated
name
(a
"measure").
The behavior of this method depends on which arguments are specified:
measure()
will
store
the
duration
as
a
DOMHighResTimeStamp
from
navigationStart
to
the
current
time.
measure()
will
store
the
duration
as
a
DOMHighResTimeStamp
from
the
most
recent
occurrence
of
the
start
mark
to
the
current
time.
measure()
will
store
the
duration
as
a
DOMHighResTimeStamp
from
the
most
recent
occurrence
of
the
start
mark
to
the
most
recent
occurrence
of
the
end
mark.
The
startMark
and
endMark
arguments
may
be
the
name
of
one
of
the
attributes
in
the
PerformanceTiming
interface
[Navigation
Timing]
.
In
this
case,
the
value
of
that
attribute
is
used
as
the
DOMHighResTimeStamp
time
value.
Parameters
in
name
type
of
DOMString
The name associated with the measure.
Measure
names
may
be
re-used
within
the
same
document.
Each
call
to
the
measure()
method
stores
a
new
duration
under
the
specified
measure
name.
Measure names live independently from mark names.
in
startMark
type
of
DOMString
[optional] The name of the start mark.
If
specified,
the
most
recent
DOMHighResTimeStamp
time
value
of
the
start
mark
is
used.
If not specified, navigationStart is used.
May
be
the
name
of
one
of
the
attributes
in
the
PerformanceTiming
interface
[Navigation
Timing]
.
In
this
case,
the
value
of
that
attribute
is
used
as
the
start
DOMHighResTimeStamp
time
value.
in
endMark
type
of
DOMString
[optional] The name of the end mark.
If
specified,
the
most
recent
DOMHighResTimeStamp
time
value
of
the
end
mark
is
used.
If
not
specified,
the
current
time
as
a
DOMHighResTimeStamp
is
used.
May
be
the
name
of
one
of
the
attributes
in
the
PerformanceTiming
interface
[Navigation
Timing]
.
In
this
case,
the
value
of
that
attribute
is
used
as
the
end
DOMHighResTimeStamp
time
value.
No Return Value
Exceptions
Throws
a
SYNTAX_ERR
exception
if
the
start
mark
or
end
mark
does
not
exist.
Throws
an
INVALID_ACCESS_ERR
exception
if
either
startMark
or
endMark
argument,
or
both,
have
the
same
name
as
a
PerformanceTiming
attribute
with
a
time
value
of
0.
clearMeasures
method
If
the
measureName
argument
is
not
specified,
this
method
removes
all
measures
and
their
associated
DOMHighResTimeStamp
durations.
If
the
measureName
argument
is
specified,
this
method
removes
all
DOMHighResTimeStamp
durations
for
the
given
measure
name.
If the measureName argument is specified but the specified measureName does not exist, this method will do nothing.
Parameters
in
measureName
type
of
DOMString
[optional]
The
name
of
the
measure
whose
DOMHighResTimeStamp
durations
should
be
cleared.
If
not
specified,
all
measures
will
be
cleared.
No Return Value
No Exceptions
PerformanceMark
Interface
interface PerformanceMark : PerformanceEntry { };
The
PerformanceMark
interface
also
exposes
marks
created
via
the
mark()
method
to
the
Performance
Timeline
[Performance
Timeline]
.
The
PerformanceMark
interface
extends
the
following
attributes
of
the
PerformanceEntry
interface:
The
name
attribute
will
return
the
mark's
name.
The
entryType
attribute
will
return
the
DOMString
mark
.
The
startTime
attribute
will
return
a
DOMHighResTimeStamp
with
the
mark's
time
value
[High
Resolution
Time]
.
The
duration
attribute
will
return
a
DOMHighResTimeStamp
of
value
0.
PerformanceMeasure
Interface
interface PerformanceMeasure : PerformanceEntry { };
The
PerformanceMeasure
interface
also
exposes
measures
created
via
the
measure()
method
to
the
Performance
Timeline
[Performance
Timeline]
.
The
PerformanceMeasure
interface
extends
the
following
attributes
of
the
PerformanceEntry
interface:
The
name
attribute
will
return
the
measure's
name.
The
entryType
attribute
will
return
the
DOMString
measure
.
The
startTime
attribute
will
return
a
DOMHighResTimeStamp
with
the
measure's
start
mark
[High
Resolution
Time]
.
The
duration
attribute
will
return
a
DOMHighResTimeStamp
with
the
duration
of
the
measure.
Vendor-specific proprietary user agent extensions are discouraged. If such extensions are needed, e.g. for experimental purposes, vendors must use the following extension mechanisms:
If the extension to be added is a Standard Mark Name , the Standard Mark Name must:
The time values stored within the interface must monotonically increase to ensure they are not affected by adjustments to the system clock. The difference between any two chronologically recorded time values must never be negative. The user agent must record the system clock at the beginning of the navigation and define subsequent time values in terms of a monotonic clock measuring time elapsed from the beginning of the navigation.
This section is non-normative.
The interfaces defined in this specification expose potentially sensitive timing information on specific JavaScript activity of a page. However, unlike other interfaces defined in the Performance Timeline , the interfaces defined in this specification do not have any restrictions on sharing timing information through script. This is because the web platform has been designed with the invariant that any script included on a page has the same access as any other script included on that page regardless of the origin of the script.
Thanks to Karen Anderson, Tony Gentilcore, Nic Jansma, James Simonsen, Steve Souders, Sigbjorn Vik, and Jason Weber for their useful comments that led to changes to this specification and their contributions to this work.