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:

1. Add the package to your pubspec.yaml file:

dependencies:
  rollbar_dart: 0.1.0

2. 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

If 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:

1. Add the package to your pubspec.yaml file:

dependencies:
  rollbar_flutter: 0.1.0

2. 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.