Web
@fictura/browser traces your website's page loads, navigations and fetch calls, and reports Core Web Vitals from every visitor.
One init() call in your website's client code, and every page load becomes a trace: the load itself, the fetch and XMLHttpRequest calls it made, and, through traceparent, your backend's spans for those calls. Each page also reports its Core Web Vitals.
Install
npm install @fictura/browserStart it on the client
Call init() once, in code that runs only in the browser. On the server it does nothing, so importing it during server rendering is safe.
import { init } from "@fictura/browser";
init({
apiKey: "gk_…", // your app's publishable key, from Setup
release: import.meta.env.VITE_RELEASE,
environment: import.meta.env.MODE === "production" ? "production" : "development",
tracePropagationTargets: ["https://api.example.com"], // your API, so its spans join the trace
});Your API must allow the traceparent header in CORS. FastAPI's CORSMiddleware with allow_headers=["*"] already does.
What gets recorded
| What it measures | |
|---|---|
| Page load | From navigation start to the load event, with the navigation type. |
| Navigation | A client-side route change, until no call has been in flight for a second (30 seconds at most). |
| Calls | Every fetch and XMLHttpRequest, as children of the page or navigation they were made on. Calls to Fictura itself are never traced. |
| Web Vitals | LCP, INP, CLS, FCP and TTFB from Google's web-vitals library, with the element behind LCP and CLS where the browser says. |
Routes are named with ids masked, so /design/8f3a…/edit reads as /design/:id/edit. Pass routeName to name them yourself.
The score
The Web tab scores each page from 0 to 100 the way Sentry and Lighthouse do: each vital's p75 is scored on a curve where Google's "good" threshold scores 90 and "needs improvement" scores 50, then the five are weighted.
| Vital | Good | Needs improvement | Weight |
|---|---|---|---|
| LCP | 2.5 s | 4 s | 30% |
| INP | 200 ms | 500 ms | 30% |
| CLS | 0.1 | 0.25 | 15% |
| FCP | 1.8 s | 3 s | 15% |
| TTFB | 800 ms | 1.8 s | 10% |
Pages are ranked by opportunity: how much your overall score would rise if that page scored 100, weighted by how often it loads. The five pages with the most to gain are also checked every hour: a vital rated needs improvement or poor there, over 7 days and at least 10 samples, files a Web Vitals performance issue.
Options
| Option | Default | What it does |
|---|---|---|
apiKey | none | Your app's publishable key. Without it nothing is sent. |
apiBase | https://api.fictura.co | Where spans go. |
release, environment | none, production | Shown on every span, and the filters on the Performance page. |
serviceName | web | The service name on the Performance page. |
tracesSampleRate | 1 | The share of page loads and navigations traced, from 0 to 1. |
tracePropagationTargets | [] | Origins, hosts (*.example.com works) or regular expressions that receive traceparent. Nothing else ever does. |
routeName | ids masked | A function from a URL to the route name. |
enabled | true | false turns everything off. |
setUser(id) adds a user id to every span (never an email). flush() sends what is waiting.
Privacy
No cookies, no query strings, no request or response bodies, no user agent and no IP address are sent. Spans leave in small batches, and on page hide with keepalive so a closing tab doesn't lose them.
Tracing
One trace from a tap in your app, through your backend, to its database and model calls. The SDKs record it by default; the Performance page shows where the time goes.
Monitors and performance issues
Thresholds you set on any span metric, the built-in alerts, the slow patterns Fictura finds in your traces on its own, and cron monitors.