DocumentationGrafana CloudMonitor applicationsFrontend ObservabilityInstrumentPerformance Instrumentation

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 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) interfaces 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.

Navigation event

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 execute resources after DOMContentLoaded, domComplete - domInteractive
• domContentLoadHandlerTime: the time to execute delayed scripts after the load event, loadEventEnd - loadEventStart
• onLoadTime: the time it takes to execute scripts which are delayed to be started after 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

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

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
• 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.

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 Copy

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 Copy

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
});