User timings with gtag.js

This guide describes how to use gtag.js to measure user timings and send them to Google Analytics.

Learn about the User Timings report.

Overview

Studies have shown that reducing page load time improves the overall user experience of a site. Using Google Analytics, it is possible to track custom timing information to measure performance specific to your site. This is particularly useful for developers to measure the latency, or time spent, making AJAX requests and loading web resources.

Implementation

To measure user timings, use the event command to send a timing_complete event:

gtag('event', 'timing_complete', [parametersObject]);

User timings parameters

The following table summarizes the user timings parameters:

Parameter name Data type Required Description
name string Yes A string to identify the variable being recorded (e.g. 'load').
value integer Yes The number of milliseconds in elapsed time to report to Google Analytics (e.g. 20).
event_category string No A string for categorizing all user timing variables into logical groups (e.g. 'JS Dependencies').
event_label string No A string that can be used to add flexibility in visualizing user timings in the reports (e.g. 'Google CDN').

Examples

The following command sends a user timing event to Google Analytics indicating that it took 3549 milliseconds for the current web page to load all its external JavaScript dependencies:

gtag('event', 'timing_complete', {
  'name': 'load',
  'value': 3549,
  'event_category': 'JS Dependencies'
});

Measuring time

When sending user timing data, you specify the amount of milliseconds spent in the value parameter. It’s up to you to write code to capture this period of time.

The easiest way to do this is to create a timestamp at the beginning of a period of time and create another timestamp at the end of the period. Then you can take the difference between both timestamps to get time spent.

Most modern browsers support the Navigation Timing API, which includes methods on the window.performance object for measuring the performance of web pages through high-resolution time data.

The following example uses the performance.now() method, which returns the amount of time that has elapsed since the page first started loading:

// Feature detects Navigation Timing API support.
if (window.performance) {
  // Gets the number of milliseconds since page load
  // (and rounds the result since the value must be an integer).
  var timeSincePageLoad = Math.round(performance.now());

  // Sends the timing event to Google Analytics.
  gtag('event', 'timing_complete', {
    'name': 'load',
    'value': timeSincePageLoad,
    'event_category': 'JS Dependencies'
  });
}

Sampling considerations

Google Analytics will sample timing events to ensure an equitable distribution of system resources for this feature.

The rate at which timing events are sampled is determined by the total number of pageviews received during the previous day for the property. The following table outlines how the timing sampling rate is determined:

Total pageview count (previous day) Maximum number of timing events that will be processed
0 - 1,000 100
1,000 - 100,000 10% of total pageview count
100,000 - 1,000,000 10,000
1,000,000+ 1% of total pageview count