Error reporting

Open in ChatGPTOpen in Claude

Unhandled / handled exceptions

For handled exceptions, use a try/catch scheme with the reportError API

Report handled errors with optional structured data and labels. Choose one variant per error event — each call generates a single error report.

Basic error reporting:

try {
  throw StateError('state error try catch');
} catch (error, stackTrace) {
  if (error is StateError) {
    await CxFlutterPlugin.reportError(
      error,
      null,
      stackTrace.toString(),
    );
  }
}

With structured data:

try {
  throw StateError('payment failed');
} catch (error, stackTrace) {
  await CxFlutterPlugin.reportError(
    error,
    {'orderId': 'ORD-123', 'amount': 99.99},
    stackTrace.toString(),
  );
}

With data and labels:

try {
  throw StateError('payment failed');
} catch (error, stackTrace) {
  await CxFlutterPlugin.reportError(
    error,
    {'orderId': 'ORD-123', 'amount': 99.99},
    stackTrace.toString(),
    labels: {'team': 'payments', 'severity': 'high'},
  );
}

⚠️ Platform note: reportError(message, data, '') (empty stack trace) attaches data on iOS only — the Android native SDK has no data-only entry point, so data is dropped on Android in that shape. Always supply a stack trace when you need attributes attached cross-platform.

For Unhandled exceptions

you need to wrap your runApp function as follows:

void main() {
  runZonedGuarded(() {
    runApp(const MaterialApp(
      title: 'Navigation Basics',
      home: MyApp(),
    ));
  }, (error, stackTrace) {
    CxFlutterPlugin.reportError(
      error,
      null,
      stackTrace.toString(),
      isCrash: true,
    );
  });
}

Custom Log

  await CxFlutterPlugin.log(CxLogSeverity.error, 'this is an error', {'fruit': 'banna', 'price': 1.30});

Views

To monitor page / views, report the current screen with setView:

   await CxFlutterPlugin.setView(viewName);

Each setView also drives the SDK's product-analytics fields on the emitted RUM events: view_number (a per-session counter that increments on each unique view change) and isNavigationEvent. These are owned and computed by the native SDK — you only need to report the view.

Automatic view tracking

Instead of calling setView in every page, drop CxNavigatorObserver into your app's navigator and route changes are tracked for you:

   MaterialApp(
     navigatorObservers: [CxNavigatorObserver()],
     // ...
   );

Only PageRoutes are tracked (dialogs, bottom sheets and popups are not treated as a screen change). The view name is taken from RouteSettings.name, so name your routes:

   MaterialPageRoute(
     settings: const RouteSettings(name: 'Cart'),
     builder: (_) => const CartPage(),
   );

Unnamed routes are skipped. To derive the name differently (or skip a route by returning null), pass a nameExtractor:

   CxNavigatorObserver(
     nameExtractor: (route) => route.settings.name ?? route.runtimeType.toString(),
   );

Set Labels

Sets the labels for the Coralogix exporter.

   final labels = {'stock': 'NVDA', 'price': 104};
   await CxFlutterPlugin.setLabels(labels);

Set User Context

Setting User Context

 var userContext = UserContext(
    userId: '456',
    userName: 'Robert Davis',
    userEmail: 'robert.davis@example.com',
    userMetadata: {'car': 'tesla'},
  );

  await CxFlutterPlugin.setUserContext(userContext);

New Session

Force-start a fresh RUM session on demand — typically on user logout — without a full re-init. A new session id is issued and per-session state resets, exactly like the SDK's automatic idle / max-age rotation.

  await CxFlutterPlugin.createNewSession();

Shutdown

Shuts down the Coralogix exporter and marks it as uninitialized.

  await CxFlutterPlugin.shutdown();