flex_logger_sentry 1.0.0

Sentry integration for FlexLogger - provides error reporting and crash analytics capabilities.

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

FlexLogger Level	Default Filter	Destination in Sentry	Visible in Sentry as
debug	❌ Not sent	Breadcrumb only	Trail in "Breadcrumbs" (no issue)
info	❌ Not sent	Breadcrumb only	Trail in "Breadcrumbs" (no issue)
success	❌ Not sent	Breadcrumb only	Trail in "Breadcrumbs" (no issue)
warning	❌ Not sent	Breadcrumb + Event	New issue + breadcrumb trail
error	✅ Sent	Breadcrumb + Event	New issue + breadcrumb trail
critical	✅ Sent	Breadcrumb + Event	New issue (fatal) + breadcrumb trail

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

Filter (example)	Sent to Sentry	Not sent
MinLevelFilter(FlexLogLevel.debug)	Everything (debug→critical)	—
MinLevelFilter(FlexLogLevel.info)	info, success, warning, error, critical	debug
MinLevelFilter(FlexLogLevel.warning)	warning, error, critical	debug, info, success
MinLevelFilter(FlexLogLevel.error)	error, critical	debug, info, success, warning
MinLevelFilter(FlexLogLevel.critical)	critical only	debug, info, success, warning, error
MultiTypeFilter([ErrorLog, CriticalLog])	error, critical	debug, info, success, warning

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

FlexLogger Level	Sentry Level	When sent, behavior
debug	debug	Breadcrumb only – context for future errors
info	info	Breadcrumb only – context for future errors
success	info	Breadcrumb only – context for future errors
warning	warning	Breadcrumb + Event – context + creates issue
error	error	Breadcrumb + Event – context + creates issue
critical	fatal	Breadcrumb + Event – context + creates critical issue

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

Parameter	Type	Default	Description
dsn	String	required	Your Sentry project DSN
filter	LogFilter	MinLevelFilter(FlexLogLevel.error)	Filter to determine which logs to send
optionsConfiguration	void Function(SentryFlutterOptions)?	null	Callback to configure all Sentry options

Available Filters

Filter	Description	Example
MinLevelFilter	Filter by minimum log level	MinLevelFilter(FlexLogLevel.warning)
TypeFilter	Filter specific log type	TypeFilter<ErrorLog>()
MultiTypeFilter	Filter multiple log types	MultiTypeFilter([ErrorLog, CriticalLog])
DevelopmentOnlyFilter	Only log in development mode	DevelopmentOnlyFilter()
CompositeLogFilter	Combine multiple filters	CompositeLogFilter.and([...])

Common Sentry Options (via optionsConfiguration)

Option	Type	Default	Description
environment	String?	null	Environment name (dev/staging/prod)
release	String?	null	Release version
sampleRate	double?	null	Error sampling rate (0.0-1.0)
tracesSampleRate	double?	null	Performance sampling rate (0.0-1.0)
captureFailedRequests	bool	true	Capture HTTP request failures
debug	bool	false	Enable debug mode
attachScreenshot	bool	false	Attach screenshots on errors
enableAutoPerformanceTracing	bool	true	Enable automatic performance tracking
beforeSend	Function?	null	Modify/filter events before sending

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.