Flutter
Dart
Rollbar SDK for pure Dart applications.
Note: if you're using Flutter, you should use rollbar-flutter instead since it includes all the features from
rollbar-dart
, plus some Flutter-specific functionality.
Quick Start
Integrating this library with your Dart codebase requires the following steps:
- Add the package to your
pubspec.yaml
file:
dependencies:
rollbar_dart: 0.1.0
- Run
dart pub get
To configure rollbar-dart and send an error and a message:
import 'package:rollbar_dart/rollbar.dart';
/// Command line application example using rollbar-dart.
void main() async {
var config = (ConfigBuilder('<YOUR ROLLBAR TOKEN HERE>')
..environment = 'development'
..codeVersion = '0.1.0'
..handleUncaughtErrors = true)
.build();
var rollbar = Rollbar(config);
await rollbar.infoMsg('This is an info message');
try {
throw ArgumentError('An error occurred');
} catch (error, stackTrace) {
await rollbar.error(error, stackTrace);
}
}
If the application is running as a command line tool, the Rollbar token must have the POST_SERVER_ITEM_ACCESS_TOKEN
scope.
Requirements
- Dart SDK >= 2.7.0
- A Rollbar account
Uncaught Errors
When the handleUncaughtErrors
configuration option is enabled, rollbar-dart
will create a dedicated Rollbar Isolate
, and it will automatically register its ReceivePort
as the error handler for the current isolate (the one in which Rollbar
was instantiated) via Isolate.current.addErrorListener
.
The error handler ReceivePort
is available through the Rollbar.errorHandlerPort
property, and can be used to handle uncaught errors in other isolates as well, eg:
var isolate = await Isolate.spawn(...);
isolate.addErrorHandler(rollbar.errorHandlerPort);
Transformer
and Sender
factory functions
Transformer
and Sender
factory functionsIf necessary, the Sender
and Transformer
classes can be configured by providing a factory function in the configuration, eg:
void main() async {
var config = (ConfigBuilder('<TOKEN>')
..codeVersion = '0.1.0'
..sender = _createSender
..transformer = _createTransformer)
.build();
var rollbar = Rollbar(config);
...
}
Sender _createSender(Config conf) {
return CustomSender(conf);
}
Transformer _createTransformer(Config conf) {
return CustomTransformer(conf);
}
class CustomSender implements Sender {
...
}
class CustomTransformer implements Transformer {
...
}
When handleUncaughtErrors
is set to true
, the factory functions must be static or free functions (like the example above), and cannot be closures, because they need to be passed to the error handling isolate as messages, and passing closures as messages is not supported by Dart.
There are no serializability requirements on the classes implementing the Sender
or Transformer
interface, since new instances of them will be created in the error handling isolate.
Flutter
Rollbar SDK for Flutter
Quick Start
Integrating this library with your Flutter codebase requires the following steps:
- Add the package to your
pubspec.yaml
file:
dependencies:
rollbar_flutter: 0.1.0
- Run
flutter pub get
To configure rollbar-flutter to handle all uncaught errors in your application:
import 'package:flutter/material.dart';
import 'package:flutter/services.dart';
import 'package:rollbar_flutter/rollbar.dart';
Future<void> main() async {
var config = (ConfigBuilder('<YOUR ROLLBAR TOKEN HERE>')
..environment = 'development'
..codeVersion = '0.1.0'
..handleUncaughtErrors = true
..includePlatformLogs = true)
.build();
await RollbarFlutter.run(config, (rollbar) {
runApp(MyApp());
});
}
class MyApp extends StatelessWidget {
...
}
When the application is running in an Android device or emulator, the Rollbar token must have the POST_CLIENT_ITEM_ACCESS_TOKEN
scope.
Requirements
- Dart SDK >= 2.7.0
- Flutter >= 1.20.0
- A Rollbar account
Platform support
rollbar-flutter
currently support Android and iOS.
Android
Platform specific occurrence information
When handleUncaughtErrors
is set to true
, there will be a separate rollbar-android
notifier that will handle uncaught exceptions on the Android platform side.
Android runtime exceptions thrown from a MethodChannel
invocation will not be caught by rollbar-android
though, since those are caught by Flutter and re-thrown on the Dart side. They will be caught and reported by the the rollbar Dart notifier.
By default the Dart exception will include the Java or Kotlin stack trace as a String in the exception message, missing some important information from the Android runtime. In order to get rollbar-android
to process the exception and add its information to the occurrence, all you need to do replace the io.flutter.plugin.common.MethodChannel
instance in your Android code, with com.rollbar.flutter.RollbarMethodChannel
, eg.:
public class MainActivity extends FlutterActivity implements MethodChannel.MethodCallHandler {
private static final String CHANNEL = "com.example.flutter/activity";
@Override
public void configureFlutterEngine(@NonNull FlutterEngine flutterEngine) {
super.configureFlutterEngine(flutterEngine);
new RollbarMethodChannel(
flutterEngine.getDartExecutor().getBinaryMessenger(),
CHANNEL).setMethodCallHandler(this);
}
}
No other code changes are necessary.
iOS
When handleUncaughtErrors
is set to true
, there will be a separate rollbar-ios
notifier initialized which will report crashes to Rollbar.
Platform logs
Platform log collection (via Logcat on Android, and NSLog on iOS) can be enabled by setting includePlatformLogs
to true
in the configuration.
Note this will increase the size of the payload significantly, since log information can get very large.
Symbolication / Deobfuscation
If you use obfuscating the Dart code in your Flutter application, reported stack traces will not be very useful in most cases.
Rollbar provides a way for you to upload the symbols file generated during the obfuscation process so that stack traces can be symbolicated as they are reported.
Here is an example cURL command to upload a symbols file:
curl 'https://api.rollbar.com/api/1/fluttersymbols' \
-F access_token=POST_SERVER_ITEM_ACCESS_TOKEN \
-F version=0.0.10 \
-F [email protected]/to/symbols/file
Where version
matches the codeVersion
set in your rollbar-flutter
configuration, corresponding to the version the symbols file was generated for.
After uploading, any future reported errors for the specified version will automatically be symbolicated using the symbols file.
Flutter symbols can also be managed through the project setting's page.
Help / Support
If you run into any issues, please email us at [email protected]
.
For bug reports, please open an issue on GitHub.
Updated 3 months ago