Copyright
©
2011
2012
W3C
®
(
MIT
,
ERCIM
,
Keio
),
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
a
the
second
Last
Call
Working
Draft
of
"User
Timing".
Please
send
comments
to
public-web-perf@w3.org
(
archived
)
with
[UserTiming]
at
the
start
of
the
subject
line
by
22
September
2011
.
.
A diff document with the previous draft is available.
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 Working Draft 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
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
introduces
defines
the
UserTiming
PerformanceMark
and
PerformanceMeasure
interfaces,
and
extensions
to
the
Performance
interface,
which
exposes
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> </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.getEntries("marks"); for (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
DOM
is
used
to
refer
to
the
API
set
made
available
to
scripts
in
Web
applications,
and
does
not
necessarily
imply
the
existence
of
an
actual
Document
object
or
of
any
other
Node
objects
as
defined
in
the
DOM
Core
specifications.
[DOM
Level
3
Core]
A DOM attribute is said to be getting when its value is being retrieved (such as by author script), and is said to be setting when a new value is assigned to it.
The term "JavaScript" is used to refer to ECMA262, rather than the official term ECMAScript, since the term JavaScript is more widely known. [ECMA262]
This section is non-normative
The
User
Timing
PerformanceMark
interface
gives
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.
UserTiming
Performance
Interface
partial interface { const unsigned short PERF_DEVELOPER_MARK = 2; const unsigned short PERF_DEVELOPER_MEASURE = 3; const string = "fullyLoaded"; const string = "fullyVisible"; const string = "aboveTheFold"; const string = "timeToUserAction"; void markName); Array markName); void markName);partial interface Performance { void mark(DOMString markName); Array getMarks(optional DOMString markName); void clearMarks(optional DOMString markName);void endMark); Array measureName); void measureName);void measure(DOMString measureName, optional DOMString startMark, optional DOMString endMark); Array getMeasures(optional DOMString measureName); void clearMeasures(optional DOMString measureName); };
mark
method
This method stores a timestamp with the associated name (a "mark").
Parameters
in
name
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]
.
Standard
Recommended
Mark
Names
The
mark
name
may
be
one
of
Developers
are
encouraged
to
use
the
following
Standard
Mark
Names.
When
using
a
Standard
Recommended
Mark
Name,
the
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
Standard
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.
getMarks
method
If
the
markName
argument
is
not
specified,
this
method
must
return
all
of
the
marks
and
their
associated
timestamps.
DOMHighResTimeStamp
time
values.
If
the
markName
argument
is
specified,
this
method
must
return
all
of
the
timestamps
DOMHighResTimeStamp
time
values
for
the
specified
mark
name.
If the markName argument is specified but it does not exist, this method must return an empty array.
If this method is invoked from a cross-origin script and the Timing-Allow-Origin HTTP response header rules are not met, this method must return an empty array.
Parameters
in
markName
type
of
DOMString
[optional] The name of the mark. If not specified, all marks are returned.
Return Value
Array
If
the
markName
argument
is
not
specified,
the
method
returns
an
associative
Array.
Each
key
in
the
Array
is
a
mark
name.
The
value
associated
with
the
mark
name
is
an
Array
of
timestamps
DOMHighResTimeStamp
time
values
for
that
mark.
In
JSON
notation,
the
data
structure
will
look
similar
to
this:
{
"mark1":
.
[0,
1,
3],
[0.750,
1.125,
3.333],
"mark2":
[2]
[2.125]
}
If
the
markName
argument
is
specified,
and
the
mark
name
exists,
the
method
returns
an
Array
of
timestamps.
DOMHighResTimeStamp
time
values.
In
JSON
notation,
the
data
structure
will
look
similar
to
this:
.
[0,
1,
3]
[0.500,
1.125,
3.750]
If
the
markName
argument
is
specified,
and
the
mark
name
does
not
exist,
the
method
returns
an
empty
Array.
In
JSON
notation,
the
data
structure
will
look
similar
to
this:
[]
.
Timestamps
will
be
listed
in
the
order
that
the
mark()
method
was
called.
The
returned
Array
is
a
copy
of
data
at
the
time
that
the
getMarks()
method
was
called.
If this method is invoked from a cross-origin script and the Timing-Allow-Origin HTTP response header rules are not met, this method must return an empty array.
No Exceptions
clearMarks
method
If
the
markName
argument
is
not
specified,
this
method
removes
all
marks
and
their
associated
timestamps.
DOMHighResTimeStamp
time
values.
If
the
markName
argument
is
specified,
this
method
removes
all
timestamps
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
timestamps
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
(measured
in
milliseconds)
along
with
the
associated
name
(a
"measure").
The behavior of this method depends on which arguments are specified:
measure()
will
store
the
duration
measure()
will
store
the
duration
measure()
will
store
the
duration
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
timestamp.
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
timestamp
DOMHighResTimeStamp
time
value
of
the
start
mark
is
used.
If
not
specified,
fetchStart
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
timestamp.
DOMHighResTimeStamp
time
value.
in
endMark
type
of
DOMString
[optional] The name of the end mark.
If
specified,
the
most
recent
timestamp
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
timestamp.
DOMHighResTimeStamp
time
value.
No Return Value
Exceptions
Throws
a
SYNTAX_ERR
exception
if
the
start
mark
or
end
mark
does
not
exist.
Throws
a
SYNTAX_ERR
exception
if
the
duration
(the
end
mark
timestamp
minus
the
start
mark
timestamp)
is
negative.
Throws
a
an
exception
if
either
SYNTAX_ERR
INVALID_ACCESS_ERR
startMark
or
endMark
argument,
or
both,
have
the
same
name
as
a
PerformanceTiming
attribute
with
a
timestamp
time
value
of
0
[Navigation
Timing]
.
0.
getMeasures
method
If
the
measureName
argument
is
not
specified,
this
method
must
return
all
of
the
measures
and
their
associated
durations.
durations
for
the
specified
measure
name.
If
the
measureName
argument
is
not
specified,
this
method
must
return
all
of
the
durations
for
the
specified
measure
name.
measures
and
their
associated
DOMHighResTimeStamp
durations.
If the measureName argument is specified but it does not exist, this method must return an empty array.
If this method is invoked from a cross-origin script and the Timing-Allow-Origin HTTP response header rules are not met, this method must return an empty array.
Parameters
in
measureName
type
of
DOMString
[optional] The name of the measure to return. If not specified, all measures are returned.
Return Value
Array
If
the
measureName
argument
is
not
specified,
the
method
returns
an
associative
Array.
Each
key
in
the
Array
is
a
measure
name.
The
value
associated
with
the
measure
name
is
an
Array
of
DOMHighResTimeStamp
durations
for
that
measure.
In
JSON
notation,
the
data
structure
will
look
similar
to
this:
{
"measure1":
.
[0,
5,
1],
[0.525,
5.125,
1.125],
"measure2":
[3]
[3.251]
}
If
the
measureName
argument
is
specified,
and
the
measure
name
exists,
the
method
returns
an
Array
of
DOMHighResTimeStamp
durations.
In
JSON
notation,
the
data
structure
will
look
similar
to
this:
[0,
5,
1]
[0.250,
5.125,
1.750].
If
the
measureName
argument
is
specified,
and
the
measure
name
does
not
exist,
the
method
returns
an
empty
Array.
In
JSON
notation,
the
data
structure
will
look
similar
to
this:
[]
.
Durations
will
be
listed
in
the
order
that
the
measure()
method
was
called.
The
returned
Array
is
a
copy
of
data
at
the
time
that
the
getMeasures()
method
was
called.
If this method is invoked from a cross-origin script and the Timing-Allow-Origin HTTP response header rules are not met, this method must return an empty array.
No Exceptions
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 : { }interface PerformanceMark : PerformanceEntry { };
The
PerformanceMark
interface
also
exposes
marks
created
via
the
mark()
method
to
the
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
.
PERF_DEVELOPER_MARK
mark
The
startTime
attribute
will
return
a
DOMHighResTimeStamp
with
the
the
mark's
timestamp.
time
value.
If
a
cross-origin
script
gets
this
attribute
and
the
Timing-Allow-Origin
HTTP
response
header
rules
are
not
met,
this
attribute
must
be
set
to
zero.
The
duration
attribute
will
return
a
DOMHighResTimeStamp
of
value
0.
PerformanceMeasure
Interface
interface PerformanceMeasure : { }interface PerformanceMeasure : PerformanceEntry { };
The
PerformanceMeasure
interface
also
exposes
measures
created
via
the
measure()
method
to
the
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
.
PERF_DEVELOPER_MEASURE
measure
The
startTime
attribute
will
return
the
timestamp
of
a
DOMHighResTimeStamp
with
the
measure's
start
mark.
If
a
cross-origin
script
gets
this
attribute
and
the
Timing-Allow-Origin
HTTP
response
header
rules
are
not
met,
this
attribute
must
be
set
to
zero.
The
duration
attribute
will
return
a
DOMHighResTimeStamp
with
the
duration
of
the
measure.
If
a
cross-origin
script
gets
this
attribute
and
the
Timing-Allow-Origin
HTTP
response
header
rules
are
not
met,
this
attribute
must
be
set
to
zero.
Vendor-specific
proprietary
user
agent
extensions
to
this
specification
are
strongly
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
timestamps
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
timestamps
time
values
must
never
be
negative.
The
user
agent
must
record
the
system
clock
at
the
beginning
of
the
navigation
and
define
subsequent
timestamps
time
values
in
terms
of
a
monotonic
clock
measuring
time
elapsed
from
the
beginning
of
the
navigation.
The
PerformanceMark
and
PerformanceMeasure
interfaces,
and
extensions
to
the
Performance
interface
expose
high
precision
timing
information
of
the
performance
characteristics
of
application
scripts.
To
limit
access
to
these
interfaces,
the
same
origin
policy
is
enforced
by
default
with
the
getMarks
and
getMeasures
methods
returning
empty
Arrays
when
invoked
from
cross-origin
scripts
and
the
startTime
and
duration
attributes
of
the
PerformanceMark
and
PerformanceMeasure
interfaces
being
set
to
zero
when
the
attributes
are
queried
from
cross-origin
scripts.
Developers can explicitly allow timing information to be accessed from cross-origin scripts by adding the Timing-Allow-Origin HTTP response header, which specifies the domains that are allowed to access the timing information.
The terms origin and same origin are defined by The HTTP Origin Header. [IETF RFC 6454]
The term cross-origin is used to mean non same origin .
Server-side applications may return the Timing-Allow-Origin HTTP response header to allow the User Agent to fully expose, to the document origin(s) specified, the values of attributes that would have been set to zero and return values of methods that would have been empty Arrays due to the cross-origin restrictions previously specified in this section.
Timing-Allow-Origin
Response
Header
The
Timing-Allow-Origin
header
indicates
whether
a
resource's
timing
can
be
shared
based
by
returning
the
value
of
the
Origin
request
header
in
the
response.
ABNF:
Timing-Allow-Origin = "Timing-Allow-Origin" ":" origin-list-or-null | "*"
origin-list-or-null
is
defined
by
The
HTTP
Origin
Header.
[IETF
RFC
6454]
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.