Documentationbreadcrumb arrow Grafana Cloudbreadcrumb arrow Monitor applicationsbreadcrumb arrow Frontend Observabilitybreadcrumb arrow Instrumentbreadcrumb arrow Performance Instrumentation
Grafana Cloud

Track navigation and resource performance

The Faro Web SDK Performance Instrumentation automatically instruments website navigation (page loading and rendering) and resources (JavaScript, CSS, images, and other files) to help you identify performance bottlenecks and make improvements.

Getting started

Performance Instrumentation is enabled by default, no further work is needed.

Performance instrumentation explained

The Faro Web SDK uses browser APIs to retrieve detailed performance metrics and calculates, enriches, and sends custom metrics as faro.performance.navigation and faro.performance.resource events. Faro creates a unique ID per event to map resources to navigation events and order navigation events in a session.

The PerformanceNavigationTiming (MDN Web Docs) interface provides metrics on loading and rendering a single full document, for example, opening a page, reloading a page, or following a link to another page.

The PerformanceResourceTiming (MDN Web Docs) interface provides detailed network data for loading resources, for example, loading JavaScript, CSS, images, or fonts.

Timestamp diagram listing faro specific navigation and resource timestamps in the order in which they’re recorded for fetching and rendering of a document

The faro.performance.navigation contains all metrics from faro.performance.resource event and the following metrics and properties:

Metrics

  • duration: the full navigation time, loadEventEnd - startTime

  • pageLoadTime: the time to load and render a page, domComplete - fetchStart

  • documentParsingTime: the time the browser needs to parse the HTML document and to construct the Document Object Model (DOM), domInteractive - (domLoading - timeOrigin)

  • domProcessingTime: the time to load and process all resources after the document has been parsed and the Document-Object-Model (DOM) is build. domComplete - domInteractive

  • domContentLoadHandlerTime: the time to execute the document load handler, loadEventEnd - loadEventStart

    Usually frameworks and libraries wait for the DOMContentLoaded event before they start to execute their code. This timing can tell how long this takes.

  • onLoadTime: the time it takes to process the load event loadEventEnd - loadEventStart

  • ttfb: the time from making the request to receiving the first byte from server, responseStart - activationStart

Properties

  • faroNavigationId: unique ID for the navigation
  • faroPreviousNavigationId: unique ID for the previous navigation, or unknown
  • type: the navigation type, back_forward,navigate,prerender,reload
  • visibilityState: the visibility of the page during the navigation

The visibilityState property can be useful to remove noise and get accurate results when filtering out hidden navigation, because browsers prioritize visible/foreground work and tabs loaded in the background are usually slower.

Resource event

Note

The instrumentation only sends events initiated by calls to the fetch method or initiated by a XMLHttpRequest.

The faro.performance.resource event contains the following metrics and properties:

Metrics

  • duration: the full resource load time, responseEnd - startTime
  • dnsLookupTime the DNS lookup time, domainLookupEnd - domainLookupStart
  • tcpHandshakeTime: the TCP handshake time, connectEnd - connectStart
  • tlsNegotiationTime: the TLS negotiation time, requestStart - secureConnectionStart
  • redirectTime: the time to follow all redirects, redirectEnd - redirectStart
  • requestTime: the request time, responseStart - requestStart
  • responseTime: the response time, responseEnd - responseStart
  • fetchTime: the time to fetch a resource without redirects, responseEnd - fetchStart
  • serviceWorkerTime: the ServiceWorker processing time, fetchStart - workerStart
  • ttfb: the time from making the request to receiving the first byte from server, responseStart - requestStart

Properties

  • name: the resource URL
  • initiatorType: the element, not media type, that triggered the resource download
  • protocol: the network protocol used to fetch the resource
  • decodedBodySize: the size in octets of the message body after removing content encoding
  • encodedBodySize: the size in octets of the payload body before removing any applied content encodings
  • transferSize: the size in octets of the fetched resource, including both the response header fields and the response payload body
  • cacheHitStatus: the type of cache the resource was loaded from:
    • cache: direct cache hit
    • conditionalFetch: loaded via a 304
    • fullLoad: loaded from the server
  • renderBlockingStatus: the render block status of a resource which has the blocking="render" attribute:
    • blocking the resource potentially blocks rendering
    • non-blocking the resource doesn’t block rendering
    • unknown: the renderBlockingStatus property is not available in Firefox and Safari
  • responseStatus: the HTTP response status code returned when fetching a resource. This property is not available in Firefox and Safari and is set to unknown for those browsers.
  • visibilityState: the visibility of the page during the navigation

Disable the performance instrumentation

You can disable the performance instrumentation by setting enablePerformanceInstrumentation to false in the settings object in the getWebInstrumentations function when initializing Faro.

Disabling the performance instrumentation is generally not recommended because:

  • You lose insights into the rendering and resource load performance of your site
  • It may impact other features in the Frontend Observability app
ts 
initializeFaro({
  url: 'https://my-domain.my-tld/collect/{app-key}',
  app: {
    name: 'my-app',
  },
  instrumentations: [
    ...getWebInstrumentations({
      enablePerformanceInstrumentation: false,
    }),
  ],
});

Enable or disable tracking of all resource events

If you want to track all resources, set trackResources to true in the Faro configuration (trackResources: true). If you do not want tracking any resources at all, set trackResources to false.

ts 
initializeFaro({
  url: 'https://my-domain.my-tld/collect/{app-key}',
  app: {
    name: 'my-app',
  },
  instrumentations: [
    ...getWebInstrumentations({
      enablePerformanceInstrumentation: false,
    }),
  ],
  trackResources: true, // or false to turn off resource tracking
});