Grafana Faro : architecture et installation

1. Architecture #

Un SDK, un récepteur, la stack LGTM.

Composants #

Grafana Faro est un SDK JavaScript open source qui collecte les signaux front-end et les envoie à un récepteur : le composant faro.receiver de Grafana Alloy (en auto-hébergé) ou Grafana Cloud Frontend Observability. Les données sont stockées dans Loki et Tempo, puis exploitées dans Grafana.

2. Le récepteur Alloy #

Recevoir, router, exposer.

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

Erreur Courante : Le récepteur est exposé sur Internet (les navigateurs l'appellent) : restreignez cors_allowed_origins à vos domaines, placez-le derrière un reverse proxy avec limitation de débit, et surveillez son volume.

3. Le SDK #

npm ou CDN.

Avec 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
  ],
});

Sans outil de build (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>

Bonne Pratique : Renseignez toujours version et environment : ce sont eux qui permettent de comparer deux déploiements et de filtrer la préproduction.

À savoir : Pour React, Angular ou Vue, des intégrations dédiées (par exemple @grafana/faro-react) ajoutent les noms de routes et les erreurs de rendu.