Grafana Faro: architecture and installation

1. Architecture #

One SDK, one receiver, the LGTM stack.

Components #

Available in: ✓ OSS ✓ Enterprise ✓ Cloud Self-hosted collection through Alloy; Frontend Observability in Grafana Cloud

Grafana Faro is an open source JavaScript SDK that collects front-end signals and sends them to a receiver: Grafana Alloy's faro.receiver component (self-hosted) or Grafana Cloud Frontend Observability. Data is stored in Loki and Tempo, then used in Grafana.

2. The Alloy receiver #

Receive, route, expose.

Configuration #

faro.receiver "front" {
  server {
    listen_address       = "0.0.0.0"
    listen_port          = 12347
    cors_allowed_origins = ["https://boutique.example.org"]
    api_key              = "change-moi"        // facultatif : le SDK l'envoie dans x-api-key
    max_allowed_payload_size = "5MiB"
  }
  output {
    logs   = [loki.write.default.receiver]
    traces = [otelcol.exporter.otlp.tempo.input]
  }
}

loki.write "default" {
  endpoint { url = "http://loki:3100/loki/api/v1/push" }
}

otelcol.exporter.otlp "tempo" {
  client {
    endpoint = "tempo:4317"
    tls { insecure = true }
  }
}

Common mistake: The receiver is exposed on the Internet (browsers call it): restrict cors_allowed_origins to your domains, put it behind a reverse proxy with rate limiting, and monitor its volume.

3. The SDK #

npm or CDN.

With npm #

npm install @grafana/faro-web-sdk @grafana/faro-web-tracing

import { initializeFaro, getWebInstrumentations } from '@grafana/faro-web-sdk';
import { TracingInstrumentation } from '@grafana/faro-web-tracing';

initializeFaro({
  url: 'https://faro.example.org/collect',
  apiKey: 'change-moi',
  app: { name: 'boutique', version: '2.4.1', environment: 'production' },
  instrumentations: [
    ...getWebInstrumentations(),          // erreurs, console, Web Vitals, sessions, vues
    new TracingInstrumentation(),         // traces fetch/XHR
  ],
});

Without a build tool (CDN) #

<script src="https://unpkg.com/@grafana/faro-web-sdk@^1/dist/bundle/faro-web-sdk.iife.js"></script>
<script>
  window.GrafanaFaroWebSdk.initializeFaro({
    url: 'https://faro.example.org/collect',
    app: { name: 'vitrine', version: '1.0.0', environment: 'production' },
  });
</script>

Good practice: Always set version and environment: they let you compare two deployments and filter out staging.

Good to know: For React, Angular or Vue, dedicated integrations (for example @grafana/faro-react) add route names and rendering errors.