1. The role of faro.receiver #
The bridge between browser and backend.
The principle #
The Grafana Faro SDK collects JavaScript errors, events, Core Web Vitals and network call traces in the browser. It sends them over HTTP to faro.receiver, which listens on port 12347 by default and turns each item into a log line (to Loki) or a span (to Tempo).
2. A production-ready configuration #
Securing a public endpoint.
config.alloy #
faro.receiver "frontend" {
server {
listen_address = "0.0.0.0"
listen_port = 12347
cors_allowed_origins = ["https://shop.example.com"]
api_key = sys.env("FARO_API_KEY")
rate_limiting {
strategy = "per_app"
rate = 50
}
}
sourcemaps {
download = false
location {
path = "/srv/sourcemaps/{{ .Release }}"
minified_path_prefix = "https://shop.example.com/assets/"
}
}
extra_log_labels = {service_name = "shop-frontend"}
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
}
}
}Configuration validated with alloy validate (Alloy v1.21.3, November 2026).
Settings that matter #
| Setting | Default | Why change it |
|---|---|---|
listen_address | 127.0.0.1 | The browser must reach the receiver: listen on 0.0.0.0 behind a TLS proxy. |
cors_allowed_origins | empty (CORS disabled) | List your domains; ["*"] accepts any site. |
api_key | empty | Requires the X-API-Key header; otherwise HTTP 401. |
rate_limiting | 50 req/s, burst 100, global | per_app isolates each app and environment; beyond that, HTTP 429. |
sourcemaps.download | true | The receiver downloads source maps from the URL sent by the client: turn it off for untrusted traffic and serve them from disk. |
max_allowed_payload_size | 5MiB | Limits request size. |
Don't leave download = true on a public receiver: any client could make Alloy download the URL of its choice.3. What Alloy receives: a real test #
Payload, responses, produced lines.
HTTP responses #
We sent a Faro payload (a log, an event, Web Vitals, an exception and a trace) to Alloy, with loki.echo and otelcol.exporter.debug to display the result:
curl -X POST http://127.0.0.1:12347/collect -H 'Content-Type: application/json' --data @payload.json
# → 401 (missing key)
curl -X POST http://127.0.0.1:12347/collect -H 'X-API-Key: secret-demo' -H 'Origin: http://127.0.0.1:8099' --data @payload.json
# → HTTP/1.1 202 Accepted
# Access-Control-Allow-Origin: http://127.0.0.1:8099Lines sent to Loki #
Each item becomes a logfmt line with a kind field and app, session, page and browser context (excerpt):
labels={service_name="shop-frontend"}
kind=log message="panier validé" level=info app_name=shop-frontend app_version=1.4.2 app_environment=production session_id=s-7f3a page_url=https://shop.example.com/checkout browser_name=Firefox
kind=event event_name=checkout_step event_domain=shop event_data_step=payment …
kind=measurement type=web-vitals cls=0.040000 inp=180.000000 lcp=2310.000000 …
kind=exception type=TypeError value="Cannot read properties of undefined (reading 'price')" stacktrace="TypeError: …\n at computeTotal (https://shop.example.com/assets/app.min.js:1:4821)" …The trace reaches Tempo as an OpenTelemetry span: HTTP POST /api/orders, service.name=shop-frontend, scope @grafana/faro-web-tracing. In Loki, filter errors:
{service_name="shop-frontend"} | logfmt | kind="exception"
quantile_over_time(0.75, {service_name="shop-frontend"} | logfmt | kind="measurement" | unwrap lcp [5m])