Docs / SDKs / Flutter

Flutter

talaria_flutter — global error hooks, route tags, zone bootstrap, and optional tracing.

Built on the Dart SDK. Use this guide for Flutter-specific error hooks, route tags, and app bootstrap.

Install

Add the package to your pubspec.yaml, then run flutter pub get.

dependencies:
  talaria_flutter: ^0.1.0

Configure & global hooks

TalariaFlutter.init installs FlutterError.onError and PlatformDispatcher.onError, and tracks app.state. Add TalariaNavigatorObserver so events carry the current route / screen.

import 'package:flutter/widgets.dart';
import 'package:talaria_flutter/talaria_flutter.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();

  await TalariaFlutter.init(TalariaOptions(
    dsn: const String.fromEnvironment(
      'TALARIA_DSN',
      defaultValue: 'https://api.newtalaria.com',
    ),
    apiKey: const String.fromEnvironment('TALARIA_API_KEY'),
    environment: const String.fromEnvironment(
      'APP_ENV',
      defaultValue: 'production',
    ),
    release: const String.fromEnvironment('APP_RELEASE'),
    minLevel: SeverityLevel.warning,
  ));

  ErrorWidget.builder = talariaErrorWidgetBuilder();
  runApp(MyApp(
    navigatorObservers: [TalariaNavigatorObserver()],
  ));
}

Zone-guarded bootstrap

Use TalariaFlutter.runZonedApp to wrap init and runApp in a zone so async errors outside the framework are captured too:

Future<void> main() async {
  await TalariaFlutter.runZonedApp(
    TalariaOptions(
      dsn: 'https://api.newtalaria.com',
      apiKey: 'tal_live_…',
      environment: 'production',
    ),
    const MyApp(),
  );
}

Capture exceptions

try {
  await riskyOperation();
} catch (error, stackTrace) {
  await Talaria.captureException(
    error,
    stackTrace: stackTrace,
    context: CaptureContext(tags: {'screen': 'checkout'}),
  );
  rethrow;
}

Performance tracing

Tracing options live on TalariaOptions — same as the Dart SDK. Tracing is off until enableTracing is true or tracesSampleRate is greater than 0. Head-based sampling: 100% of error transactions; default 10% of successful. Route changes from TalariaNavigatorObserver become transactions. Inspect waterfalls and RED in Performance.

await TalariaFlutter.init(TalariaOptions(
  dsn: 'https://api.newtalaria.com',
  apiKey: const String.fromEnvironment('TALARIA_API_KEY'),
  environment: 'production',
  enableTracing: true,
  tracesSampleRate: 0.1, // 10% of successful transactions; errors always traced
));

Already running an OpenTelemetry Collector? That is an advanced path — export OTLP/HTTP JSON to POST /otlp/v1/traces. Prefer the native SDK unless you already operate a Collector. See the API overview.

Environments & releases

Map build flavors / --dart-define values into environment and release so the dashboard can filter issues and correlate deploys.

Troubleshooting

• 401/403 — check API key and that it belongs to the target project.
• No issue appears — confirm environment filter in the dashboard.
• Rejected events — validate JSON shape against the API overview.

Need pure Dart (no Flutter)? See the Dart SDK or send events over HTTP via the API overview.