Performance/Guides/Create new frontend metrics

There are a couple of ways that you can add extra metrics to a page to get more useful performance data.
== Element timings ==
In Chrome and Chromium based browsers the Element Timing API can be used to collect information on when elements are painted on the screen for the user. The performance team have tested it and the metrics match what we collect when we record a video of the screen.
With the element timings you can target a specific image or other element and know when its painted. This is useful when you do changes so you can keep track of when things are painted on the screen.
=== Add ===
To measure an element you need to annotate the HTML, so that the browser know it should measure that specific element. You annotate your element by adding an attribute named elementtiming. You give your element attribute a name/id and then the browser can collect that information.
Here's an example of what the HTML would look like if you want to know when a image or a paragraph is painted:
<img... elementtiming='my-image'/>
This is text I care about.
To test that it works, you can open a browser that supports element timings, open the JavaScript console and copy/paste the following (after you loaded the page):
const observer = new PerformanceObserver((list) => {
 const perfEntries = list.getEntries();
 for (let entries of perfEntries) {
 console.log(entries);
 }
});
observer.observe({type: 'element', buffered: true});
If it works it will log the something like this to your console:
{
renderTime: 1158.7400000134949
loadTime: 1073.9300000132062
intersectionRect: DOMRectReadOnly {x: 94, y: 50, width: 500, height: 433, top: 50, …}
identifier: "my-image"
naturalWidth: 1000
naturalHeight: 865
id: ""
element: img
url: "https://upload.wikimedia.org/my/image.png"
name: "image-paint"
entryType: "element"
startTime: 1158.7400000134949
duration: 0
}
=== Collect from real users ===
At the moment we don't automatically pickup element timing metrics in our Navigation Timing extension but that is maybe something we can do in the future.
=== Collect from synthetic testing ===
At the moment WebPageTest do not pickup element timings automatically but we can add that see T243878. 
The other tests that we run with sitespeed.io/WebPageReplay automatically picks up element timings. When you added them you will be able to see them in the WebPageReplay dashboard and look for the row named Element Timings. Or you can go directly to that row.
== User timing ==
With the User Timing API you can as a developer collect and measure whatever you want on your page. It's supported in almost all modern browsers.
=== Add a mark ===
A user timing mark is a user defined timing. You give the mark a name and the browser will remember when you marked it (the time is relative to the page started to load (navigationStart)). Using marks you can measure specific tasks that your web page is doing by marking a start and an end.
Remember that all browsers doesn't support the User Timing API, you need to verify that it exists before you use it:
if ( window.performance && performance.mark ) {
 performance.mark( 'myMark' );
}
Verify that it worked by getting the entries in your browser console:
window.performance.getEntriesByType('mark');
That will return an array with the performance marks on that page. Verify that your mark exists. If your mark is named myMark it should look something like this:
[{detail: null, name: "myMark", entryType: "mark", startTime: 519.5649999950547, duration: 0}]
=== Collect from real users ===
At the moment we don't support automatically collecting User Timings.
=== Collect from synthetic testing ===
Browsertime/sitespeed.io automatically picks up user timings.
==== sitespeed.io ====
Sitespeed.io picks up all user marks (and measurements). 
You can see the span (min/median/max) of each user timing on the page summary. 
And if you go to a individual run and choose metrics, there's a table that show all your user timings.
And the Page drill down also have a graph showing user timing data.
Category:Wikimedia Performance