Error reporting
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) attachesdataon iOS only — the Android native SDK has no data-only entry point, sodatais dropped on Android in that shape. Always supply a stack trace when you need attributes attached cross-platform.
For unhandled exceptions
From version 0.21.0, once initSdk completes, the plugin reports unhandled errors automatically. You don't write any handler code. This covers:
- Errors the Flutter framework catches, such as exceptions thrown in
build, layout, paint, or a gesture callback. - Errors that escape every zone, such as a failed
Futureorcompute()call that nothing awaits or catches.
These are reported as errors, not crashes, because an unhandled Dart error doesn't stop the app. Errors Flutter marks as silent, such as a failed image load, are not reported. When the same error repeats, for example on every frame, it is reported at most once every 5 seconds.
To turn this off, set errors to false in instrumentations. This also turns off native crash reporting and reportError:
CXExporterOptions(
// ...
instrumentations: {'errors': false},
);
If you set FlutterError.onError or PlatformDispatcher.instance.onError before calling initSdk, your handler still runs after the plugin reports the error. If your handler also calls reportError, or passes the error to a runZonedGuarded handler that does, remove that path, or each error is reported twice. A handler you set after initSdk replaces the plugin's.
Errors caught by a runZonedGuarded handler don't reach the plugin. If you use runZonedGuarded, report from its handler:
void main() {
runZonedGuarded(() {
runApp(const MyApp());
}, (error, stackTrace) {
CxFlutterPlugin.reportError(error, null, stackTrace.toString());
});
}
Dart errors that happen before initSdk completes are not reported.
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 = UserMetadata(
userId: '456',
userName: 'Robert Davis',
userEmail: 'robert.davis@example.com',
userMetadata: {'car': 'tesla'},
accountId: 'acc-42', // optional, from 0.16.0
accountName: 'Acme Corp', // optional, from 0.16.0
);
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();