---
title: "Track navigation and resource performance | Grafana Cloud documentation"
description: "Faro automatic performance instrumentation to help identify performance bottlenecks and make performance improvements."
---

> For a curated documentation index, see [llms.txt](/llms.txt). For the complete documentation index, see [llms-full.txt](/llms-full.txt).

# 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)](https://developer.mozilla.org/en-US/docs/Web/API/PerformanceNavigationTiming) 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)](https://developer.mozilla.org/en-US/docs/Web/API/PerformanceResourceTiming) 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 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
- `httpHost`: the host from the resource URL, or `unknown` if the URL can’t be parsed (for example, `data:` or `blob:` URLs)
- `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 ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```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 ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

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