"Performance marks: the missing manual, Part 1"
Tags: javascript, performance, usertimingapi, perfmatters
Published: 2018-01-01 23:45:44

---
title:  "Performance marks: the missing manual, Part 1"
tags:  javascript, performance, user-timing-api, perfmatters
published: true
cover_image: https://thepracticaldev.s3.amazonaws.com/i/xkeyyxabc52qrk8qyfcv.jpg
description: "Ever stumbled upon User Timing API but didn't quite get what is it for or how to use it? Let's dive into this: how to use `performance.mark()`, what common practices are, and what are some cool tricks marks do enable."
---

Image by [Viktoriiaa](https://www.shutterstock.com/g/viktoriiaa)

[`performance.mark()`](https://developer.mozilla.org/en-US/docs/Web/API/Performance/mark) is a part of [User Timing API](https://developer.mozilla.org/en-US/docs/Web/API/User_Timing_API). Arguably, it is the most useful performance-related method we have in browsers now because its application possibilities are far beyond just “mark this timestamp for me”, especially when combined with deep understanding of how browsers actually work. 

## Basic Usage
To use it, just call `performance.mark()` and pass mark name as a parameter within any JavaScript code:
```javascript
performance.mark("fontsLoaded");
```
This will add a [PerformanceMark](https://developer.mozilla.org/en-US/docs/Web/API/PerformanceMark) to the [performance timeline](https://www.w3.org/TR/performance-timeline/#performance-timeline).
To delete a mark, make a call to the `performance.clearMarks()` method:
```javascript
performance.clearMarks("fontsLoaded");
```
JS one-liners inlined directly into HTML will do as well:
```html
<p>What a beautiful text</p>
<script>
  performance.mark("afterText");
</script>
```
I know what you're thinking: “Hey JS is mostly single-threaded, can I mark the moment when browser reaches *exact line* in the document?”. For the most part, yes, you can. Let's try this out!

## Mark all the things
First, a bit of theory 🤓. [Most of the time](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Using_web_workers), document parsing and JS execution is done in a single thread, with respect for document structure from a first line to the last one. When browser meets, say, a `<link>` to the stylesheet or a script, it pauses execution, downloads the resource it stumbled on, parses and executes it, and only then continues with parsing and executing stuff below. This concept — render-blocking resources — is crucial for achieving fast rendering timings and brilliantly covered by [Ilya Grigorik](https://twitter.com/igrigorik) in his talks and [free online course](https://developers.google.com/web/fundamentals/performance/critical-rendering-path/).

Now, optimizations aside, you may want to know _how much time do you lose due to render being blocked by resources_. Take a look at this snippet:

```html
<html>
  <head>
  <title>Performance marks demo #1</title>
  <script>performance.mark('parsing:css:start');</script>
  <link rel="stylesheet" href="shiny-style.css">
  <script>performance.mark('parsing:css:end');</script>
  </head>
  <body>
    <p>What a beautiful text</p>
  </body>
</html>
```

[Opening this in browser](https://hom3chuk.github.io/perfmarks-demo-1/index.html) will mark two events: the one before stylesheet link, and one after. Check'em out:
![render-blocking CSS performance marks](https://thepracticaldev.s3.amazonaws.com/i/li3j6ec1vlgvav8ug6cc.jpg)
Whoa 😱! It took browser near 80 ms to download, parse and apply our shiny stylesheet, faster than [a blink of an eye](http://bionumbers.hms.harvard.edu/bionumber.aspx?&id=100706&ver=4&trm=blink). Not so fast for one CSS selector we have there, though.

On the bright side, you now know how to measure for how long rendering is blocked by resources. Wait, did I say `measure`?

### Measures
We all [❤️ math](https://xkcd.com/55/), don't we? But when it comes to actual calculations, we like to make computers do it. Performance marks are no exception and we have handy [`performance.measure()`](https://developer.mozilla.org/en-US/docs/Web/API/Performance/measure) method which, well, _measures_ distance between two marks. Let's add it to our HTML snippet:
```html
<html>
  <head>
  <title>Performance marks demo #2: measures</title>
  <script>performance.mark('parsing:css:start');</script>
  <link rel="stylesheet" href="shiny-style.css">
  <script>
    performance.mark('parsing:css:end');
    performance.measure('blocking-styles', 'parsing:css:start', 'parsing:css:end');
  </script>
  </head>
  <body>
    <p>What a beautiful text</p>
  </body>
</html>
```

Now let's see [how this measure thing looks in browser](https://hom3chuk.github.io/perfmarks-demo-1/index-2.html):
![performance measure example](https://thepracticaldev.s3.amazonaws.com/i/nu4gjhrhbfq5k3gg4iz1.jpg)
Cool, we can now just look at `measure`'s `duration` instead of doing math. Yay computers!

## Mark-fu
Me myself as well as some other developers prefer to use some kind of namespacing when setting up marks to organize taxonomy across different mark and event types:

```javascript
performance.mark("fonts:roboto:load");
performance.mark("parsing.head.start");
```

That is, you just separate namespaces with colon or dot and your marks are getting nice structure. Of course you can use anything ([🐰, anyone?](https://hom3chuk.github.io/perfmarks-demo-1/index-3.html)) to separate namespaces, not just dots and colons. There is no solid standard about performance marks namespacing and you are welcome to use whatever separator you want to use, pretty much like CSV format.

## Retrieve your marks
### During development
Getting performance marks with your browser is easy:

1. Go to the developer tools of your browser
2. Switch to JavaScript Console tab
3. Put down `performance.getEntriesByType('mark')` and here they are!

### From real users
Now, the hardest part is to retrieve these marks from your real users, and we're at Taki care about marks a lot. We are currently developing Marks'n'Measures Dashboard, although marks are already visible in our Waterfall view.

[Webpagetest](https://www.webpagetest.org), as well as WPT-based [MachMetrics](https://www.machmetrics.com/) & [SpeedCurve](https://speedcurve.com), do support performance marks to some extent and you can get a glance at marks in Performance Timeline with these tools. If you haven't heard about WPT, go check it out: it is one of the best #webperf tools out there, it's completely free yet carries a whole lot of features. I literally use it on a *daily* basis and do love it.

## Who use it?
There's a couple of examples of performance marks in wild I know of: Google Maps and Optimizely. They set up marks throughout their client-side JS, so if you have GMaps embeded, or do run some Optimizely experiments, check out performance entries with your devtools on those pages!

## What next?

In coming articles I will show a lot more of advanced level _mark-fu_ and tell you about differences across different browsers in marks handling (you didn't even thought everything will work the same across all the browserzoo we're developing to, do you?😉).

If you know some other examples of marks in the wild other than Google Maps and Optimizely, please do share them in comments below. And of course I encourage you to share your experience with marks, would love to take a look at other devs approach to marks.

And remember, #perfmatters!