+Add support for isolates and write tests

robelator · robelator · commit c5d2c1d6a961 · 2026-02-13T11:14:10.000+10:00
diff --git a/ARTICLE.md b/ARTICLE.md
@@ -275,7 +275,8 @@ Here is a quick reference to all the main features available.
 
 ### Configuration (Static Properties on Log)
 
-- `Log.enableStyling = true`: Enables/disables ANSI colors and icons. Set this to false if your terminal does not supprt ANSI colors.
+- `Log.context = 'MAIN'`: Labels the current isolate. Shows inside the log brackets so you can tell which isolate printed what.
+- `Log.enableStyling = true`: Enables/disables ANSI colors and icons. Set this to false if your terminal does not support ANSI colors.
 - `Log.showTimestamps = true`: Shows a HH:mm:ss.SSS timestamp on each log.
 - `Log.showTags = true`: Shows tags like #auth #ui on each log.
 - `Log.showIds = false`: Shows a unique ID on each log.
@@ -286,8 +287,32 @@ Here is a quick reference to all the main features available.
 - `Log.storeLogs = true`: If true, keeps a history of logs in memory.
 - `Log.maxStoredLogs = 50`: Sets the max number of LogItem objects to store.
 - `Log.items`: A `Queue<LogItem>` containing the stored logs.
+- `Log.clear()`: Clears all stored logs.
 - `Log.addCallback(callback)`: Registers a function void `Function(LogItem item)` that runs for every log.
 - `Log.removeCallback(callback)`: Removes a previously registered callback.
+- `Log.onLogDiscarded`: Called when old logs are removed from the queue (when full).
+- `Log.exportLogsAsJsonLines()`: Exports all stored logs as a JSONL string.
+
+### Multi-Isolate Debugging
+
+In Dart, each isolate has its own memory. All `Log` statics (`context`, `items`, `activeTags`, etc.) are independent per isolate. Set `Log.context` at the start of each isolate to label it:
+
+```dart
+void main() {
+  Log.context = 'MAIN';
+  runApp(const App());
+}
+
+@pragma("vm:entry-point")
+void overlayMain() {
+  Log.context = 'OVERLAY';
+  runApp(const Overlay());
+}
+```
+
+Output: `[🟣 app #43 MAIN] Starting payment...` vs `[🟣 overlay #12 OVERLAY] Rendering widget`
+
+This works on all platforms including web.
 
 ### Advanced Output
 
diff --git a/README.md b/README.md
@@ -4,7 +4,7 @@
 [![tag](https://img.shields.io/badge/Tag-v0.3.30-purple?logo=github)](https://github.com/dev-cetera/df_log/tree/v0.3.30)
 [![buymeacoffee](https://img.shields.io/badge/Buy%20Me%20A%20Coffee-FFDD00?logo=buy-me-a-coffee&logoColor=black)](https://www.buymeacoffee.com/dev_cetera)
 [![sponsor](https://img.shields.io/badge/Sponsor-grey?logo=github-sponsors&logoColor=pink)](https://github.com/sponsors/dev-cetera)
-[![patreon](https://img.shields.io/badge/Patreon-grey?logo=patreon)](https://www.patreon.com/t0mb3rr)
+[![patreon](https://img.shields.io/badge/Patreon-grey?logo=patreon)](https://www.patreon.com/robelator)
 [![discord](https://img.shields.io/badge/Discord-5865F2?logo=discord&logoColor=white)](https://discord.gg/gEQ8y2nfyX)
 [![instagram](https://img.shields.io/badge/Instagram-E4405F?logo=instagram&logoColor=white)](https://www.instagram.com/dev_cetera/)
 [![license](https://img.shields.io/badge/License-MIT-blue.svg)](https://raw.githubusercontent.com/dev-cetera/df_log/main/LICENSE)
@@ -24,6 +24,8 @@
 - **Release Mode Control:** Configure logs and assertions to be active even in release builds.
 - **Customizable Output:** Show or hide timestamps, log IDs, and tags.
 - **IDE Integration:** Optionally uses `dart:developer`'s `log` function for a richer experience in some IDEs.
+- **Isolate-Friendly:** Set `Log.context` per isolate to instantly see where logs come from. Works on web too.
+- **Log Export:** Export stored logs as JSONL with `Log.exportLogsAsJsonLines()`.
 - **Extensible:** Add custom callbacks to integrate with other services (e.g., crash reporting).
 
 ## 📸 Screenshot
@@ -100,12 +102,40 @@ void main() {
 }
 ```
 
-### 💡 3. Configuration
+### 💡 4. Isolate Context
+
+When debugging across isolates, set `Log.context` at the start of each isolate. Since Dart statics are per-isolate, each isolate gets its own value automatically - no locking, no shared state, no complexity.
+
+```dart
+void main() {
+  Log.context = 'MAIN';
+  Log.info('Starting app');
+  // Output: [🟣 example #5 MAIN] Starting app
+  runApp(const App());
+}
+
+@pragma("vm:entry-point")
+void overlayMain() {
+  Log.context = 'OVERLAY';
+  Log.info('Overlay started');
+  // Output: [🟣 example #5 OVERLAY] Overlay started
+  runApp(const Overlay());
+}
+```
+
+Use a short tag like `M` to save space, or a full string like `ISOLATE_MAIN` for clarity.
+
+**How it works:** In Dart, each isolate has its own memory. All `Log` statics (`context`, `items`, `activeTags`, etc.) are independent per isolate. This means `Log.context = 'OVERLAY'` in one isolate has zero effect on another. The only shared thing is the console output (stdout), which is why `Log.context` exists - so you can tell which isolate printed what. This works on all platforms including web.
+
+### 💡 5. Configuration
 
 You can customize the logging behavior to suit your needs, including styling, output format, and storage options. The Log class provides various settings to control how logs are displayed and managed.
 
 ```dart
 void main() {
+  // Set a label for the current isolate (useful for multi-isolate debugging).
+  Log.context = 'MAIN';
+
    // Enable or disable ANSI colors and icons. Disable this if your console doesn't support it.
   Log.enableStyling = true;
 
@@ -142,6 +172,17 @@ void main() {
   // Remove an existing callback.
   Log.removeCallback(callback);
 
+  // Get notified when old logs are discarded from the queue.
+  Log.onLogDiscarded = (discardedItem) {
+    // TODO: Forward to analytics before it's gone.
+  };
+
+  // Clear log history.
+  Log.clear();
+
+  // Export all stored logs as a JSONL string.
+  final jsonl = Log.exportLogsAsJsonLines();
+
   runApp(MyApp());
 }
 ```
diff --git a/TODO.md b/TODO.md
diff --git a/_README_CONTENT.md b/_README_CONTENT.md
@@ -9,6 +9,8 @@
 - **Release Mode Control:** Configure logs and assertions to be active even in release builds.
 - **Customizable Output:** Show or hide timestamps, log IDs, and tags.
 - **IDE Integration:** Optionally uses `dart:developer`'s `log` function for a richer experience in some IDEs.
+- **Isolate-Friendly:** Set `Log.context` per isolate to instantly see where logs come from. Works on web too.
+- **Log Export:** Export stored logs as JSONL with `Log.exportLogsAsJsonLines()`.
 - **Extensible:** Add custom callbacks to integrate with other services (e.g., crash reporting).
 
 ## 📸 Screenshot
@@ -85,12 +87,40 @@ void main() {
 }
 ```
 
-### 💡 3. Configuration
+### 💡 4. Isolate Context
+
+When debugging across isolates, set `Log.context` at the start of each isolate. Since Dart statics are per-isolate, each isolate gets its own value automatically - no locking, no shared state, no complexity.
+
+```dart
+void main() {
+  Log.context = 'MAIN';
+  Log.info('Starting app');
+  // Output: [🟣 example #5 MAIN] Starting app
+  runApp(const App());
+}
+
+@pragma("vm:entry-point")
+void overlayMain() {
+  Log.context = 'OVERLAY';
+  Log.info('Overlay started');
+  // Output: [🟣 example #5 OVERLAY] Overlay started
+  runApp(const Overlay());
+}
+```
+
+Use a short tag like `M` to save space, or a full string like `ISOLATE_MAIN` for clarity.
+
+**How it works:** In Dart, each isolate has its own memory. All `Log` statics (`context`, `items`, `activeTags`, etc.) are independent per isolate. This means `Log.context = 'OVERLAY'` in one isolate has zero effect on another. The only shared thing is the console output (stdout), which is why `Log.context` exists - so you can tell which isolate printed what. This works on all platforms including web.
+
+### 💡 5. Configuration
 
 You can customize the logging behavior to suit your needs, including styling, output format, and storage options. The Log class provides various settings to control how logs are displayed and managed.
 
 ```dart
 void main() {
+  // Set a label for the current isolate (useful for multi-isolate debugging).
+  Log.context = 'MAIN';
+
    // Enable or disable ANSI colors and icons. Disable this if your console doesn't support it.
   Log.enableStyling = true;
 
@@ -127,6 +157,17 @@ void main() {
   // Remove an existing callback.
   Log.removeCallback(callback);
 
+  // Get notified when old logs are discarded from the queue.
+  Log.onLogDiscarded = (discardedItem) {
+    // TODO: Forward to analytics before it's gone.
+  };
+
+  // Clear log history.
+  Log.clear();
+
+  // Export all stored logs as a JSONL string.
+  final jsonl = Log.exportLogsAsJsonLines();
+
   runApp(MyApp());
 }
 ```
diff --git a/analysis_options.yaml b/analysis_options.yaml
@@ -1,4 +1,5 @@
-# Dev-Cetera analysis_options.yaml for Dart - Version 1
+# For dev-cetera.com
+# Version: 1
 
 include: package:lints/recommended.yaml
 
@@ -9,7 +10,6 @@ linter:
     avoid_web_libraries_in_flutter: true
     camel_case_types: false
     constant_identifier_names: false
-    directives_ordering: true
     file_names: false
     library_private_types_in_public_api: false
     non_constant_identifier_names: false
@@ -19,6 +19,7 @@ linter:
     prefer_final_fields: true
     prefer_function_declarations_over_variables: false
     prefer_relative_imports: true
+    prefer_single_quotes: true
     require_trailing_commas: true
     unawaited_futures: true
     unnecessary_this: true
@@ -32,24 +33,24 @@ analyzer:
     strict-raw-types: true
   exclude:
     - build/**
+    # - '**.g.dart'
 
   errors:
     always_declare_return_types: error
     avoid_renaming_method_parameters: error
     avoid_type_to_string: error
+    close_sinks: error
+    collection_methods_unrelated_type: error
     depend_on_referenced_packages: error
     flutter_style_todos: error
     invalid_override_of_non_virtual_member: error
     invalid_use_of_protected_member: error
+    missing_return: error
     no_leading_underscores_for_local_identifiers: error
     prefer_final_in_for_each: error
     prefer_relative_imports: error
-    prefer_single_quotes: error
-    unnecessary_async: error
-    unnecessary_await_in_return: error
-    unnecessary_late: error
+    record_literal_one_positional_no_trailing_comma: error
     unnecessary_new: error
-    unnecessary_unawaited: error
     unrelated_type_equality_checks: error
     unused_label: ignore
     use_key_in_widget_constructors: error
diff --git a/lib/src/log.dart b/lib/src/log.dart
@@ -25,7 +25,28 @@ final class Log {
   //
   //
 
-  /// A filter for console output. A log is printed if untagged, or if ALL of
+  /// A custom label for the current isolate or execution context.
+  ///
+  /// Set this at the start of each isolate to identify where logs come from.
+  /// Displayed inside the square brackets of the log output.
+  ///
+  /// Dart statics are per-isolate, so each isolate gets its own value.
+  ///
+  /// ```dart
+  /// void main() {
+  ///   Log.context = 'MAIN';
+  ///   runApp(const App());
+  /// }
+  ///
+  /// @pragma("vm:entry-point")
+  /// void overlayMain() {
+  ///   Log.context = 'OVERLAY';
+  ///   runApp(const Overlay());
+  /// }
+  /// ```
+  static String? context;
+
+  /// A filter for console output. A log is printed if untagged, or if any of
   /// its tags are present in this set.
   static var activeTags = {#debug, ..._IconCategory.values.map((e) => e.tag)};
 
@@ -52,13 +73,18 @@ final class Log {
   static set maxStoredLogs(int value) {
     _maxStoredLogs = value < 0 ? 0 : value;
     while (items.length > _maxStoredLogs) {
-      items.removeFirst();
+      final discarded = items.removeFirst();
+      onLogDiscarded?.call(discarded);
     }
   }
 
   /// An in-memory queue of the most recent log items, capped by `maxStoredLogs`.
   static final items = Queue<LogItem>();
 
+  /// Called when the log queue is full and the oldest log is about to be
+  /// discarded. Receives the [LogItem] being removed.
+  static void Function(LogItem discardedItem)? onLogDiscarded;
+
   /// If `true`, enables colors and other ANSI styling in the console output.
   static var enableStyling = false;
 
@@ -105,6 +131,20 @@ final class Log {
   /// The internal function used for printing. Defaults to the standard `print`.
   static void Function(Object?) _printFunction = print;
 
+  /// Clears the in-memory log history.
+  static void clear() => items.clear();
+
+  /// Exports all stored logs as a JSONL string (one JSON object per line).
+  ///
+  /// Web-safe. Use however you want: save to file, send to a server, etc.
+  static String exportLogsAsJsonLines() {
+    final buffer = StringBuffer();
+    for (final item in items) {
+      buffer.writeln(item.toJson(pretty: false));
+    }
+    return buffer.toString();
+  }
+
   //
   //
   //
@@ -536,14 +576,15 @@ final class Log {
       showTags: showTags,
       showTimestamp: showTimestamps,
       frame: frame,
+      context: context,
     );
 
     // Remove old logs.
-    if (storeLogs) {
-      if (items.length >= maxStoredLogs) {
-        items.removeFirst();
+    if (storeLogs && maxStoredLogs > 0) {
+      while (items.length >= maxStoredLogs) {
+        final discarded = items.removeFirst();
+        onLogDiscarded?.call(discarded);
       }
-      // Maybe store new logs.
       items.add(logItem);
     }
 
diff --git a/lib/src/log_item.dart b/lib/src/log_item.dart
@@ -29,6 +29,7 @@ final class LogItem {
   final Object? message;
   final Object? metadata;
   final Set<Symbol> tags;
+  final String? context;
   final int internalIndex;
   static int _internalCount = 0;
 
@@ -55,6 +56,7 @@ final class LogItem {
     required this.showTags,
     required this.showTimestamp,
     required this.frame,
+    required this.context,
   }) : id = const Uuid().v4(),
        timestamp = DateTime.now(),
        internalIndex = _internalCount++;
@@ -73,6 +75,9 @@ final class LogItem {
         buffer.write('$icon ');
       }
       buffer.write(location);
+      if (context != null && context!.isNotEmpty) {
+        buffer.write(' $context');
+      }
       if (showTimestamp) {
         final isoString = timestamp.toLocal().toIso8601String();
         final timeStr = isoString.substring(11, 23);
@@ -121,7 +126,9 @@ final class LogItem {
       }
       buffer.write('['.withAnsiStyle(bracketStyle));
       buffer.write(location1.withAnsiStyle(pathTextStyle));
-
+      if (context != null && context!.isNotEmpty) {
+        buffer.write(' $context'.withAnsiStyle(bracketStyle));
+      }
       if (showTimestamp) {
         final isoString = timestamp.toLocal().toIso8601String();
         final timeStr = isoString.substring(11, 23);
@@ -163,6 +170,7 @@ final class LogItem {
     return {
       'id': id,
       'column': column,
+      'context': context,
       'icon': icon != null && (location != null && location!.isNotEmpty)
           ? icon
           : null,
diff --git a/pubspec.yaml b/pubspec.yaml
diff --git a/test/df_log_test.dart b/test/df_log_test.dart
