flex_logger_isolate library

Isolate logging integration for FlexLogger.

This package provides isolate logging support for FlexLogger, enabling logging from Dart isolates to the main isolate's logger instance.

Features

  • IsolateLogger: A logger implementation for use in worker isolates
  • IsolateLoggerProvider: Provider for managing isolate communication
  • Automatic message routing: Logs from isolates appear in main logger
  • All log levels supported: debug, info, success, warning, error, critical
  • Custom log support: Send custom FlexLog implementations from isolates
  • Proper lifecycle management: Automatic ReceivePort cleanup with Finalizer

Quick Start

Basic Usage

import 'dart:isolate';
import 'package:flex_logger/flex_logger.dart';
import 'package:flex_logger_isolate/flex_logger_isolate.dart';
import 'package:flex_logger_console/flex_logger_console.dart';

// Main isolate setup
void main() async {
  FlexLogger.instance.configure(
    providers: [
      ConsoleLoggerProvider(),
      IsolateLoggerProvider(),
    ],
  );
  await FlexLogger.instance.initialize();

  // Create logger for worker isolate (extension – no need to pass provider around)
  final sendPort = FlexLogger.instance.initializeIsolate('worker-1');

  // Spawn worker isolate
  await Isolate.spawn(workerEntryPoint, sendPort);

  // When worker is done
  FlexLogger.instance.disposeIsolate('worker-1');

  await FlexLogger.instance.dispose();
}

// Worker isolate entry point
void workerEntryPoint(SendPort sendPort) {
  final logger = IsolateLogger(
    tag: 'worker-1',
    sendPort: sendPort,
  );

  logger.info('Worker started');
  logger.debug('Processing data...');
  logger.success('Task completed');
}

Multiple Isolates

// Create multiple workers with unique IDs
for (int i = 0; i < 4; i++) {
  final sendPort = FlexLogger.instance.initializeIsolate('worker-$i');
  await Isolate.spawn(workerEntryPoint, sendPort);
}

// Later, clean up all isolates
for (int i = 0; i < 4; i++) {
  FlexLogger.instance.disposeIsolate('worker-$i');
}

Error Handling in Isolates

void workerEntryPoint(SendPort sendPort) {
  final logger = IsolateLogger(
    tag: 'worker-1',
    sendPort: sendPort,
  );

  try {
    // Do work...
    throw Exception('Something went wrong');
  } catch (e, stackTrace) {
    logger.error('Worker failed', e, stackTrace);
  }
}

Important Notes

  • Always call FlexLogger.instance.disposeIsolate (or IsolateLoggerProvider.disposeIsolate) when an isolate is done to properly close the ReceivePort
  • Each isolate should have a unique ID for tracking
  • Logs from isolates are prefixed with [tag] LEVEL in the output (e.g. worker-1 DEBUG)
  • The provider uses a Finalizer for automatic cleanup if dispose is forgotten, but will log a warning
  • Filtering is handled by the observers configured in FlexLogger (Console, File, Sentry, etc.), not at the IsolateLoggerProvider level

Classes

IsolateCriticalLog
Critical error log from an isolate.
IsolateDebugLog
Debug log from an isolate.
IsolateErrorLog
Error log from an isolate.
IsolateInfoLog
Info log from an isolate.
IsolateLog
Base sealed class for all logs coming from isolates.
IsolateLogger
A logger implementation for use in isolates.
IsolateLoggerProvider
A logger provider that enables logging from Dart isolates.
IsolateSuccessLog
Success log from an isolate.
IsolateWarningLog
Warning log from an isolate.

Extensions

IsolateLoggerExtension on FlexLogger
Extension on FlexLogger for isolate logging.

Exceptions / Errors

SerializedError
An Error reconstructed from its string representation.
SerializedException
An Exception reconstructed from its string representation.