The backend is fast. P95 server-rendered HTML lands in 90 ms. Synthetic checks all green. A customer screenshots a 14-second blank screen on a product page on mobile. You can’t reproduce it on your dev machine, you can’t reproduce it on the staging URL, and the access log shows their request hit the server in 110 ms. The 14 seconds happened in the browser — third-party scripts, oversized images, a render-blocking polyfill, an exception in a deferred chunk — and you have zero visibility into it. Faro is what closes that gap. Every page load on a real customer’s device emits Web Vitals, navigation timing, console errors, unhandled promise rejections, and trace context that ties back to the server-side span. On a single VM running the Faro collector, the “we have no idea what’s happening in the browser” problem disappears.
What’s happening
Faro is the Grafana Labs frontend RUM stack. It has two parts: a small JavaScript SDK you ship in your web app (@grafana/faro-web-sdk) and the Grafana Alloy / Faro Collector that receives the events. The SDK captures Web Vitals (LCP, FID, INP, CLS), navigation timings, JS errors, console messages, custom events, and OpenTelemetry browser spans. It posts batches to the collector over CORS-enabled HTTPS. The collector fans out: web events go to Loki as structured logs, spans go to Tempo, vital metrics go to Mimir.
Faro vs. an external SaaS provider: you keep the data, you scale the collector horizontally as load grows, and you get the same Grafana correlation hooks you already use for backend tracing (clicking a slow page-load drills into the matching backend span in Tempo). The trade-off is you operate the pipeline — collector capacity, sample rate, PII redaction.
How to verify
Collector is healthy:
curl -s http://10.60.0.51:12347/-/ready
# expect: ready
A synthetic event reaches the collector and flows to Loki:
curl -X POST http://10.60.0.51:12347/collect \
-H 'Content-Type: application/json' \
-d '{
"meta":{"sdk":{"name":"test","version":"0.0.0"},"app":{"name":"synthetic","release":"0"}},
"logs":[{"message":"hello from synthetic","level":"info","timestamp":"2026-05-14T12:00:00Z"}]
}'
# Query Loki
logcli query '{service_name="synthetic"} |~ "hello from synthetic"' --limit 5
Browser SDK is connected — in your app’s DevTools Network tab, you should see POST /collect returning 204 every 5 seconds during page interaction.
The fix
Save as /root/setup-faro-collector.sh and run on the Ubuntu 22.04 VM. Installs Grafana Alloy (Faro Receiver lives there as a component), NGINX in front with TLS and aggressive CORS, UFW, and a hardened systemd unit.
#!/usr/bin/env bash
set -euo pipefail
### Ubuntu 22.04 Grafana Faro collector (via Alloy) installer
### Receives browser RUM events, fans out to Loki/Tempo/Mimir
if [[ "$(id -u)" -ne 0 ]]; then
echo "Run as root."
exit 1
fi
# === EDIT ===
NODE_IP="10.60.0.51"
PUBLIC_DOMAIN="faro.example.com"
ALLOY_VERSION="1.3.0"
LOKI_URL="https://loki.example.com/loki/api/v1/push"
TEMPO_URL="tempo.example.com:443"
MIMIR_URL="https://mimir.example.com/api/v1/push"
INGEST_AUTH_USER="faro"
INGEST_AUTH_PASS="CHANGE_ME_INGEST"
ALLOWED_ORIGINS="https://app.example.com,https://www.example.com"
# =============
echo
echo "========================================"
echo "Faro collector ${PUBLIC_DOMAIN}"
echo "========================================"
export DEBIAN_FRONTEND=noninteractive
apt-get update
apt-get -y dist-upgrade
apt-get -y install curl wget ca-certificates gnupg lsb-release \
ufw fail2ban unattended-upgrades chrony jq tar gzip \
iproute2 net-tools dnsutils socat nginx certbot python3-certbot-nginx \
apache2-utils htop iotop
systemctl enable --now chrony
echo "==> Grafana repo"
mkdir -p /etc/apt/keyrings/
wget -q -O - https://apt.grafana.com/gpg.key | gpg --dearmor > /etc/apt/keyrings/grafana.gpg
echo "deb [signed-by=/etc/apt/keyrings/grafana.gpg] https://apt.grafana.com stable main" \
> /etc/apt/sources.list.d/grafana.list
apt-get update
apt-get -y install alloy=${ALLOY_VERSION}-1
echo "==> UFW"
ufw default deny incoming
ufw default allow outgoing
ufw allow 22/tcp
ufw allow 80/tcp
ufw allow 443/tcp
ufw --force enable
echo "==> SSH hardening"
sed -i 's|^[#[:space:]]*PermitRootLogin.*|PermitRootLogin prohibit-password|' /etc/ssh/sshd_config
sed -i 's|^[#[:space:]]*PasswordAuthentication.*|PasswordAuthentication no|' /etc/ssh/sshd_config
systemctl restart ssh
cat > /etc/fail2ban/jail.d/sshd.local <<'FAIL2BAN'
[sshd]
enabled = true
port = ssh
backend = systemd
maxretry = 4
findtime = 10m
bantime = 1h
FAIL2BAN
systemctl enable --now fail2ban
cat > /etc/apt/apt.conf.d/20auto-upgrades <<'AUTO'
APT::Periodic::Update-Package-Lists "1";
APT::Periodic::Unattended-Upgrade "1";
AUTO
echo "==> Sysctl"
cat > /etc/sysctl.d/99-alloy.conf <<'SYSCTL'
fs.file-max = 2097152
net.core.somaxconn = 8192
net.ipv4.ip_local_port_range = 10240 65535
SYSCTL
sysctl --system
cat > /etc/security/limits.d/99-alloy.conf <<'LIMITS'
alloy soft nofile 200000
alloy hard nofile 200000
LIMITS
echo "==> Writing /etc/alloy/config.alloy"
mkdir -p /etc/alloy
cat > /etc/alloy/config.alloy <<EOF
// Grafana Alloy — Faro receiver pipeline
// Receives browser RUM, fans out to Loki / Tempo / Mimir
logging {
level = "info"
format = "logfmt"
}
// === Receiver ===
faro.receiver "default" {
server {
listen_address = "0.0.0.0"
listen_port = 12347
cors_allowed_origins = ["${ALLOWED_ORIGINS//,/\",\"}"]
api_key = "${INGEST_AUTH_PASS}"
max_allowed_payload_size = "5MB"
rate_limiting {
rate = 100
}
}
sourcemaps {
location {
path = "/var/lib/alloy/sourcemaps"
minified_path_prefix = "https://app.example.com/static/"
}
}
output {
logs = [loki.write.faro.receiver]
traces = [otelcol.exporter.otlp.tempo.input]
}
}
// === Loki destination for logs/events ===
loki.write "faro" {
endpoint {
url = "${LOKI_URL}"
basic_auth {
username = "loki-ingest"
password = "CHANGE_ME_LOKI"
}
}
external_labels = {
source = "faro",
}
}
// === Tempo destination for browser spans ===
otelcol.exporter.otlp "tempo" {
client {
endpoint = "${TEMPO_URL}"
tls {
insecure = false
}
}
}
// === Optional Mimir destination for derived Web Vitals metrics ===
// Faro receiver does not yet emit Prometheus directly; if you want Web Vitals
// as metrics, use a recording rule from Loki logs or a downstream conversion.
EOF
mkdir -p /var/lib/alloy/sourcemaps
chown -R alloy:alloy /var/lib/alloy
echo "==> Override systemd to point at our config"
mkdir -p /etc/systemd/system/alloy.service.d
cat > /etc/systemd/system/alloy.service.d/override.conf <<'OVR'
[Service]
ExecStart=
ExecStart=/usr/bin/alloy run --server.http.listen-addr=127.0.0.1:12345 --storage.path=/var/lib/alloy /etc/alloy/config.alloy
LimitNOFILE=200000
OVR
systemctl daemon-reload
systemctl enable --now alloy
echo "==> NGINX with CORS + TLS"
cat > /etc/nginx/sites-available/faro <<EOF
upstream faro_collector { server 127.0.0.1:12347; keepalive 32; }
map \$http_origin \$cors_origin {
default "";
"~^https://(app|www)\\.example\\.com\$" "\$http_origin";
}
server {
listen 80;
server_name ${PUBLIC_DOMAIN};
location /.well-known/acme-challenge/ { root /var/www/html; }
location / { return 301 https://\$host\$request_uri; }
}
server {
listen 443 ssl http2;
server_name ${PUBLIC_DOMAIN};
ssl_certificate /etc/letsencrypt/live/${PUBLIC_DOMAIN}/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/${PUBLIC_DOMAIN}/privkey.pem;
ssl_protocols TLSv1.2 TLSv1.3;
client_max_body_size 5m;
proxy_read_timeout 30s;
location /collect {
if (\$request_method = OPTIONS) {
add_header Access-Control-Allow-Origin \$cors_origin always;
add_header Access-Control-Allow-Methods "POST, OPTIONS" always;
add_header Access-Control-Allow-Headers "Content-Type, x-faro-session-id, x-api-key" always;
add_header Access-Control-Max-Age 86400 always;
return 204;
}
add_header Access-Control-Allow-Origin \$cors_origin always;
proxy_set_header Host \$host;
proxy_set_header X-Real-IP \$remote_addr;
proxy_pass http://faro_collector/collect;
}
location /-/ready {
proxy_pass http://faro_collector/-/ready;
}
}
EOF
ln -sf /etc/nginx/sites-available/faro /etc/nginx/sites-enabled/faro
rm -f /etc/nginx/sites-enabled/default
nginx -t
systemctl reload nginx
echo "==> Waiting for collector"
for i in {1..60}; do
if curl -fs http://127.0.0.1:12347/-/ready >/dev/null 2>&1; then break; fi
sleep 2
done
echo
echo "========================================"
echo "DONE"
echo "========================================"
echo
ss -lntp | grep -E ':(80|443|12345|12347)\b' || true
echo
echo "Next: certbot --nginx -d ${PUBLIC_DOMAIN}"
echo "Ingest key (for SDK config): ${INGEST_AUTH_PASS}"
echo "Allowed origins: ${ALLOWED_ORIGINS}"
Browser SDK: React / Vite / Webpack app
In your web app, install the SDK and initialize it before your app renders. Critical: the SDK must run before any code you want instrumented, so put it in the entry point.
npm install @grafana/faro-web-sdk @grafana/faro-web-tracing
// src/observability/faro.ts
import {
initializeFaro,
getWebInstrumentations,
ConsoleInstrumentation,
} from '@grafana/faro-web-sdk';
import { TracingInstrumentation } from '@grafana/faro-web-tracing';
export const faro = initializeFaro({
url: 'https://faro.example.com/collect',
apiKey: import.meta.env.VITE_FARO_API_KEY,
app: {
name: 'checkout-web',
version: import.meta.env.VITE_APP_VERSION,
environment: import.meta.env.MODE,
},
instrumentations: [
...getWebInstrumentations({
captureConsole: true,
captureConsoleDisabledLevels: ['debug'],
}),
new ConsoleInstrumentation({
disabledLevels: ['debug'],
}),
new TracingInstrumentation({
instrumentationOptions: {
propagateTraceHeaderCorsUrls: [
/https:\/\/api\.example\.com\/.*/,
],
},
}),
],
sessionTracking: {
samplingRate: 1,
persistent: true,
},
beforeSend: (event) => {
// Strip PII from URLs before they leave the browser
if (event.payload && typeof event.payload === 'object') {
const p = event.payload as Record<string, unknown>;
if (typeof p.url === 'string') {
p.url = p.url.replace(/email=[^&]+/g, 'email=REDACTED');
}
}
return event;
},
});
// src/main.tsx — entry point
import './observability/faro'; // MUST be first import
import React from 'react';
import ReactDOM from 'react-dom/client';
import App from './App';
ReactDOM.createRoot(document.getElementById('root')!).render(<App />);
Add VITE_FARO_API_KEY to your .env (or your deploy pipeline’s secret store) — same value you set in the Alloy config above. The version field becomes critical for diffs: pin it to the build SHA so you can compare error rates pre- and post-deploy.
Dashboards in Grafana
Three queries get you 80% of the value:
- Web Vitals over time — Loki:
{source="faro", app="checkout-web"} | json | __error__="" | type="measurement" | values_lcp != "" | unwrap values_lcp [5m] - Error rate by browser — Loki:
sum by (browser_name) ( rate({source="faro", app="checkout-web"} | json | kind="exception" [5m]) ) - Trace from slow page-load to backend — in Grafana’s Explore view, click any Faro session log entry with a
traceId, then “View trace” to jump to the matching Tempo trace.
Sample rate is the operational lever you’ll touch most often. Start at 100% in pre-production, drop to 10-25% in production. Faro’s sessionTracking.samplingRate is applied per session (so all events from a sampled session arrive together, which keeps trace correlation intact), unlike per-event sampling.
Run frontend RUM on Stack Harbor’s managed cloud compute with the collector, alerting on Web Vitals regression, and SDK rollout coordinated through our deployment management team — or scope it together if you want the observability tier delivered end-to-end.