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;
+    _configureDebugLogger();
     if (_debug == true &&
         (log == noOpLog || diagnosticLog?.logger == noOpLog)) {
       log = debugLog;
@@ -175,7 +176,18 @@ class SentryOptions {
   bool _debug = false;
 
   /// minimum LogLevel to be used if debug is enabled
-  SentryLevel diagnosticLevel = _defaultDiagnosticLevel;
+  SentryLevel get diagnosticLevel => _diagnosticLevel;
+
+  set diagnosticLevel(SentryLevel newValue) {
+    _diagnosticLevel = newValue;
+    _configureDebugLogger();
+  }
+
+  SentryLevel _diagnosticLevel = _defaultDiagnosticLevel;
+
+  void _configureDebugLogger() {
+    SentryDebugLogger.configure(isEnabled: _debug, minLevel: _diagnosticLevel);
+  }
 
   /// Sentry client name used for the HTTP authHeader and userAgent eg
   /// sentry.{language}.{platform}/{version} eg sentry.java.android/2.0.0 would be a valid case

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,158 @@
+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('configuration', () {
+      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));
+      });
+
+      test('SentryOptions.debug enables logger', () {
+        final options = defaultTestOptions();
+
+        expect(options.debug, isFalse);
+        options.debug = true;
+
+        expect(SentryDebugLogger.isEnabled, isTrue);
+      });
+
+      test('SentryOptions.diagnosticLevel sets minLevel when set before debug',
+          () {
+        final options = defaultTestOptions();
+
+        options.diagnosticLevel = SentryLevel.error;
+        options.debug = true;
+
+        expect(SentryDebugLogger.isEnabled, isTrue);
+        expect(SentryDebugLogger.minLevel, equals(SentryLevel.error));
+      });
+
+      test(
+          'SentryOptions.diagnosticLevel updates minLevel when set after debug',
+          () {
+        final options = defaultTestOptions();
+
+        options.debug = true;
+        expect(SentryDebugLogger.minLevel, equals(SentryLevel.warning));
+
+        options.diagnosticLevel = SentryLevel.error;
+
+        expect(SentryDebugLogger.isEnabled, isTrue);
+        expect(SentryDebugLogger.minLevel, equals(SentryLevel.error));
+      });
+    });
+
+    group('logging when enabled', () {
+      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('accepts error object', () {
+        expect(
+          () => debugLogger.error(
+            'error occurred',
+            error: Exception('test exception'),
+          ),
+          returnsNormally,
+        );
+      });
+
+      test('accepts stackTrace', () {
+        expect(
+          () => debugLogger.error(
+            'error occurred',
+            error: Exception('test'),
+            stackTrace: StackTrace.current,
+          ),
+          returnsNormally,
+        );
+      });
+    });
+
+    group('logger instances', () {
+      test('debugLogger constant is available', () {
+        expect(debugLogger, isA<SentryDebugLogger>());
+      });
+
+      test('can create logger with custom name', () {
+        const customLogger = SentryDebugLogger('sentry.flutter');
+
+        SentryDebugLogger.configure(isEnabled: true);
+
+        expect(
+          () => customLogger.info('test from flutter logger'),
+          returnsNormally,
+        );
+      });
+    });
+  });
+}