flex_logger_file #

Writes FlexLogger logs to local files with single-file, size-based rotation, or daily strategies.

Contents #

• Features
• Installation
• Quick Start
• API overview
• Resource management

Features #

• Three strategies – singleFile, rotating, timeBased via factory constructors; or custom FileStrategy
• Rotating – Size-based rotation; current file renamed to .1, .2, …; no logs lost
• Single file – Optional cleanup by maxFileSize and/or maxAge (buffers during cleanup)
• Time-based – One file per day; optional retention by maxAge / maxFiles
• FileFormatter – Default format [YYYY-MM-DD HH:MM:SS.mmm] [LEVEL] message; custom via LogFormatter
• Filtering – Optional LogFilter (e.g. MinLevelFilter) per provider
• Auto directory creation – Strategies create parent directories if missing
• FileStrategy – Abstract interface for custom storage (e.g. cloud, custom rotation)

Installation #

dependencies:
  flex_logger: ^1.0.0
  flex_logger_file: ^1.0.0

flutter pub get

Quick Start #

Rotating files (recommended for production) #

import 'package:flex_logger/flex_logger.dart';
import 'package:flex_logger_file/flex_logger_file.dart';
import 'package:path_provider/path_provider.dart';
import 'package:path/path.dart' as path;

Future<void> main() async {
  final appDocDir = await getApplicationDocumentsDirectory();
  final logPath = path.join(appDocDir.path, 'logs', 'app.log');

  FlexLogger.instance.configure(
    providers: [
      FileLoggerProvider.rotating(
        filePath: logPath,
        maxFileSize: 5 * 1024 * 1024, // 5 MB
        maxBackupCount: 10,
        filter: MinLevelFilter(FlexLogLevel.info),
      ),
    ],
  );
  await FlexLogger.instance.initialize();

  FlexLogger.instance.info('Application started');
  FlexLogger.instance.error('An error occurred');
}

Daily files #

FlexLogger.instance.configure(
  providers: [
    FileLoggerProvider.timeBased(
      directoryPath: appDocDir.path,
      filePrefix: 'myapp',
      maxAge: Duration(days: 30),
      maxFiles: 30,
      filter: MinLevelFilter(FlexLogLevel.debug),
    ),
  ],
);
await FlexLogger.instance.initialize();

Single file (optional cleanup) #

// No limits – file grows indefinitely
FileLoggerProvider.singleFile(filePath: logPath);

// With size and/or age limits
FileLoggerProvider.singleFile(
  filePath: logPath,
  maxFileSize: 10 * 1024 * 1024,
  maxAge: Duration(days: 7),
  cleanupCheckInterval: 100,
);

API overview #

FileLoggerProvider #

• Default constructor – FileLoggerProvider(strategy: FileStrategy, formatter?, filter?, providerId?) for custom strategies.
• FileLoggerProvider.singleFile – filePath?, maxFileSize?, maxAge?, cleanupCheckInterval: 100, formatter, filter, providerId?. Default path: <documents>/app.log.
• FileLoggerProvider.rotating – filePath? (default: <documents>/app.log), maxFileSize: 10 MB, maxBackupCount: 5, formatter, filter. Rotation renames current to .1, .2, …; oldest backup removed when count exceeded.
• FileLoggerProvider.timeBased – directoryPath?, filePrefix: 'app', maxAge?, maxFiles?, formatter, filter. File names: <filePrefix>-YYYY-MM-DD.log.

Use providerId when registering multiple file providers so each has a unique id.

FileFormatter #

Default format:

[2024-01-15 10:30:45.456] [INFO] Application started
[2024-01-15 10:30:46.789] [ERROR] An error occurred
Error: Exception: Something went wrong
Stack trace:
#0      main (file:///app.dart:10:5)
...

Long stack traces are abbreviated to 1000 characters. Use a custom LogFormatter for different output.

Custom strategy #

Implement FileStrategy (initialize, write, dispose, currentLogFilePath):

class MyCustomStrategy implements FileStrategy {
  @override
  Future<void> initialize() async { /* ... */ }

  @override
  void write(String formattedLog) { /* ... */ }

  @override
  Future<void> dispose() async { /* ... */ }

  @override
  String? get currentLogFilePath => /* ... */;
}

final provider = FileLoggerProvider(strategy: MyCustomStrategy());

FileObserver (advanced) #

If you build the observer yourself (e.g. for tests): FileObserver(strategy:, formatter:, filter:), then await observer.initialize(). Normally you use FileLoggerProvider, which creates the observer internally.

Resource management #

Call await FlexLogger.instance.dispose() before app exit so file handles are closed and buffers flushed.

License #

MIT License - see LICENSE for details.