littlefish_observability_sentry 1.4.2

The implementation of the littlefish sentry observability package

littlefish_observability_sentry

The Sentry implementation of the littlefish observability package for error tracking and crash reporting.

Features

• Error and exception logging via Sentry
• User identification for error tracking
• Custom key-value pairs for error context
• Automatic crash reporting

Getting Started

Add this package to your pubspec.yaml:

dependencies:
  littlefish_observability_sentry: ^1.0.0

Usage

import 'package:littlefish_observability_sentry/sentry_observability_service.dart';

// Initialize the service
final observabilityService = SentryObservabilityService();
await observabilityService.initialise(
  settings: ObservabilitySettings(
    enabled: true,
    configuration: {
      'dsn': 'YOUR_SENTRY_DSN',
    },
  ),
);

// Log errors
await observabilityService.logError(
  exception,
  stackTrace: stackTrace,
  reason: 'Something went wrong',
);

// Set user context
await observabilityService.setUserId('user123');

// Add custom context
await observabilityService.setCustomKey('feature', 'checkout');

Configuration

The ObservabilitySettings.configuration map supports the following keys:

• dsn (required): Your Sentry DSN
• environment: The environment name (e.g., 'production', 'staging')
• release: The release version
• tracesSampleRate: Sample rate for performance monitoring (0.0 to 1.0)
• profilesSampleRate: Sample rate for profiling (0.0 to 1.0)
• sendDefaultPii: Whether to send default PII (default: false)
• attachScreenshot: Enable automatic screenshot capture on errors (default: false)
• attachViewHierarchy: Enable view hierarchy capture on errors (default: false)

Screenshot Capture

To enable automatic screenshot capture when errors occur, set attachScreenshot: true in the configuration:

await observabilityService.initialise(
  settings: ObservabilitySettings(
    enabled: true,
    configuration: {
      'dsn': 'YOUR_SENTRY_DSN',
      'attachScreenshot': true,
    },
  ),
);

Important: For screenshot capture to work, your app must wrap the root widget using the getAppWrapper() method:

void main() async {
  // Initialize observability service first
  await observabilityService.initialise(
    settings: ObservabilitySettings(
      enabled: true,
      configuration: {
        'dsn': 'YOUR_SENTRY_DSN',
        'attachScreenshot': true,
      },
    ),
  );
  
  // Get the wrapper from the service (returns null if not needed)
  final wrapper = observabilityService.getAppWrapper();
  
  // Use the wrapper if available
  runApp(wrapper != null ? wrapper(MyApp()) : MyApp());
}

The getAppWrapper() method returns an ObservabilityWidgetWrapper function that wraps your root widget. This abstraction allows your app to use screenshot capture without directly referencing Sentry packages.

Screenshots are captured automatically when errors are logged and will appear as attachments in the Sentry dashboard. Note that screenshots may contain PII, so this feature is opt-in.

Note

If Sentry is already initialized elsewhere in your application, this service will detect it and use the existing instance without re-initializing.