Fictura
Performance

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/browser

Start 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.

src/client.tsx
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 loadFrom navigation start to the load event, with the navigation type.
NavigationA client-side route change, until no call has been in flight for a second (30 seconds at most).
CallsEvery fetch and XMLHttpRequest, as children of the page or navigation they were made on. Calls to Fictura itself are never traced.
Web VitalsLCP, 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.

VitalGoodNeeds improvementWeight
LCP2.5 s4 s30%
INP200 ms500 ms30%
CLS0.10.2515%
FCP1.8 s3 s15%
TTFB800 ms1.8 s10%

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

OptionDefaultWhat it does
apiKeynoneYour app's publishable key. Without it nothing is sent.
apiBasehttps://api.fictura.coWhere spans go.
release, environmentnone, productionShown on every span, and the filters on the Performance page.
serviceNamewebThe service name on the Performance page.
tracesSampleRate1The 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.
routeNameids maskedA function from a URL to the route name.
enabledtruefalse 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.

On this page