Using the 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 entry types: the "mark" entry type and the "measure" entry 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 shows how to create mark and measure performance entry types and how to use User Timing methods (which are extensions of the Performance interface) to retrieve and remove entries from the browser's performance timeline.
A live version of the examples is available on GitHub, as is the source code. Pull requests, enhancement requests and bug reports are welcome.
A performance mark is a named performance entry that is created by the application at some location in an application. The mark is a timestamp in the browser's performance timeline.
The performance.mark() method is used to create a performance mark. The method takes one argument, the name of the mark, as shown in the following example.
function create_marks(ev) {
if (performance.mark === undefined) {
log("Create Marks: performance.mark Not supported", 0);
return;
} else {
log("Create marks", 0);
performance.mark("mark-1");
do_work(50000);
performance.mark("mark-2");
do_work(50000);
performance.mark("mark-2");
var marks = ["mark-1", "mark-2", "mark-2"];
for (var i=0; i < marks.length; i++)
log("... Created mark = " + marks[i], 0);
}
The Performance interface has three methods to retrieve marks. The following examples shows how to use each of these methods (performance.getEntries(), performance.getEntriesByType(entryType), and performance.getEntriesByName(name, entryType) ) to retrieve one or more marks.
function display_marks(ev) {
if (performance.getEntries === undefined) {
log("Display Marks: performance.getEntries Not supported", 0);
return;
}
log("Display marks", 0);
var entries = performance.getEntries();
var j=0;
for (var i=0; i < entries.length; i++) {
if (entries[i].entryType == "mark") {
if (j == 0) { log("= getEntries()", 0); j++ }
log("... [" + i + "] = " + entries[i].name, 0);
}
}
entries = performance.getEntriesByType("mark");
for (var i=0; i < entries.length; i++) {
if (i == 0) log("= getEntriesByType('mark')", 0);
log("... [" + i + "] = " + entries[i].name, 0);
}
entries = performance.getEntriesByName("mark-1","mark");
for (var i=0; i < entries.length; i++) {
if (i == 0) log("= getEntriesByName('mark-1', 'mark')", 0);
log("... " + entries[i].name, 0);
}
entries = performance.getEntriesByName("mark-2","mark");
for (var i=0; i < entries.length; i++) {
if (i == 0) log("= getEntriesByName('mark-2', 'mark')", 0);
log("... " + entries[i].name, 0);
}
}
The performance.clearMarks() method is used to remove one or more marks from the browser's performance timeline. If a specific mark name is given to this method, only the mark(s) with that name will be removed. However, if no argument is given, then all performance entries of type "mark" will be removed from the performance timeline. The following example demonstrates both uses of this method.
function clear_marks(obj) {
if (performance.clearMarks === undefined) {
log("Clear Marks: performance.clearMarks Not supported", 0);
return;
}
log("Clear marks", 0);
if (typeof obj == "string") {
log("... cleared '" + obj + "' mark(s)", 0);
performance.clearMarks(obj);
} else {
log("... cleared All marks", 0);
performance.clearMarks();
}
}
A measure performance entry type is named by the application and its timestamp is placed between two named marks thus a measure is effectively a midpoint between two marks in the browser's performance timeline.
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).
function create_measures(ev) {
if (performance.measure === undefined) {
log("Create Measures: performance.measure Not supported", 1);
return;
}
log("Create measures", 1);
performance.mark("mark-A");
do_work(50000);
performance.mark("mark-B");
performance.mark("mark-C");
do_work(50000);
performance.mark("mark-D");
performance.measure("measure-1", "mark-A", "mark-B");
performance.measure("measure-2", "mark-C", "mark-D");
var marks = ["mark-A", "mark-B", "mark-C", "mark-D"];
for (var i=0; i < marks.length; i++)
log("... Created mark = " + marks[i], 1);
var measures = ["measures-1", "measures-2"];
for (var i=0; i < measures.length; i++)
log("... Created measure = " + measures[i], 1);
}
The Performance interface has three methods to retrieve measures. The following examples shows how to use each of these methods (performance.getEntries(), performance.getEntriesByType(entryType), and performance.getEntriesByName(name, entryType)) to retrieve one or more measures.
function display_measures(ev) {
if (performance.getEntries === undefined) {
log("Display Measures: performance.getEntries Not supported", 1);
return;
}
log("Display measures", 1);
var entries = performance.getEntries();
var j=0;
for (var i=0; i < entries.length; i++) {
if (entries[i].entryType == "measure") {
if (j == 0) { log("= getEntries()", 1); j++ }
log("... [" + i + "] = " + entries[i].name, 1);
}
}
entries = performance.getEntriesByType("measure");
for (var i=0; i < entries.length; i++) {
if (i == 0) log("= getEntriesByType('measure')", 1);
log("... [" + i + "] = " + entries[i].name, 1);
}
entries = performance.getEntriesByName("measure-1","measure");
for (var i=0; i < entries.length; i++) {
if (i == 0) log("= getEntriesByName('measure-1', 'measure')", 1);
log("... " + entries[i].name, 1);
}
entries = performance.getEntriesByName("measure-2","measure");
for (var i=0; i < entries.length; i++) {
if (i == 0) log("= getEntriesByName('measure-2', 'measure')", 1);
log("... " + entries[i].name, 1);
}
}
The performance.clearMeasures() method is used to remove measures from the browser's performance timeline. If the method is called with a specific measure name, all measures with that name will be removed from the timeline. If the method is called with no arguments, all performance entries with a type of "measure" will be removed from the timeline. The following examples shows both uses of this method.
function clear_measures(obj) {
if (performance.clearMeasures === undefined) {
log("Clear Measures: performance.clearMeasures Not supported", 1);
return;
}
log("Clear measures", 1);
if (typeof obj == "string") {
log("... cleared '" + obj + "' measure(s)", 1);
performance.clearMeasures(obj);
} else {
log("... cleared All measures", 1);
performance.clearMeasures();
}
}
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 no support for Desktop Safari and Mobile Safari).
See also