enh(internal): debug log api

packages/dart/lib/sentry.dart

@@ -61,3 +61,5 @@ export 'src/utils/url_details.dart';
 // ignore: invalid_export_of_internal_element
 export 'src/utils/breadcrumb_log_level.dart';
 export 'src/sentry_logger.dart';
+// ignore: invalid_export_of_internal_element
+export 'src/utils/debug_logger.dart' show SentryDebugLogger;

packages/dart/lib/src/sentry_options.dart

@@ -162,6 +162,7 @@ class SentryOptions {
 
   set debug(bool newValue) {
     _debug = newValue;
+    SentryDebugLogger.configure(isEnabled: _debug, minLevel: diagnosticLevel);
     if (_debug == true &&
         (log == noOpLog || diagnosticLog?.logger == noOpLog)) {
       log = debugLog;

packages/dart/lib/src/utils/debug_logger.dart

@@ -0,0 +1,106 @@
+import 'dart:developer' as dev;
+
+import 'package:meta/meta.dart';
+
+import '../../sentry.dart';
+
+/// Lightweight isolate compatible diagnostic logger for the Sentry SDK.
+///
+/// Logger naming convention:
+/// - `sentry` – core dart package
+/// - `sentry.flutter` – flutter package
+/// - `sentry.{integration}` – integration packages (dio, hive, etc.)
+///
+/// Each package should have at least one top-level instance.
+///
+/// Example:
+/// ```dart
+/// const debugLogger = SentryDebugLogger('sentry.flutter');
+///
+/// debugLogger.warning('My Message')
+///```
+@internal
+class SentryDebugLogger {
+  final String _name;
+
+  const SentryDebugLogger(this._name);
+
+  static bool _isEnabled = false;
+  static SentryLevel _minLevel = SentryLevel.warning;
+
+  @visibleForTesting
+  static bool get isEnabled => _isEnabled;
+
+  @visibleForTesting
+  static SentryLevel get minLevel => _minLevel;
+
+  /// Configure logging for the current isolate.
+  ///
+  /// This needs to be called for each new spawned isolate before logging.
+  static void configure({
+    required bool isEnabled,
+    SentryLevel minLevel = SentryLevel.warning,
+  }) {
+    _isEnabled = isEnabled;
+    _minLevel = minLevel;
+  }
+
+  void debug(
+    String message, {
+    Object? error,
+    StackTrace? stackTrace,
+  }) =>
+      _log(SentryLevel.debug, message, error: error, stackTrace: stackTrace);
+
+  void info(
+    String message, {
+    Object? error,
+    StackTrace? stackTrace,
+  }) =>
+      _log(SentryLevel.info, message, error: error, stackTrace: stackTrace);
+
+  void warning(
+    String message, {
+    Object? error,
+    StackTrace? stackTrace,
+  }) =>
+      _log(SentryLevel.warning, message, error: error, stackTrace: stackTrace);
+
+  void error(
+    String message, {
+    Object? error,
+    StackTrace? stackTrace,
+  }) =>
+      _log(SentryLevel.error, message, error: error, stackTrace: stackTrace);
+
+  void fatal(
+    String message, {
+    Object? error,
+    StackTrace? stackTrace,
+  }) =>
+      _log(SentryLevel.fatal, message, error: error, stackTrace: stackTrace);
+
+  @pragma('vm:prefer-inline')
+  void _log(
+    SentryLevel level,
+    String message, {
+    Object? error,
+    StackTrace? stackTrace,
+  }) {
+    if (!_isEnabled) return;
+    if (level.ordinal < _minLevel.ordinal) return;
+
+    dev.log(
+      '[${level.name}] $message',
+      name: _name,
+      level: level.toDartLogLevel(),
+      error: error,
+      stackTrace: stackTrace,
+      time: DateTime.now(),
+    );
+  }
+}
+
+/// Logger for the Sentry Dart SDK.
+@internal
+const debugLogger = SentryDebugLogger('sentry');

packages/dart/test/utils/debug_logger_test.dart

@@ -0,0 +1,148 @@
+import 'package:sentry/sentry.dart';
+import 'package:sentry/src/utils/debug_logger.dart';
+import 'package:test/test.dart';
+
+import '../test_utils.dart';
+
+void main() {
+  group(SentryDebugLogger, () {
+    tearDown(() {
+      // Reset to default state after each test
+      SentryDebugLogger.configure(isEnabled: false);
+    });
+
+    group('configure', () {
+      test('enables logging when isEnabled is true', () {
+        SentryDebugLogger.configure(isEnabled: true);
+
+        expect(SentryDebugLogger.isEnabled, isTrue);
+      });
+
+      test('disables logging when isEnabled is false', () {
+        SentryDebugLogger.configure(isEnabled: false);
+
+        expect(SentryDebugLogger.isEnabled, isFalse);
+      });
+
+      test('sets minimum level', () {
+        SentryDebugLogger.configure(
+          isEnabled: true,
+          minLevel: SentryLevel.error,
+        );
+
+        expect(SentryDebugLogger.isEnabled, isTrue);
+        expect(SentryDebugLogger.minLevel, equals(SentryLevel.error));
+      });
+
+      test('defaults minLevel to warning', () {
+        SentryDebugLogger.configure(isEnabled: true);
+
+        expect(SentryDebugLogger.minLevel, equals(SentryLevel.warning));
+      });
+    });
+
+    group('log methods', () {
+      setUp(() {
+        SentryDebugLogger.configure(
+            isEnabled: true, minLevel: SentryLevel.debug);
+      });
+
+      test('debug logs without throwing', () {
+        expect(
+          () => debugLogger.debug('debug message'),
+          returnsNormally,
+        );
+      });
+
+      test('info logs without throwing', () {
+        expect(
+          () => debugLogger.info('info message'),
+          returnsNormally,
+        );
+      });
+
+      test('warning logs without throwing', () {
+        expect(
+          () => debugLogger.warning('warning message'),
+          returnsNormally,
+        );
+      });
+
+      test('error logs without throwing', () {
+        expect(
+          () => debugLogger.error('error message'),
+          returnsNormally,
+        );
+      });
+
+      test('fatal logs without throwing', () {
+        expect(
+          () => debugLogger.fatal('fatal message'),
+          returnsNormally,
+        );
+      });
+
+      test('logs with error object without throwing', () {
+        expect(
+          () => debugLogger.error(
+            'error occurred',
+            error: Exception('test exception'),
+          ),
+          returnsNormally,
+        );
+      });
+
+      test('logs with stackTrace without throwing', () {
+        expect(
+          () => debugLogger.error(
+            'error occurred',
+            error: Exception('test'),
+            stackTrace: StackTrace.current,
+          ),
+          returnsNormally,
+        );
+      });
+    });
+
+    group('debugLogger constant', () {
+      test('is named sentry', () {
+        // The debugLogger constant should be accessible and usable
+        expect(debugLogger, isA<SentryDebugLogger>());
+      });
+    });
+
+    group('custom logger name', () {
+      test('can create logger with custom name', () {
+        const customLogger = SentryDebugLogger('sentry.flutter');
+
+        SentryDebugLogger.configure(isEnabled: true);
+
+        expect(
+          () => customLogger.info('test from flutter logger'),
+          returnsNormally,
+        );
+      });
+    });
+
+    group('SentryOptions integration', () {
+      test('setting debug to true enables SentryDebugLogger', () {
+        final options = defaultTestOptions();
+
+        expect(options.debug, isFalse);
+        options.debug = true;
+
+        expect(SentryDebugLogger.isEnabled, isTrue);
+      });
+
+      test('diagnosticLevel is used as minLevel when debug is enabled', () {
+        final options = defaultTestOptions();
+
+        options.diagnosticLevel = SentryLevel.error;
+        options.debug = true;
+
+        expect(SentryDebugLogger.isEnabled, isTrue);
+        expect(SentryDebugLogger.minLevel, equals(SentryLevel.error));
+      });
+    });
+  });
+}

packages/flutter/lib/src/isolate/isolate_worker.dart

@@ -2,7 +2,7 @@ import 'dart:async';
 import 'dart:isolate';
 
 import '../../sentry_flutter.dart';
-import 'isolate_logger.dart';
+import '../utils/debug_logger.dart';
 
 typedef SpawnWorkerFn = Future<Worker> Function(WorkerConfig, WorkerEntry);
 
@@ -141,20 +141,18 @@ void runWorker(
   SendPort host,
   WorkerHandler handler,
 ) {
-  IsolateLogger.configure(
-    debug: config.debug,
-    level: config.diagnosticLevel,
-    loggerName: config.debugName,
-  );
+  // ignore: invalid_use_of_internal_member
+  SentryDebugLogger.configure(
+      isEnabled: config.debug, minLevel: config.diagnosticLevel);
 
   final inbox = ReceivePort();
   host.send(inbox.sendPort);
 
   inbox.listen((msg) async {
     if (msg == _shutdownCommand) {
-      IsolateLogger.log(SentryLevel.debug, 'Isolate received shutdown');
+      debugLogger.debug('${config.debugName}: isolate received shutdown');
       inbox.close();
-      IsolateLogger.log(SentryLevel.debug, 'Isolate closed');
+      debugLogger.debug('${config.debugName}: isolate closed');
       return;
     }
 
@@ -172,8 +170,8 @@ void runWorker(
     try {
       await handler.onMessage(msg);
     } catch (exception, stackTrace) {
-      IsolateLogger.log(SentryLevel.error, 'Isolate failed to handle message',
-          exception: exception, stackTrace: stackTrace);
+      debugLogger.error('${config.debugName}: isolate failed to handle message',
+          error: exception, stackTrace: stackTrace);
     }
   });
 }