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.
Tracing is on by default in every Fictura SDK: the app SDK (@fictura/sdk), the backend SDKs (fictura for Python, @fictura/node) and the browser SDK (@fictura/browser). Point the app's traceparent at your API and one trace runs from the tap to the database. Everything goes over OpenTelemetry's OTLP, so any OpenTelemetry SDK can send to Fictura too.
This page covers the app first, then the backend, then what the Performance page shows.
What gets recorded
| What it measures | |
|---|---|
| App start | From the system starting your app to its first screen. |
| Screen load | From a navigation to the screen being ready, with slow and frozen frames counted. |
| Full display | From a navigation to your own Growth.reportFullyDisplayed() call, within 30 seconds. |
| Network calls | Every fetch and XMLHttpRequest, as children of the screen they were made on. |
Each screen visit is one trace, so a slow screen shows the calls behind it.
Name your screens
With Expo Router, the SDK names screens by itself from the route. If a prettified path reads badly, name it:
Growth.init({
// ...
screenNames: { "/(tabs)/index": "Home" },
});Without Expo Router, call Growth.screen() on each screen change. With React Navigation, that's onStateChange:
<NavigationContainer
ref={navigation}
onStateChange={() => {
const name = navigation.getCurrentRoute()?.name;
if (name) Growth.screen(name);
}}
>Growth.screen() also logs screen_viewed and screen_closed, and repeating the current screen does nothing.
Time your most important screen
A screen is "ready" when the JavaScript thread goes idle, which can be before its real content has loaded. On the one screen that matters most, say when it really is ready:
Growth.reportFullyDisplayed(); // a paywall's prices loaded, a feed's first page shownCall it once per screen visit.
Options
Pass these to Growth.init. The defaults are right for almost every app.
| Option | Default | What it does |
|---|---|---|
enableTracing | true | false installs nothing. |
tracesSampleRate | 1 | The share of traces kept, from 0 to 1. The dashboard's rate wins once it has loaded. |
tracePropagationTargets | [] | Where the traceparent header may be sent, so your own backend's spans join the same trace. It's never sent anywhere else. |
enableFrameTracking | true | Slow and frozen frame counts. It needs the SDK's native module, so it stays off in Expo Go. |
Tracing records nothing for a user who has opted out.
Since 0.25 every screen load also carries its JS stalls: how long the JavaScript thread was blocked, counted the way Sentry counts them (a 50 ms timer that fires more than 100 ms late).
Trace your backend
The Python SDK traces every FastAPI (or any ASGI) request, with no code beyond fictura.instrument(app):
| What it records | |
|---|---|
| Requests | One span per request, named by its route template, with status, user and release. It continues the caller's traceparent. |
| Database | Supabase calls (/rest/v1/<table>) as database spans: the table and the operation (select, insert, update, upsert, delete, call). |
| HTTP calls | Every httpx and requests call, with the response size. |
| Model calls | Gemini calls through google-genai: model, provider and token counts. Prompts and completions are never sent. |
| MCP tools | One span per tool, prompt or resource your MCP server answers. |
| Background tasks | Each FastAPI background task as its own trace, linked to the request that queued it. |
| Crons | Anything wrapped in @fictura.monitor("slug"). See Monitors. |
The Node SDK does the same for Express, Fastify and plain http. Both SDKs read traces_sample_rate (default 1: everything), and every span carries its sample rate, so counts on the Performance page stay right when you sample.
Join the app to the backend
Add your API to the propagation list, in the app or under Performance → Overview → Tracing settings, and the app sends traceparent to it. The backend then records its spans under the app's trace, and the trace page shows the screen, the call, the route and its queries in one waterfall. The Sources card says how many app traces reached your backend in the last 24 hours.
Where to see it
Traces arrive within a minute. The Performance page has a tab for each kind of work, and every row opens the same summary: its numbers against the window before, latency over time with where each release started, how durations spread, where the time goes inside each request, what the slowest 10% have that the rest don't, sample traces and the issues on that route.
| Tab | What it shows |
|---|---|
| Overview | Backend requests per minute, p95 and errors against the window before; screen and page load times; the routes that take the most total time; the slowest screens, pages and dependencies; who is sending. |
| Backend | Every route and MCP tool: throughput, p50, p95, p99, errors, open issues and time spent. |
| Dependencies | Database tables and HTTP hosts by time spent, with 5xx and 4xx. A row lists the routes that call it. |
| AI | Model calls by model with tokens, and MCP tool calls by tool. |
| Jobs | Crons (late ones first) and background tasks. |
| App | Cold start, time to initial and full display, slow and frozen frames and JS stalls at p75, per screen and per release. |
| Web | The web vitals score and each vital, pages by opportunity. See Web. |
| Releases | Two releases side by side: every route, screen and page that got slower or faster. |
| Explore | Single spans by name, op, service, route, status and duration, or grouped to compare count, p50, p95 and errors. |
| Monitors | Your own thresholds. See Monitors. |
The page opens on production when your app has it, so development traffic stays out until you pick it. Percentiles are exact for windows up to 24 hours; longer windows merge hourly histograms and are within 4.4% of exact. Spans are kept 30 days and the hourly numbers 90 days.
Your coding agent can read all of this through MCP: get_performance_overview, get_endpoint_summary, compare_releases, get_tracing_health and the rest. See MCP server.
Performance issues
Fictura reads your traces for slow patterns and files them on the Issues page as warnings, one issue per pattern and route. Filter the Issues page by Kind → Performance issues to see only these. They are listed, with their thresholds, on Monitors and performance issues.