Skip to main content

tracex_flutter 1.0.0 copy "tracex_flutter: ^1.0.0" to clipboard
tracex_flutter: ^1.0.0 copied to clipboard

Official Flutter SDK for TraceX — real-time crash capture, forensic telemetry, and incident triage.

TraceX Flutter SDK #

Flutter License

Official Flutter SDK for TraceX — developer-first, AI-assisted crash observability with sub-50ms Cloudflare Edge Ingestion, intelligent origin failover, offline FIFO queuing, and automated root-cause analysis.


Features #

  • ⚡ Cloudflare Edge Ingestion: Telemetry is routed through Anycast edge workers with low latency (<50ms) and automatic sticky failover to direct origin APIs on network failures.
  • 🛡️ Zero Telemetry Loss (Offline Queue): Unhandled crashes and breadcrumbs are cached locally using Hive in a 100-event FIFO buffer and automatically replayed when network connectivity is restored.
  • 🎯 5-Minute Fingerprint Deduplication: In-memory micro-cooldown deduplicates storm bursts of repeated exceptions.
  • 🧭 Automatic Route Breadcrumbs: Track user navigation paths across your application with TraceXNavigatorObserver.
  • 🌐 HTTP Network Breadcrumbs: Track HTTP request durations, status codes, and network failures with TraceXDioInterceptor.
  • 📱 Hardware Environment Telemetry: Captures battery level, total/free RAM, low-memory flags, OS version, device model, and app package metadata.

Installation #

Add tracex_flutter to your Flutter project:

Option 1: Terminal Command #

flutter pub add tracex_flutter

Option 2: pubspec.yaml #

Add the dependency under dependencies in your pubspec.yaml:

dependencies:
  flutter:
    sdk: flutter
  tracex_flutter: ^1.0.0

Then run:

flutter pub get

Quickstart #

1. Initialize TraceX in main() #

Initialize TraceX before running runApp(). TraceX automatically hooks into FlutterError.onError and PlatformDispatcher.instance.onError to intercept unhandled exceptions.

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

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  // Initialize TraceX SDK with your project API key
  await TraceX.init(
    projectKey: 'YOUR_PROJECT_API_KEY',
    enableLogging: true, // Optional: print internal SDK logs to console
  );

  runApp(const MyApp());
}

2. Add Navigation Route Breadcrumbs #

Add TraceXNavigatorObserver to your MaterialApp to automatically record route pushes, pops, and replacements:

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'My TraceX App',
      navigatorObservers: [
        TraceXNavigatorObserver(),
      ],
      home: const HomeScreen(),
    );
  }
}

3. Add HTTP Network Breadcrumbs (Dio) #

If your app uses dio for HTTP networking, attach TraceXDioInterceptor to track outgoing requests and latency:

import 'package:dio/dio.dart';
import 'package:tracex_flutter/tracex_flutter.dart';

final dio = Dio();
dio.interceptors.add(TraceXDioInterceptor());

Manual Error Reporting #

Record Caught Exceptions #

Capture handled try-catch exceptions without crashing the user's interface:

try {
  await performCriticalCheckout();
} catch (error, stackTrace) {
  TraceX.recordError(
    error,
    stackTrace,
    reason: 'Payment gateway rejected customer card',
    fatal: false,
  );
}

Run Within a Guarded Zone #

Catch unhandled asynchronous exceptions in custom microtasks or isolates:

void main() {
  TraceX.runGuarded(() {
    runApp(const MyApp());
  });
}

Configuration Options #

Parameter Type Default Description
projectKey String Required Your TraceX Project API Key (tracex_live_...). Can also use apiKey.
enableLogging bool false When true, prints internal SDK diagnostic events via debugPrint.
offlineBuffer bool true When true, caches crashes in offline storage if offline or rate-limited.
captureBreadcrumbs bool true When true, records navigation and lifecycle breadcrumbs.
endpoint String? Edge Base URL Custom ingestion gateway endpoint (defaults to Cloudflare Edge).
fallbackEndpoint String? Origin Base URL Custom origin endpoint for fallback when edge is unreachable.

Testing Your Integration #

To verify that your integration is streaming events to your TraceX dashboard:

ElevatedButton(
  onPressed: () {
    throw StateError('Simulated Test Crash from Flutter App');
  },
  child: const Text('Trigger Test Crash'),
)

Within seconds, check your TraceX Incident Stream at /dashboard/issues to inspect symbolicated stack frames, environment details, and AI root cause diagnosis!

1
likes
110
points
51
downloads

Documentation

API reference

Publisher

verified publishertracex.dev

Weekly Downloads

Official Flutter SDK for TraceX — real-time crash capture, forensic telemetry, and incident triage.

Homepage
Repository (GitHub)
View/report issues

License

MIT (license)

Dependencies

battery_plus, connectivity_plus, device_info_plus, dio, flutter, get_it, hive, hive_flutter, package_info_plus

More

Packages that depend on tracex_flutter

Packages that implement tracex_flutter