The only tool you need to know what is happening and how to fix it.
Flutter SDK Reference
The Traceway Flutter SDK is the traceway package on pub.dev. It supports iOS, Android, and macOS. It does NOT support Flutter web (see the bottom of this file).
Setup
flutter pub add traceway
Wrap the app in Traceway.run():
import 'package:flutter/material.dart';
import 'package:traceway/traceway.dart';
void main() {
Traceway.run(
connectionString: 'your-token@https://traceway.example.com/api/report',
options: TracewayOptions(
screenCapture: true,
version: '1.0.0',
),
child: MyApp(),
);
}
This automatically captures Flutter framework errors (FlutterError.onError), native platform channel errors, and uncaught async errors (via Dart's Zone mechanism).
Wire the navigator observer so navigation transitions are recorded:
MaterialApp(
navigatorObservers: [Traceway.navigatorObserver],
home: const HomePage(),
);
Manual capture
try {
await riskyOperation();
} catch (e, st) {
TracewayClient.instance?.captureException(e, st);
}
TracewayClient.instance?.captureMessage('User completed onboarding');
Options (TracewayOptions)
| Option | Type | Default | Description |
|---|---|---|---|
sampleRate |
double |
1.0 |
Event sampling rate (0.0 to 1.0) |
screenCapture |
bool |
false |
Records the last ~10 seconds of screen as video |
debug |
bool |
false |
Prints debug info to the console |
version |
String |
'' |
App version string |
debounceMs |
int |
1500 |
Milliseconds before sending batched events |
capturePixelRatio |
double |
0.75 |
Screenshot resolution scale |
maxBufferFrames |
int |
150 |
Max frames in recording buffer (~10s at 15fps) |
fps |
int |
15 |
Frames per second for screen capture (1 to 59) |
retryDelayMs |
int |
10000 |
Retry delay in ms on failed uploads |
maxPendingExceptions |
int |
5 |
Max exceptions held in memory before oldest is dropped |
persistToDisk |
bool |
true |
Persist pending exceptions to disk across app restarts |
maxLocalFiles |
int |
5 |
Max exception files stored on disk |
localFileMaxAgeHours |
int |
12 |
Hours after which unsynced local files are deleted |
captureLogs |
bool |
true |
Mirror every print / debugPrint into the rolling log buffer |
captureNetwork |
bool |
true |
Install HttpOverrides.global to record every dart:io HTTP call |
captureNavigation |
bool |
true |
Record transitions reported by Traceway.navigatorObserver |
eventsWindow |
Duration |
10s |
Rolling window kept in the log/action buffers |
eventsMaxCount |
int |
200 |
Hard cap applied independently to logs and actions |
Platform permissions
- Android: add the
INTERNETpermission toandroid/app/src/main/AndroidManifest.xml:<uses-permission android:name="android.permission.INTERNET"/> - macOS: sandboxed by default; add
com.apple.security.network.client(value<true/>) to BOTHmacos/Runner/DebugProfile.entitlementsandmacos/Runner/Release.entitlements. - iOS: nothing needed.
Screen recording
With screenCapture: true, the SDK wraps the app in a RepaintBoundary, captures frames at ~15 fps, and on exception encodes the last ~10 seconds to MP4 and sends it with the report. Touch positions are rendered as blue circles on the captured frames only; the live app is unaffected.
Mask sensitive content with TracewayPrivacyMask (applies to recorded frames only):
TracewayPrivacyMask(
child: Text('4242 4242 4242 4242'),
)
TracewayPrivacyMask(
mode: TracewayMaskMode.blur(ratio: 0.5),
child: CreditCardWidget(),
)
TracewayPrivacyMask(
mode: TracewayMaskMode.blank(color: Color(0xFF000000)),
child: SensitiveDataWidget(),
)
Logs and actions
Every captured exception ships with the last ~10 seconds of context from two rolling buffers (200 entries each by default):
- Logs: every
print/debugPrintline, mirrored via a Zone print override.dart:developer.logis NOT captured. - Network actions: every dart:io HTTP request (method, URL, status, duration, byte counts) via
HttpOverrides.global, which catchespackage:http, Dio, Firebase, and anything else on the dart:io HttpClient. - Navigation actions: push / pop / replace / remove, from
Traceway.navigatorObserver. - Custom actions:
Traceway.recordAction( category: 'cart', name: 'add_item', data: {'sku': 'SKU-123', 'qty': 2}, );
Symbol upload (obfuscated builds)
A plain flutter build --release keeps enough symbol information that crash stack traces are already readable (function names plus file:line), and the SDK reports them as-is. You only need symbol upload when the build is hardened with --obfuscate and/or --split-debug-info=<dir>: those flags strip and rename Dart symbols into per-architecture .symbols files, so production traces then arrive as bare instruction offsets and stay unreadable until Traceway resolves them server-side from the build's .symbols files (the same way it handles JavaScript source maps).
First, check whether the build is obfuscated. Look at how release artifacts are produced (the flutter build invocations in CI under .github/, in fastlane/, in a Makefile, or in shell scripts) and ask the user how they build for release. If neither --obfuscate nor --split-debug-info is passed, stack traces are already readable and symbol upload is unnecessary; skip the rest of this section. If obfuscation is (or will be) used, set up the upload.
Then use the project's upload token. Symbol uploads authenticate with the dedicated upload token (Connection page > Symbol Upload, the same token shown under Source Maps), NOT the project token from the connection string. It is a CI secret, never committed. readonly members cannot generate one.
The traceway package ships an uploader (dart run traceway:upload_symbols) that finds the .symbols files, derives each one's architecture and debug ID, and posts them. Configure it once, then run it on every release.
One-time setup. Add a traceway: block to the app's pubspec.yaml:
traceway:
url: https://<instance> # omit on Traceway Cloud
# upload_token: ... # prefer the env var below, especially in CI
The upload token resolves from TRACEWAY_UPLOAD_TOKEN (or --token) before the upload_token key, so keep it out of pubspec.yaml in CI.
Per release. Build with obfuscation and a known symbols directory, then run the uploader:
flutter build apk --release --obfuscate --split-debug-info=build/symbols
TRACEWAY_UPLOAD_TOKEN=<upload-token> dart run traceway:upload_symbols
The uploader auto-discovers build/symbols and uploads every architecture in one run, so no flags are required. Each value resolves from a CLI flag first (--token, --url, --symbols-dir), then an env var (TRACEWAY_UPLOAD_TOKEN, TRACEWAY_URL), then the pubspec.yaml block. Pass --dry-run to preview, but note that it still requires a resolved token and URL: without them it exits with No upload token. Set TRACEWAY_UPLOAD_TOKEN, pass --token, or add traceway.upload_token to pubspec.yaml. Symbols are unique to each build, so upload on every release; a crash only resolves against the exact build it came from.
The build command above produces an Android APK; other targets (appbundle, ios, macos) emit their own .symbols files into the same directory, all picked up by a single uploader run. On Android the debug ID is read straight from each file's build-id note. iOS and macOS .symbols carry no such note, so the uploader reads the Mach-O UUID from the built .app (auto-discovered under build/, or point at it with --app build/macos/Build/Products/Release/YourApp.app); run the uploader on the same Mac that produced the build.
The uploader exists because that UUID has to be read out of the compiled app, which is easiest on the build machine. It is not the only path. If a pipeline cannot run the Dart uploader, read the UUID yourself and pass it as a debug_id field:
dwarfdump --uuid build/macos/Build/Products/Release/YourApp.app/Contents/Frameworks/App.framework/App
curl -fsS -H "Authorization: Bearer <upload-token>" \
-F "files=@build/symbols/app.darwin-arm64.symbols" \
-F "debug_id=<uuid-from-dwarfdump>" \
https://<instance>/api/symbols/upload
Case and dashes are normalized server-side, so paste the UUID exactly as dwarfdump prints it. The architecture is read from the .symbols filename; pass -F "arch=arm64" too if the file has been renamed.
Known issue, verified 2026-08-17. This curl body is byte-identical to what the Dart uploader sends, and on macOS both currently accept the upload (2/2 uploaded, debug_id matching the runtime build id) while obfuscated release traces still come back unresolved. The curl path inherits the bug, so it is not a workaround for it. Until that is fixed, keep a copy of the .symbols files with each release so traces can be resolved offline.
Wire the upload into the release pipeline right after the build step (CI, fastlane, or a build script), with the token from a secret:
- name: Upload Flutter symbols
run: dart run traceway:upload_symbols
env:
TRACEWAY_URL: ${{ secrets.TRACEWAY_URL }}
TRACEWAY_UPLOAD_TOKEN: ${{ secrets.TRACEWAY_UPLOAD_TOKEN }}
Self-hosted instances must have blob storage (S3 or a persistent volume) configured, or uploaded symbols disappear when the container is recreated.
Flutter web
The Flutter SDK does not support web (no error tracking, no screen recording there). For Flutter web apps, use the JS SDK in web/index.html instead:
<script src="https://cdn.jsdelivr.net/npm/@tracewayapp/frontend@1/dist/traceway.iife.global.js"></script>
<script>
Traceway.init("your-token@https://traceway.example.com/api/report");
</script>
For network capture in Dart code on web (where HttpOverrides.global does not run), TracewayHttpClient is a drop-in http.Client, usable directly or passed to libraries that accept a custom client (Dio, Chopper):
final client = TracewayHttpClient();
final res = await client.get(Uri.parse('https://api.example.com/users'));
Verify
Add a button that throws (throw StateError('Test error from Traceway')), tap it, and check the Issues page in the dashboard. With screenCapture: true, the recording appears alongside the stack trace. For an obfuscated release build, confirm the stack trace shows real frames rather than obfuscated offsets once the matching .symbols files have been uploaded.