Traceway Flutter SDK

Error tracking and screen recording for Flutter apps. Capture exceptions with full stack traces and the last 10 seconds of screen recording — automatically.

Traceway is a completely open-source error tracking platform. You can self-host it or use Traceway Cloud.

Features

Automatic capture of all Flutter errors (framework, platform, and async)
Full Dart stack traces
Screen recording — last ~10 seconds encoded as MP4 video
Touch/click positions rendered on recordings
Gzip-compressed transport
Simple one-line setup

Installation

flutter pub add traceway

Quick Start

Wrap your app with Traceway.run():

import 'package:flutter/material.dart';
import 'package:traceway/traceway.dart';

void main() {
  Traceway.run(
    connectionString: 'your-token@https://your-traceway-instance.com/api/report',
    options: TracewayOptions(
      screenCapture: true,
      version: '1.0.0',
    ),
    child: MyApp(),
  );
}

That's it. All uncaught exceptions are captured automatically.

Manual Capture

// Capture a caught exception
try {
  await riskyOperation();
} catch (e, st) {
  TracewayClient.instance?.captureException(e, st);
}

// Capture a message
TracewayClient.instance?.captureMessage('User completed checkout');

// Force send pending events
await TracewayClient.instance?.flush();

Options

Option	Default	Description
`sampleRate`	`1.0`	Error sampling rate (0.0 - 1.0)
`screenCapture`	`false`	Record last ~10 seconds of screen
`debug`	`false`	Print debug info to console
`version`	`''`	App version string
`debounceMs`	`1500`	Milliseconds before sending batched events
`retryDelayMs`	`10000`	Retry delay on failed uploads
`capturePixelRatio`	`0.75`	Screenshot resolution scale factor
`maxBufferFrames`	`150`	Max frames in recording buffer (~10s at 15fps)
`captureIntervalMs`	`67`	Frame capture interval (~15fps)

Platform Setup

Traceway needs network access to send error reports. Depending on the platform, you may need to add permissions manually.

Android

Add the INTERNET permission to android/app/src/main/AndroidManifest.xml:

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <uses-permission android:name="android.permission.INTERNET"/>
    <application
      ...

macOS

macOS apps are sandboxed by default and cannot make network requests without the com.apple.security.network.client entitlement.

Add it to both macos/Runner/DebugProfile.entitlements and macos/Runner/Release.entitlements:

<dict>
    <key>com.apple.security.app-sandbox</key>
    <true/>
    <key>com.apple.security.network.client</key>
    <true/>
</dict>

iOS

No additional configuration is required. iOS apps can make HTTPS requests by default.

Screen Recording

When screenCapture: true, the SDK:

Wraps your app in a RepaintBoundary
Captures frames at ~15fps into a circular buffer
On exception, encodes the last ~10 seconds to MP4
Sends the video alongside the stack trace

Touch and click positions are drawn directly onto the recorded frames (invisible to the user) so you can see exactly what the user was doing before the crash.

Platform Support

Platform	Error Tracking	Screen Recording
iOS	Yes	Yes
Android	Yes	Yes
macOS	Yes	Yes
Web	No	No

For Flutter web, use the JS SDK instead — see Flutter Web below.

What Gets Captured Automatically

Flutter framework errors — rendering, layout, gestures via FlutterError.onError
Platform errors — native plugin crashes via PlatformDispatcher.onError
Uncaught async errors — unhandled futures via runZonedGuarded

Flutter Web

This SDK does not support Flutter web. For web apps, use the @tracewayapp/frontend JS SDK which provides rrweb session replay and automatic fetch instrumentation.

Add the CDN script to web/index.html:

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

Alternatively, if you use npm in your Flutter web project:

npm install @tracewayapp/frontend

<script type="module">
  import { init } from '@tracewayapp/frontend';
  init('your-token@https://traceway.example.com/api/report');
</script>

See the full JS SDK documentation for all options.

License

MIT