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.