User Timing API
The User Timing
interface allows the developer to create application specific timestamps
that are part of the browser's performance timeline. There are two types of user defined timing event types: the "mark
" event type
and the "measure
" event type
.
mark
events are named by the application and can be set at any location in an application. measure
events are also named by the application but they are placed between two marks thus they are effectively a midpoint between two marks.
This document provides an overview of the mark
and measure
performance event types
including the four User Timing
methods that extend the Performance
interface. For more details and example code regarding these two performance event types and the methods, see Using the User Timing API.
Performance marks
A performance mark
is a named performance entry
that is created by the application. The mark is a timestamp
in the browser's performance timeline.
Creating a performance mark
The performance.mark()
method is used to create a performance mark. The method takes one argument, the name of the mark (for example performance.mark("mark-1")
).
The mark's
performance entry
will have the following property values:
Retrieving performance marks
The Performance
interface has three methods that can be used to retrieve a mark:
performance.getEntries()
-
Returns all
performance entries
in the performance timeline. Finding onlymark
entries requires checking each entry'sentryType
for "mark
". performance.getEntriesByName(name, entryType)
-
Returns all
performance entries
in the performance timeline with the specifiedname
andentryType
, thus setentryType
to "mark
" to get all marks (and setname
accordingly to retrieve more specific entries). performance.getEntriesByType(entryType)
-
Returns all
performance entries
in the performance timeline with the specifiedentryType
, thus setentryType
to "mark
" to get all marks.
Removing performance marks
To remove a specific mark from the performance timeline, call performance.clearMarks(name)
where name
is the name of the mark(s) you want removed. If this method is called with no arguments, all mark type entries will be removed from the performance timeline.
Performance measures
measure
events are also named by the application but they are placed between two marks thus they are effectively a midpoint between two marks.
Creating a performance measure
A measure
is created by calling performance.measure(measureName, startMarkName, endMarkName)
where measureName
is the measure's name and startMarkName
and endMarkName
are the start and end names, respectively, of the marks the measure will be placed between (in the performance timeline).
The measure's
performance entry
will have the following property values:
Retrieving performance measures
The Performance
interface has three methods that can be used to retrieve a measure:
performance.getEntries()
-
Returns all
performance entries
in the performance timeline. Finding themeasure
entries requires checking each entry'sentryType
for "measure
". performance.getEntriesByName(name, entryType)
-
Returns all
performance entries
in the performance timeline with the specifiedname
andentryType
, thus setentryType
to "measure
" to get all measures (and setname
accordingly to retrieve more specific entries). performance.getEntriesByType(entryType)
-
Returns all
performance entries
in the performance timeline with the specifiedentryType
, thus setentryType
to "measure
" to get all measures.
Removing performance measures
To remove a specific measure from the performance timeline, call performance.clearMeasures(name)
where name
is the name of the measure(s) you want removed. If this method is called with no arguments, all measure type entries will be removed from the performance timeline.
Interoperability
As shown in the Performance
interface's Browser Compatibility table, the User Timing
methods are broadly implemented by desktop and mobile browsers (the only exceptions are Desktop Safari and Mobile Safari, however the Safari Technology Preview 24 has support).
To test your browser's support for this API, run the perf-api-support
application.
See also
- User Timing Standard; W3C Editor's Draft
- CanIUse data
- A Primer for Web Performance Timing APIs; Xiaoqian Wu; W3C Editor's Draft