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:

entryType - set to "mark".
name - set to the "name" given when the mark was created.
startTime - set to the timestamp when mark() was called.
duration - set to "0" (a mark has no duration).

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 only mark entries requires checking each entry's entryType for "mark".
performance.getEntriesByName(name, entryType): Returns all performance entries in the performance timeline with the specified name and entryType, thus set entryType to "mark" to get all marks (and set name accordingly to retrieve more specific entries).
performance.getEntriesByType(entryType): Returns all performance entries in the performance timeline with the specified entryType, thus set entryType 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:

entryType - set to "measure".
name - set to the "name" given when the measure was created.
startTime - set to the timestamp when measure() was called.
duration - set to a DOMHighResTimeStamp that is the duration of the measure (typically, the end mark timestamp minus the start mark timestamp).

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 the measure entries requires checking each entry's entryType for "measure".
performance.getEntriesByName(name, entryType): Returns all performance entries in the performance timeline with the specified name and entryType, thus set entryType to "measure" to get all measures (and set name accordingly to retrieve more specific entries).
performance.getEntriesByType(entryType): Returns all performance entries in the performance timeline with the specified entryType, thus set entryType 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.