User Timing

1. Introduction

This section is non-normative.

Web developers need the ability to assess and understand the performance characteristics of their applications. While JavaScript [ECMA-262] provides a mechanism to measure application latency (retrieving the current timestamp from the Date.now() method), the precision of this timestamp varies between user agents.

This document defines the PerformanceMark and PerformanceMeasure interfaces, and extensions to the Performance interface, which expose a high precision, monotonically increasing timestamp so that developers can better measure the performance characteristics of their applications.

async function run() {
  performance.mark("startTask1");
  await doTask1(); // Some developer code
  performance.mark("endTask1");

  performance.mark("startTask2");
  await doTask2(); // Some developer code
  performance.mark("endTask2");

  // Log them out
  const entries = performance.getEntriesByType("mark");
  for (const entry of entries) {
    console.table(entry.toJSON());
  }
}
run();

element.addEventListener("click", e => {
  const component = getComponent(element);
  fetch(component.url).then(() => {
    element.textContent = "Updated";
    const updateMark = performance.mark("update_component", {
      detail: {component: component.name},
    });
    performance.measure("click_to_update_component", {
      detail: {component: component.name},
      start: e.timeStamp,
      end: updateMark.startTime,
    });
  });
});

2. User Timing

2.1. Extensions to the Performance interface

The Performance interface and DOMHighResTimeStamp are defined in [HR-TIME-2]. The PerformanceEntry interface is defined in [PERFORMANCE-TIMELINE-2].

dictionary PerformanceMarkOptions {
    any detail;
    DOMHighResTimeStamp startTime;
};

dictionary PerformanceMeasureOptions {
    any detail;
    (DOMString or DOMHighResTimeStamp) start;
    DOMHighResTimeStamp duration;
    (DOMString or DOMHighResTimeStamp) end;
};

partial interface Performance {
    PerformanceMark mark(DOMString markName, optional PerformanceMarkOptions markOptions = {});
    undefined clearMarks(optional DOMString markName);
    PerformanceMeasure measure(DOMString measureName, optional (DOMString or PerformanceMeasureOptions) startOrMeasureOptions = {}, optional DOMString endMark);
    undefined clearMeasures(optional DOMString measureName);
};

2.1.1. mark() method

Stores a timestamp with the associated name (a "mark"). It MUST run these steps:

1. Run the PerformanceMark constructor and let entry be the newly created object.
2. Queue a PerformanceEntry entry.
3. Add entry to the performance entry buffer.
4. Return entry.

2.1.1.1. PerformanceMarkOptions dictionary

detail

Metadata to be included in the mark.

startTime

Timestamp to be used as the mark time.

2.1.2. clearMarks() method

Removes the stored timestamp with the associated name. It MUST run these steps:

1. If markName is omitted, remove all PerformanceMark objects from the performance entry buffer.
2. Otherwise, remove all PerformanceMark objects listed in the performance entry buffer whose name is markName.
3. Return undefined.

2.1.3. measure() method

Stores the DOMHighResTimeStamp duration between two marks along with the associated name (a "measure"). It MUST run these steps:

1. If startOrMeasureOptions is a PerformanceMeasureOptions object and at least one of start, end, duration, and detail exist, run the following checks:
   1. If endMark is given, throw a TypeError.
   2. If startOrMeasureOptions’s start and end members are both omitted, throw a TypeError.
   3. If startOrMeasureOptions’s start, duration, and end members all exist, throw a TypeError.
2. Compute end time as follows:
   1. If endMark is given, let end time be the value returned by running the convert a mark to a timestamp algorithm passing in endMark.
   2. Otherwise, if startOrMeasureOptions is a PerformanceMeasureOptions object, and if its end member exists, let end time be the value returned by running the convert a mark to a timestamp algorithm passing in startOrMeasureOptions’s end.
   3. Otherwise, if startOrMeasureOptions is a PerformanceMeasureOptions object, and if its start and duration members both exist:
      1. Let start be the value returned by running the convert a mark to a timestamp algorithm passing in start.
      2. Let duration be the value returned by running the convert a mark to a timestamp algorithm passing in duration.
      3. Let end time be start plus duration.
   4. Otherwise, let end time be the value that would be returned by the Performance object’s now() method.
3. Compute start time as follows:
   1. If startOrMeasureOptions is a PerformanceMeasureOptions object, and if its start member exists, let start time be the value returned by running the convert a mark to a timestamp algorithm passing in startOrMeasureOptions’s start.
   2. Otherwise, if startOrMeasureOptions is a PerformanceMeasureOptions object, and if its duration and end members both exist:
      1. Let duration be the value returned by running the convert a mark to a timestamp algorithm passing in duration.
      2. Let end be the value returned by running the convert a mark to a timestamp algorithm passing in end.
      3. Let start time be end minus duration.
   3. Otherwise, if startOrMeasureOptions is a DOMString, let start time be the value returned by running the convert a mark to a timestamp algorithm passing in startOrMeasureOptions.
   4. Otherwise, let start time be 0.
4. Create a new PerformanceMeasure object (entry) with this’s relevant realm.
5. Set entry’s name attribute to measureName.
6. Set entry’s entryType attribute to DOMString "measure".
7. Set entry’s startTime attribute to start time.
8. Set entry’s duration attribute to the duration from start time to end time. The resulting duration value MAY be negative.
9. Set entry’s detail attribute as follows:
   1. If startOrMeasureOptions is a PerformanceMeasureOptions object and startOrMeasureOptions’s detail member exists:
      1. Let record be the result of calling the StructuredSerialize algorithm on startOrMeasureOptions’s detail.
      2. Set entry’s detail to the result of calling the StructuredDeserialize algorithm on record and the current realm.
   2. Otherwise, set it to null.
10. Queue a PerformanceEntry entry.
11. Add entry to the performance entry buffer.
12. Return entry.

2.1.3.1. PerformanceMeasureOptions dictionary

detail

Metadata to be included in the measure.

start

Timestamp to be used as the start time or string to be used as start mark.

duration

Duration between the start and end times.

end

Timestamp to be used as the end time or string to be used as end mark.

2.1.4. clearMeasures() method

Removes stored timestamp with the associated name. It MUST run these steps:

1. If measureName is omitted, remove all PerformanceMeasure objects in the performance entry buffer.
2. Otherwise remove all PerformanceMeasure objects listed in the performance entry buffer whose name is measureName.
3. Return undefined.

2.2. The PerformanceMark Interface

The PerformanceMark interface also exposes marks created via the Performance interface’s mark() method to the Performance Timeline.

[Exposed=(Window,Worker)]
interface PerformanceMark : PerformanceEntry {
  constructor(DOMString markName, optional PerformanceMarkOptions markOptions = {});
  readonly attribute any detail;
};