Introduction to the User Timing API

The User Timing API allows you to easily measure how much of time your code blocks or events take so that you can find any performance bottlenecks in your code. With the API, you can find out how measure the time long tasks like your network requests take.

The API is supported in a vast majority of browsers, for browsers that don’t support it, you can use this ploy-fill. 

User Timing Interface

The main methods of the API are given below:

mark()

The mark method is used to set a named point in your code to measure from.

example: window.performance.mark('start');

In the above example, we create a mark named “start”

clearMarks()

clearMarks is used to discard existing marks, it takes in an optional parameter, if no parameter is supplied, it discards all existing marks

example: window.performance.clearMarks(); //discards all marks
         window.performance.clearMarks('start'); //discards mark named 'start'

measure()

measure is used to calculate the duration between different marks, it can also measure the duration between marks are events defined in the Navigation Timing Interface.

It takes in 3 parameters, 

window.performance.measure('parameter1', 'parameter2', 'parameter3');

//parameter1 is the name of the measure
//parameter2 is the mark to start from
//parameter3 is the mark to end on

example: window.performance.measure('calculateTime', 'start', 'end')

//here calculateTime is the name given to the measure, start and end and the two marks to measure from.

clearMeasure()

Like clearMark(), clearMeasure() is used to get rid of existing measures

example: window.performance.clearMeasure(); //discards all measures
         window.performance.clearMeasure('calculateMeasure'); //discards measure named 'calculateMeasure'

getEntries

The getEntries methods are used to get the marks and measures so that you can access the values.

You can get an array of all the existing marks using the getEntriesByType method and passing in marks

window.performance.getEntriesByType('marks');

Similarly, you can get the array of existing measures by passing in measure

 window.performance.getEntriesByType('measure');

Using the getEntriesByName method, you can get a single mark of measure

window.performance.getEntriesByName('mark_fully_loaded');

Example App

Lets use the user timing api in an simple example. The example can be found here.

In this example, we populate an array with a 1000 random integers and then use 2 types of for loops, we then measure how long each for loop took.

First we create the function to return an array filled with 1000 random integers.

// function to create an array filled with 1000 random ints			function randomArray() {					
// create a temp array				
    var tmp_arr = [];				
    // loop through 1000 times				
    for(var i=0; i<1000; i++){					
        // create a temp random number					
        var tmp = Math.floor(Math.random()*1000 +1);					             
        tmp_arr.push(tmp); // add to array				
     }				              
     return tmp_arr;			
}

Next we get the array, and create a mark, run the first for loop and then create another mark after the end of the loop

// get the array
var array = randomArray();

// create a mark for the first type of for loop        window.performance.mark('for1');        

for(var j = 0,len = array.length; j<len; j++){              
     console.log(array[j])        
}

// mark the end of the for loop
.performance.mark('endfor1');

Similarly, we do the same for the other type of for loop

 // create a mark for the second type of for loop
window.performance.mark('for2');
 
array.forEach(x=>console.log(x));

// mark the end of the for loop
window.performance.mark('endfor2'); 

Next create the measures for both the for loops

// next we need to measure the times
window.performance.measure('for1_measure', 'for1', 'endfor1');
window.performance.measure('for2_measure', 'for2', 'endfor2');

Next get the duration and update the UI

// get the measurements and display the output
            
var measure1 = window.performance.getEntriesByName('for1_measure');
var measure2 = window.performance.getEntriesByName('for2_measure');

document.getElementById('time1').innerHTML = measure1[0].duration + "ms";
document.getElementById('time2').innerHTML = measure2[0].duration + "ms";