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.

Performance `marks`

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.

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, 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);
  // Create several performance marks including two with the same name
  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);
}

Retrieving performance `marks`

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);

  // Display each mark using getEntries()
  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);
    }
  }

  // Display each mark using getEntriesByType()
  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);
  }

  // Display each mark using getEntriesName(); must look for each mark separately
  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);
  }
}

Removing performance `marks`

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 {
    // No argument specified so clear all marks
    log("... cleared All marks", 0);
    performance.clearMarks();
  }
}

Performance `measures`

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.

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).

function create_measures(ev) {
  if (performance.measure === undefined) {
    log("Create Measures: performance.measure Not supported", 1);
    return;
  }
  log("Create measures", 1);

  // Create several performance marks
  performance.mark("mark-A");
  do_work(50000);
  performance.mark("mark-B");

  performance.mark("mark-C");
  do_work(50000);
  performance.mark("mark-D");

  // Create some measures
  performance.measure("measure-1", "mark-A", "mark-B");
  performance.measure("measure-2", "mark-C", "mark-D");

  // Log the marks and measures
  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);

}

Retrieving performance `measures`

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);

  // Display each measure using getEntries()
  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);
    }
  }

  // Display each measure using getEntriesByType
  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);
  }

  // Display each measure using getEntriesName() - have to look for each measure separately
  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);
  }
}

Removing performance `measures`

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 {
    // No argument specified so clear all measures
    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).