Skip to content

Commit

Permalink
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Make User Timing overview page more overviewy (mdn#21853)
Browse files Browse the repository at this point in the history 
* Make User Timing overview page more overviewy

* Move examples section, add spec section

* Rewrite more

* Shorten intro

* simplify
@Elchi3 @OnkarRuikar
Elchi3 authored and OnkarRuikar committed Nov 11, 2022
1 parent 9a2ed94 commit 734dbe2
Showing 1 changed file with 70 additions and 47 deletions.
117 changes: 70 additions & 47 deletions files/en-us/web/api/user_timing_api/index.md
View file
Original file line number Diff line number Diff line change
@@ -10,80 +10,103 @@ tags:

{{DefaultAPISidebar("Performance 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")}}

0 comments on commit 734dbe2

Please sign in to comment.