Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Make User Timing overview page more overviewy #21853

Merged
merged 6 commits into from
Nov 10, 2022
Merged

Make User Timing overview page more overviewy #21853

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
5435a16
Make User Timing overview page more overviewy
Elchi3 Oct 26, 2022
e3a0db1
Move examples section, add spec section
Elchi3 Oct 27, 2022
ec25a40
Rewrite more
Elchi3 Oct 28, 2022
478c3a6
Shorten intro
Elchi3 Oct 28, 2022
6cb136e
simplify
Elchi3 Oct 28, 2022
98e7768
Merge branch 'main' into user-timing-overview
Elchi3 Oct 31, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
117 changes: 70 additions & 47 deletions files/en-us/web/api/user_timing_api/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,80 +10,103 @@ tags:

{{DefaultAPISidebar("User Timing API")}}

The **`User Timing`** interface allows the developer to create application specific {{domxref("DOMHighResTimeStamp","timestamps")}} that are part of the browser's _performance timeline_. There are two types of _user_ defined timing event types: the "`mark`" {{domxref("PerformanceEntry.entryType","event type")}} and the "`measure`" {{domxref("PerformanceEntry.entryType","event type")}}.
The **User Timing API** allows you measure the performance of applications using [high-precision timestamps](/en-US/docs/Web/API/DOMHighResTimeStamp) that are part of the browser's performance timeline. There are two types of timing performance entries:

**`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.
- {{domxref("PerformanceMark")}} entries are marks that you can name and add at any location in an application.
- {{domxref("PerformanceMeasure")}} entries are time measurements between two marks.

This document provides an overview of the `mark` and `measure` {{domxref("PerformanceEntry.entryType","performance event types")}} including the four `User Timing` methods that extend the {{domxref("Performance")}} interface. For more details and example code regarding these two performance event types and the methods, see [Using the User Timing API](/en-US/docs/Web/API/User_Timing_API/Using_the_User_Timing_API).
This document provides an overview how to work with the mark and measure performance entry types. For more details and example code, see [Using the User Timing API](/en-US/docs/Web/API/User_Timing_API/Using_the_User_Timing_API).

## Performance `marks`
## Performance marks

A performance **`mark`** is a _named_ {{domxref("PerformanceEntry","performance entry")}} that is created by the application. The mark is a {{domxref("DOMHighResTimeStamp","timestamp")}} in the browser's _performance timeline_.
Interface: {{domxref("PerformanceMark")}}

### Creating a performance `mark`
{{InheritanceDiagram("PerformanceMark")}}

The {{domxref("Performance.mark","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 `PerformanceMark` interface has the following read-only properties (directly or inherited from {{domxref("PerformanceEntry")}}):

The `mark's` {{domxref("PerformanceEntry","performance entry")}} will have the following property values:
- {{domxref("PerformanceMark.detail","detail")}} provides additional information about the mark.
- {{domxref("PerformanceEntry.duration","duration")}} is always `0` (a mark has no duration).
- {{domxref("PerformanceEntry.entryType","entryType")}} is always `"mark"`.
- {{domxref("PerformanceEntry.name","name")}} is the name given when the mark was created.
- {{domxref("PerformanceEntry.startTime","startTime")}} is the {{domxref("DOMHighResTimeStamp","timestamp")}} when `mark()` was called.

- {{domxref("PerformanceEntry.entryType","entryType")}} - set to "`mark`".
- {{domxref("PerformanceEntry.name","name")}} - set to the "`name`" given when the mark was created.
- {{domxref("PerformanceEntry.startTime","startTime")}} - set to the {{domxref("DOMHighResTimeStamp","timestamp")}} when `mark()` was called.
- {{domxref("PerformanceEntry.duration","duration")}} - set to "`0`" (a mark has no _duration_).
### Creating performance marks

### Retrieving performance `marks`
- {{domxref("Performance.mark","performance.mark()")}} adds a performance mark to the browser's performance timeline.
- {{domxref("PerformanceMark.PerformanceMark", "PerformanceMark()")}} constructs a `PerformanceMark` object that isn't added to the browser's performance timeline.

The {{domxref("Performance")}} interface has three methods that can be used to retrieve a mark:
### Retrieving performance marks

- {{domxref("Performance.getEntries","performance.getEntries()")}}
- : Returns all {{domxref("PerformanceEntry","performance entries")}} in the performance timeline. Finding only `mark` entries requires checking each entry's {{domxref("PerformanceEntry.entryType","entryType")}} for "`mark`".
- {{domxref("Performance.getEntriesByName","performance.getEntriesByName(name, entryType)")}}
- : Returns all {{domxref("PerformanceEntry","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).
- {{domxref("Performance.getEntriesByType","performance.getEntriesByType(entryType)")}}
- : Returns all {{domxref("PerformanceEntry","performance entries")}} in the performance timeline with the specified `entryType`, thus set `entryType` to "`mark`" to get all marks.
- [`performance.getEntriesByType("mark")`](/en-US/docs/Web/API/Performance/getEntriesByType) gets all marks.
- [`performance.getEntriesByName("myMarker", "mark")`](/en-US/docs/Web/API/Performance/getEntriesByName) gets all marks with the name "myMarker".
- {{domxref("Performance.getEntries","performance.getEntries()")}} gets all entries (filter as needed).

### Removing performance `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.clearMarks("myMarker")`](/en-US/docs/Web/API/Performance/clearMarks) removes the performance marker with the name "myMarker".
- [`performance.clearMarks()`](/en-US/docs/Web/API/Performance/clearMarks) removes all performance markers.

## Performance `measures`
## 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.
Interface: {{domxref("PerformanceMeasure")}}

### Creating a performance `measure`
{{InheritanceDiagram("PerformanceMeasure")}}

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 `PerformanceMeasure` interface has the following read-only properties (directly or inherited from {{domxref("PerformanceEntry")}}):

The `measure's` {{domxref("PerformanceEntry","performance entry")}} will have the following property values:
- {{domxref("PerformanceMeasure.detail","detail")}} provides additional information about the measure.
- {{domxref("PerformanceEntry.duration","duration")}} is a {{domxref("DOMHighResTimeStamp")}} that is the duration of the measure (typically, the end mark timestamp minus the start mark timestamp).
- {{domxref("PerformanceEntry.entryType","entryType")}} is always `"measure"`.
- {{domxref("PerformanceEntry.name","name")}} is the name given when the measure was created.
- {{domxref("PerformanceEntry.startTime","startTime")}} is the {{domxref("DOMHighResTimeStamp","timestamp")}} when `measure()` was called.

- {{domxref("PerformanceEntry.entryType","entryType")}} - set to "`measure`".
- {{domxref("PerformanceEntry.name","name")}} - set to the "`name`" given when the measure was created.
- {{domxref("PerformanceEntry.startTime","startTime")}} - set to the {{domxref("DOMHighResTimeStamp","timestamp")}} when `measure()` was called.
- {{domxref("PerformanceEntry.duration","duration")}} - set to a {{domxref("DOMHighResTimeStamp")}} that is the duration of the measure (typically, the end mark timestamp minus the start mark timestamp).
### Creating performance measures

### Retrieving performance `measures`
- [`performance.measure(measureName, startMarkName, endMarkName)`](/en-US/docs/Web/API/Performance/measure) creates a measure 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 {{domxref("Performance")}} interface has three methods that can be used to retrieve a measure:
### Retrieving performance measures

- {{domxref("Performance.getEntries","performance.getEntries()")}}
- : Returns all {{domxref("PerformanceEntry","performance entries")}} in the performance timeline. Finding the `measure` entries requires checking each entry's {{domxref("PerformanceEntry.entryType","entryType")}} for "`measure`".
- {{domxref("Performance.getEntriesByName","performance.getEntriesByName(name, entryType)")}}
- : Returns all {{domxref("PerformanceEntry","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).
- {{domxref("Performance.getEntriesByType","performance.getEntriesByType(entryType)")}}
- : Returns all {{domxref("PerformanceEntry","performance entries")}} in the performance timeline with the specified `entryType`, thus set `entryType` to "`measure`" to get all measures.
- [`performance.getEntriesByType("measure")`](/en-US/docs/Web/API/Performance/getEntriesByType) gets all measures.
- [`performance.getEntriesByName("myMeasure", "measure")`](/en-US/docs/Web/API/Performance/getEntriesByName) gets all measures with the name "myMeasure".
- {{domxref("Performance.getEntries","performance.getEntries()")}} gets all entries (filter as needed).

### Removing performance `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.
- [`performance.clearMeasures("myMeasure")`](/en-US/docs/Web/API/Performance/clearMeasures) removes the performance measure with the name "myMeasure".
- [`performance.clearMeasures()`](/en-US/docs/Web/API/Performance/clearMeasures) removes all performance measures.

## Interoperability
## Examples

As shown in the {{domxref("Performance")}} interface's [Browser Compatibility](/en-US/docs/Web/API/Performance#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](https://developer.apple.com/safari/technology-preview/release-notes/#r24)).
### Measuring login duration

To test your browser's support for this API, run the [`perf-api-support`](https://mdn.github.io/dom-examples/performance-apis/perf-api-support.html) application.
Typically, you identify the most critical paths of your application and measure how long it takes from start to finish. For example, you can measure how long it takes to login:

```js
// Place at a location in the code that starts login
performance.mark("login-started");

// Place at a location in the code that finishes login
performance.mark("login-finished");

// Measure login duration
const loginMeasure = performance.measure(
"login-duration",
"login-started",
"login-finished"
);

// Send to analytics endpoint
// or log to the console
console.log(loginMeasure.duration);
```

## Specifications

- [User Timing specification](https://w3c.github.io/user-timing/)

## See also

- [User Timing Standard](https://w3c.github.io/user-timing/); W3C Editor's Draft
- [CanIUse data](https://caniuse.com/#search=user-timing)
- [A Primer for Web Performance Timing APIs](https://siusin.github.io/perf-timing-primer/); Xiaoqian Wu; W3C Editor's Draft
- [Using the User Timing API](/en-US/docs/Web/API/User_Timing_API/Using_the_User_Timing_API)
- {{domxref("PerformanceMark")}}
- {{domxref("PerformanceMeasure")}}