Version License CI codecov

This package provides a Sentry integration for Couchbase Lite with support for recording breadcrumbs and performance tracing.

The Couchbase Lite API is provided by cbl, which you always need, to use Couchbase Lite. Which other packages you need depends on the target platform and features you want to use:

PackageRequired when you want to:PubLikesPointsPopularity
cbluse Couchbase Lite.
cbl_dartuse Couchbase Lite in a Dart app (e.g. CLI) or in Flutter unit tests.
cbl_flutteruse Couchbase Lite in a Flutter app.
cbl_flutter_ceuse the Community Edition in a Flutter app.
cbl_flutter_eeuse the Enterprise Edition in a Flutter app.
cbl_sentryintegrate Couchbase Lite with Sentry in a Dart or Flutter app.
cbl_generatorgenerated Dart code to access data trough a typed data model.

This package is in beta. Use it with caution and report any issues you see.

Table of contents

🤩 Features

  • Record log messages as Sentry breadcrumbs
  • Record CBL Dart API usage as Sentry breadcrumbs
  • Record CBL Dart operations as Sentry transaction spans

⛔ Limitations

Sentry currently does not support binding transaction spans to zones. This means there can only be one global transaction span that integrations can transparently access. To support more advanced use cases, this package provides a mechanism to bind transaction spans to zones. This mechanism will be removed if and when Sentry supports this natively.

🔌 Getting started

To get started just add the CouchbaseLiteIntegration when configuring Sentry:

import 'package:cbl_sentry/cbl_sentry.dart';
import 'package:sentry/sentry.dart';

void main() {
  Sentry.init(
    (options) {
      options
        ..dsn = ...
        // While testing your Sentry configuration, make sure that all traces are sampled.
        ..tracesSampleRate = 1
        // Add the CBL Dart integration.
        ..addIntegration(CouchbaseLiteIntegration());
    },
    appRunner: () async {
      runApp(MyApp());
    }
  );
}

To find out about configurable options, see the documentation of CouchbaseLiteIntegration.

Note: Make sure you don't install a TracingDelegate when using the CouchbaseLiteIntegration. The integration has to be able to install a TracingDelegate itself.

Performance tracing

This integration only records transaction spans when a transaction has been started and a child span of the transaction is available in the environment.

To find a span, the integration uses cblSentrySpan. This is a getter that returns either a span that has been bound to the current zone or as a fallback the result of Sentry.getSpan(). To bind a span to a zone use runWithCblSentrySpan.

The following code snippet shows functions that are useful to trace the performance of operations in an app:

Future<T> runAppTransaction<T>(String name, Future<T> Function() fn) =>
    _runAppSpan(Sentry.startTransaction(name, 'task'), fn);

Future<T> runAppOperation<T>(String name, Future<T> Function() fn) =>
    _runAppSpan(cblSentrySpan!.startChild(name), fn);

Future<T> _runAppSpan<T>(ISentrySpan span,Future<T> Function() fn) async {
  try {
    return await runWithCblSentrySpan(span, fn);
    // ignore: avoid_catches_without_on_clauses
  } catch (e) {
    span
      ..throwable = e
      ..status = const SpanStatus.internalError();
    rethrow;
  } finally {
    span.status ??= const SpanStatus.ok();
    await span.finish();
  }
}

A app operation like the one below is traced as a transaction span, with CBL Dart operations as child spans:

Future<void> queryDatabase() => runAppOperation('queryDatabase', () async {
      final query = await Query.fromN1ql(
        db,
        'SELECT * FROM example WHERE age >= 28 OR name LIKE "A%"',
      );
      final resultSet = await query.execute();
      final results = await resultSet
          .asStream()
          .map((result) => result.toPlainMap())
          .toList();

      prettyPrintJson(results);
    });

Sentry Trace Example)

💡 Where to go next

🤝 Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Please make sure to update tests as appropriate.

Read CONTRIBUTING to get started developing.

⚖️ Disclaimer

⚠️ This is not an official Couchbase product.

Libraries

cbl_sentry