End users (browsers and mobile apps)
What your users' browsers and mobile apps measured is here: page loads and app starts, Web Vitals, sessions, errors and crashes, calls to your backend. Each is linked to the backend trace it started. Menu: APM → End users.
Before you start
- Create a browser and app key: Admin → Integrations › Add integration › Browser and app key (details).
- Connect your app with its guide:
| App | Guide |
|---|---|
| Any site, no build step | HTML / JavaScript |
| React (Vite, Next.js, Create React App) | React.js |
| React Native, Expo | React Native |
| Flutter | Flutter |
| Native Android (Kotlin, Java) | Android |
| Native iOS (Swift) | iOS |
Overview
App and Platform narrow the page. A click on a value in any table (a browser, a version, a country) narrows the whole page to it as well.
- Crash-free sessions: the share of sessions with no crash. The users share shows only when your code names the user, otherwise
–. - Page load (p75) and App start (p75), with cold and warm starts (Android sends
start.type). - Web Vitals: the 75th percentile and band of LCP, INP, CLS, FCP and TTFB.
- Page load, step by step (DNS to load, from the HTML loader) and Files a page loads (the slowest files).
- By device and version: the device type is what the app says; else it comes from the user agent, else from the screen (shorter side 600 dp or more: tablet).
Pages
The Pages tab groups pages by route: ids and long numbers in an address become {id}, so /orders/123 and /orders/456 are one page. Per page you see load time (p50, p75, p95), Web Vitals, errors and long tasks (work that blocked the page for 50 ms or more).
Two tables on the page detail help most: LCP elements tells which element was the largest paint (e.g. main > img.hero), INP targets which element the slow interactions were on. The most common case: an uncompressed hero image is what spoils LCP.
Error and crash groups
Open this error under an error opens its group: the same error or crash on every device, with its count, sessions, first and last time, and how it splits by version, device, browser and country. Samples are the newest occurrences, each with its session and trace.
When the version's symbol files are in Spitfire, Your code shows the stack turned back: minified JavaScript (app.min.js:1:4211) becomes the source file, line and function; an Android stack shrunk by R8 (a.b.a(SourceFile:2)) becomes the class and method. As sent is the raw stack. The badge says how many frames matched. Reading the files needs Starter or higher; the raw stack shows on every plan.
Symbol files
The Symbol files tab keeps these files per app and version:
| File | From |
|---|---|
JavaScript source maps (*.map, version 3) |
your bundler's output folder (Vite: build.sourcemap: true; webpack: devtool: 'source-map') |
Android mapping.txt (R8 / ProGuard) |
app/build/outputs/mapping/release/mapping.txt after a release build |
Up to 50 MB per app version; a new file with the same name replaces the old one. The app and version must be what the app sends (service.name, service.version). iOS dSYM files are not read.
Upload them by hand on the tab (admins), or from CI after each build with an API token (user menu → API tokens) of an admin. This works from any folder; set DIST to the bundler's output folder and MAPPING to the mapping file (one of them may be missing):
SPITFIRE_URL='https://<spitfire>'
APP='<service-name>'
VERSION='<service-version>'
DIST="$HOME/build/<service-name>/dist"
MAPPING="$HOME/build/<service-name>/app/build/outputs/mapping/release/mapping.txt"
printf 'Spitfire API token: '; read -rs SPITFIRE_TOKEN; echo
{ find "$DIST" -type f -name '*.map' 2>/dev/null; [ -f "$MAPPING" ] && echo "$MAPPING"; } | while IFS= read -r f; do
curl -fsS -o /dev/null -X POST "$SPITFIRE_URL/api/v1/apm/eum/symbols" -H "Authorization: Bearer $SPITFIRE_TOKEN" \
-F "app=$APP" -F "version=$VERSION" -F "file=@$f" && echo "uploaded: $f" || echo "NOT uploaded: $f"
done
curl -fsS "$SPITFIRE_URL/api/v1/apm/eum/symbols?app=$APP&version=$VERSION" -H "Authorization: Bearer $SPITFIRE_TOKEN" | grep -q '"name"' \
&& echo "OK: symbol files of $APP $VERSION are in Spitfire" || echo "No symbol files for $APP $VERSION: check DIST, MAPPING and the token"It must end with OK: …. Do not serve the .map files from your site: upload them here and delete them from the build output if you do not want your source to be public.
Sessions
The Sessions tab lists sessions newest first; narrow it with With errors / With crashes and the country, device and version selects. Click a start time for the timeline: views, clicks, requests and errors in order. Open the trace on a step shows the whole waterfall, from the browser span down to your backend's database calls.
A session is one browser tab or one app run; Android renews it after 30 minutes in the background or after 4 hours.
Countries and cities
The world map colours countries by sessions; the borders ship inside Spitfire and no map service is called. Click a country to see its regions and cities.
Spitfire works out the country from the sender's address when the data arrives, then drops the address. It needs a location database file (.mmdb) for that, and Spitfire does not ship one; without it the page works and shows no countries. DB-IP's free IP to City Lite database works (license CC BY 4.0; the Countries and cities tab shows the required "IP Geolocation by DB-IP" line). Docker installation in ~/spitfire:
- Download this month's file into the installation's
geoipfolder:
mkdir -p ~/spitfire/deploy/docker/geoip && curl -fsSL "https://download.db-ip.com/free/dbip-city-lite-$(date +%Y-%m).mmdb.gz" | gunzip > ~/spitfire/deploy/docker/geoip/dbip-city-lite.mmdb- Tell Spitfire where it is:
grep -q '^SPITFIRE_GEOIP_DB=' ~/spitfire/deploy/docker/.env || echo 'SPITFIRE_GEOIP_DB=/var/lib/spitfire/geoip/dbip-city-lite.mmdb' >> ~/spitfire/deploy/docker/.env- Restart the controller:
docker compose --project-directory ~/spitfire/deploy/docker up -d controller- Check that it was read:
docker compose --project-directory ~/spitfire/deploy/docker logs controller | grep -q 'geoip: End users places addresses' && echo OKIt must print OK. New data shows the country from then on; earlier data stays without one. We suggest repeating steps 1 and 3 once a month. A MaxMind GeoLite2 City file works the same way (it needs a MaxMind account). On Kubernetes, mount the file into the controller and set SPITFIRE_GEOIP_DB to its path.
Requests
The newest calls the apps made: the address (without its query string), status, duration, the backend service that answered and the host it ran on. When the app called another address (a load balancer, a gateway), via names it. not traced: the backend did not answer with a trace of its own; it has no OTel, or the call did not carry traceparent.
From a backend trace
A trace a browser or app started shows Started from: above its waterfall: the app, the page, the device, the country and a link to the user's session.
What is kept and what is not
- The sender's IP address is used for the country and not stored.
- Device identifiers and anything starting with
user.,enduser.orgeo.are removed. Only theenduser.id/user.idyour code sets on purpose stays (HTML:SpitfireRUM.setUser). - The loader sends addresses without query strings.
- Metrics from a browser key are dropped; spans and logs stay as long as APM keeps data.
Common problems
| Symptom | Fix |
|---|---|
| The page shows the six guides | Nothing has arrived in the range: check the guide's Verify steps and widen the range |
| No country | Countries and cities; step 4 must print OK |
Step 1 of countries fails with 404 |
Early in a month the new file may not be out yet: put last month in place of $(date +%Y-%m), e.g. 2026-10 |
Crash-free users is – |
Your app does not name its users; that is the default |
| Requests show not traced | The backend needs OTel and the call must carry traceparent (the guide's propagate setting and the backend's CORS) |
| The stack is not turned back | Upload the version's symbol files; app and version must be the ones the app sends |
| No iOS crashes | The iOS package does not collect crashes; report caught errors with Otel.error |