Flutter

The Coralogix RUM Mobile SDK is a library (plugin) for Flutter that provides mobile telemetry instrumentation. Learn how to integrate with Coralogix's Real User Monitoring (RUM).

Overview

The Coralogix RUM Mobile SDK is a library (plugin) for Flutter that provides mobile telemetry instrumentation. The SDK captures:

HTTP requests
Unhandled/handled exceptions
Custom logs
Crashes (iOS Native using PLCrashReporter)
Views

Coralogix captures data using an SDK within your application's runtime. These platform-specific SDKs allow Coralogix to gain a deep understanding of how your application works, enabling comprehensive real-user monitoring and performance analysis.

Install

To add the Coralogix dependency, navigate to the root folder of your Flutter app and run:

flutter pub add cx_flutter_plugin

Configure

To initialize the RUM SDK, you need to input both CXExporterOptions and CXDomain.

import 'package:cx_flutter_plugin/cx_http_client.dart';

class _MyAppState extends State<MyApp> {
  @override
  void initState() {
    super.initState();
    initPlatformState();
  }

  Future<void> initPlatformState() async {
    var coralogixDomain = <Coralogix Domain>;

    var options = CXExporterOptions(
      coralogixDomain: <CXDomain>,
      userContext: null,
      environment: '<Environment>',
      application: '<App Name>',
      version: '<App Version>',
      publicKey: '<PublicKey>',
      ignoreUrls: [],
      ignoreErrors: [],
      customDomainUrl: '',
      labels: {'item': 'playstation 5', 'itemPrice': 1999},
      debug: false,
    );

    await CxFlutterPlugin.initSdk(options);

    // If the widget was removed from the tree while the asynchronous platform
    // message was in flight, we want to discard the reply rather than calling
    // setState to update our non-existent appearance.
    if (!mounted) return;
  }
}

Field	Description	Example
`coralogixDomain`	The region associated with your Coralogix domain.	`US1, US2, EU1, EU2, 2PI, API`
`userContext`	User context information, such as user ID, name, email, and additional metadata.	`var userContext = UserContext( userId: '123', userName: 'John Doe', userEmail: '[email protected]', userMetadata: {'item1': '1999'}, );`
`environment`	The environment in which the application is running (e.g., production, staging).	`"production"`
`application`	The name of the application.	`"MyApp"`
`version`	The version of the application.	`"1.0.0"`
`publicKey`	Coralogix token, publicly-visible publicKey value. This is a required property.	`"my_public_key"`
`ignoreUrls`	A list of URLs to ignore for logging and monitoring purposes.	`["https://example.com/api"]`
`ignoreErrors`	A list of errors to ignore for logging and monitoring purposes.	`["NotFoundError", "TimeoutError"]`
`customDomainUrl`	A custom domain URL for sending data, if different from the default Coralogix domain.	`"https://custom-domain.example.com"`
`labels`	A set of key-value pairs for additional metadata or labels to attach to logs and monitoring data.	`{ environment: "production", region: "us-east-1"}`
`debug`	A boolean flag to enable or disable debug mode for additional logging and diagnostics.	`true` or `false`

Network requests

By using CxHttpClient, the RUM SDK can monitor the HTTP traffic.

final client = CxHttpClient(http.Client());
await client.get(Uri.parse(url));

Unhandled/Handled exceptions

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

try {
  throw StateError('state error try catch');
} catch (error, stackTrace) {
  if (error is StateError) {
    // Handle the StateError
    CxFlutterPlugin.reportError(error.message, {}, stackTrace.toString());
  }
}

Or

await CxFlutterPlugin.reportError('this is an error', {'fruit': 'banana', 'price': 1.30}, "");

Unhandled exceptions

Wrap your runApp function as follows:

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

Custom logs

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

Views

To monitor page views, use the following API:

await CxFlutterPlugin.setView(viewName);

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: '[email protected]',
  userMetadata: {'car': 'tesla'},
);

await CxFlutterPlugin.setUserContext(userContext);