flex_logger_sentry #

Send FlexLogger logs to Sentry as breadcrumbs and events for error tracking and crash analytics in Flutter apps.

Contents #

• Features
• Installation
• Setup
• Usage
• Log Level Mapping
• Configuration Options
• License

Features #

• Error tracking – Exceptions/errors in logs trigger Sentry.captureException via observer's onException/onError
• Level mapping – FlexLogLevel.toSentryLevel() extension (success → info, critical → fatal)
• Breadcrumbs – All logs that pass the filter are added as breadcrumbs; warning/error/critical also create events (issues)
• Filtering – Default MinLevelFilter(FlexLogLevel.error); override with any LogFilter
• Sentry options – Optional optionsConfiguration callback for SentryFlutterOptions

Installation #

Add this to your package's pubspec.yaml file:

dependencies:
  flex_logger: ^1.0.0
  flex_logger_sentry: ^1.0.0

Then run:

flutter pub get

Setup #

1. Get Sentry DSN #

First, create a project in Sentry and get your DSN.

2. Basic Setup #

import 'package:flex_logger/flex_logger.dart';
import 'package:flex_logger_sentry/flex_logger_sentry.dart';

void main() async {
  FlexLogger.instance.configure(
    providers: [
      SentryLoggerProvider(
        dsn: 'YOUR_SENTRY_DSN_HERE',
        filter: const MinLevelFilter(FlexLogLevel.warning),
        optionsConfiguration: (options) {
          options.environment = 'production';
          options.release = '1.0.0';
        },
      ),
    ],
  );
  await FlexLogger.instance.initialize();

  runApp(MyApp());
}

3. Advanced Configuration #

SentryLoggerProvider(
  dsn: 'YOUR_SENTRY_DSN_HERE',
  // Filter only errors and above
  filter: const MinLevelFilter(FlexLogLevel.error),
  optionsConfiguration: (options) {
    // Basic configuration
    options.environment = 'production';
    options.release = '1.0.0';
    
    // Sampling rates
    options.sampleRate = 1.0;                 // 100% of errors
    options.tracesSampleRate = 0.1;           // 10% of transactions for performance
    
    // Features
    options.captureFailedRequests = true;     // Capture HTTP failures
    options.attachScreenshot = true;          // Attach screenshots on errors
    options.enableAutoPerformanceTracing = true;
    
    // Custom event filtering
    options.beforeSend = (event, hint) {
      // Add custom logic to modify or filter events
      return event;
    };
  },
)

4. Using Different Filters #

// Type-based filtering - only specific log types
SentryLoggerProvider(
  dsn: 'YOUR_SENTRY_DSN_HERE',
  filter: const MultiTypeFilter([ErrorLog, CriticalLog]),
)

// Composite filtering - combine multiple conditions
SentryLoggerProvider(
  dsn: 'YOUR_SENTRY_DSN_HERE',
  filter: CompositeLogFilter.and([
    MinLevelFilter(FlexLogLevel.warning),
    DevelopmentOnlyFilter(), // Only in development
  ]),
)

Usage #

Once configured, logs that pass the provider's filter are sent to Sentry (breadcrumbs and/or events). Use FlexLogger as usual:

import 'package:flex_logger/flex_logger.dart';

void doSomething() {
  try {
    FlexLogger.instance.info('Operation completed successfully');
  } catch (error, stackTrace) {
    FlexLogger.instance.error('Operation failed', error, stackTrace);
  }
}

Exceptions and errors in logs are captured by the Sentry observer via onException / onError and sent with Sentry.captureException.

Log Level Mapping #

Quick reference: What appears in Sentry #

Use filters to control which logs are sent to Sentry. The default filter is MinLevelFilter(FlexLogLevel.error).
With MinLevelFilter(X), logs of level X and above are sent (e.g., MinLevelFilter(FlexLogLevel.info) sends info, success, warning, error, and critical).

Not sent at all: Logs that don't pass the filter are never sent to Sentry.

Important: All logs that pass the filter are added as breadcrumbs to provide context. Warning, error, and critical logs are ALSO sent as events to create issues in Sentry. This follows Sentry's best practices for providing context in error reports.

Effect of different filters – what is sent vs. not sent #

Example: With filter: MinLevelFilter(FlexLogLevel.warning), only warning, error, and critical logs are sent. debug/info/success never reach Sentry. Among those sent, warning/error/critical create events (issues); we do not add an extra breadcrumb for the same message.

Sentry level mapping #

Breadcrumbs vs Events Strategy #

Following Sentry's best practices, all logs are added as breadcrumbs to provide context:

All levels (debug/info/success/warning/error/critical):

• ✅ Always added as breadcrumb – provides context trail for error analysis
• Appear in the "Breadcrumbs" section when viewing issues in Sentry
• Example: User actions, navigation, state changes, warnings leading to errors

Warning/Error/Critical levels additionally:

• ✅ Also create events/issues in Sentry dashboard (when they don't contain exceptions)
• These issues include all previous breadcrumbs as context
• Uses captureMessage for message-only events
• Example: Payment failures, validation errors, business logic warnings

Logs with exceptions:

• ✅ Use captureException instead of captureMessage
• Provides full stack traces and exception details
• Automatically triggered when logs contain error or stackTrace fields
• Example: Unhandled exceptions, caught errors with stack traces

Why both? When an error occurs, you see the full context:

Issue: "Payment processing failed"
  Breadcrumbs:
    [info] User logged in
    [debug] Loaded payment methods
    [success] Cart validated
    [warning] Payment validation slow  ← Context!
    [error] Payment processing failed  ← Issue created here

This approach ensures warnings appear as context for later errors, following Sentry's recommended pattern.

Configuration Options #

SentryLoggerProvider Parameters #

Available Filters #

Common Sentry Options (via optionsConfiguration) #

See SentryFlutterOptions for all available options.

Where to go next #

• API reference – pub.dev package page for API docs.
• FlexLogger – Core package: flex_logger.
• Sentry for Flutter – Sentry Flutter documentation.
• Issues and contributing – issue tracker.

License #

This project is licensed under the MIT License - see the LICENSE file for details.