Using the Performance API

A fundamental requirement of web performance is a precise and consistent definition of time. The DOMHighResTimeStamp type (a double) is used by all performance interfaces to hold such time values. Additionally, there must be a way to create a timestamp for a specific point in time; this is done with the now() method.

Web performance interfaces are defined in a suite of standards. The base interface for these standards is the Performance interface and its methods and properties are extended by different standards. This guide describes how to use the Performance interfaces that are defined in the High-Resolution Time standard. Other web performance guides (listed in the See also section) describe how to use additional methods and properties of the Performance interface.

High precision timing

High precision timing is achieved by using the DOMHighResTimeStamp type for time values. The unit is milliseconds and should be accurate to 5 µs (microseconds). However, if the browser is unable to provide a time value accurate to 5 microseconds (because of hardware or software constraints, for example), the browser can represent the value as a time in milliseconds accurate to a millisecond.

The following code example shows the use of DOMHighResTimeStamp and the Performance.now() method. The now() method returns a timestamp (of type DOMHighResTimeStamp) that is a discrete point in time. By calling this method before and after a task, the time it takes to do the task can be measured.

function calculate_time() {
  var startTime;
  var endTime;

  startTime = performance.now();
  do_task();
  endTime = performance.now();

  return (endTime - startTime);
}

Serializing the Performance object

JSON serialization of the Performance object is done via the toJSON() method. In the following example, JSON serialization for the Performance, Performance.timing and Performance.navigation objects is printed in the object element.

function print_json() {
  var json;
  var o = document.getElementsByTagName("output")[0];

  if (window.performance.toJSON === undefined) {
    json = "window.performance.toJSON() is NOT supported";
    o.innerHTML += json + "<br>";
  } else {
    var s;
    json = window.performance.toJSON();

    // Print the performance object
    s = JSON.stringify(json);
    o.innerHTML = "<p>performance = " + s + "</p>";

    // Print the performance.timing and performance.navigation objects
    var perf = JSON.parse(s);

    var timing = perf.timing;
    o.innerHTML += "<p>performance.timing = " + JSON.stringify(timing) + "</p>";

    var navigation = perf.navigation;
    o.innerHTML += "<p>performance.navigation = " + JSON.stringify(navigation) + "</p>";
  }
}

Specifications

The interfaces described in this document are defined in the High Resolution Time standard which has two levels:

Interoperability

As shown in the Performance interface's Browser Compatibility table, most of the Performance interfaces are broadly implemented by desktop browsers.

See also