Logger for Dart

A LogPrinter is responsible for formatting the log event into a list of strings. This is where the visual structure of the log is defined. You can implement a custom printer by extending LogPrinter and overriding the log method.

class MyPrinter extends LogPrinter {
  @override
  List<String> log(LogEvent event) {
    return [event.message];
  }
}

A LogOutput takes the formatted strings from a printer and sends them to a destination. The default is ConsoleOutput.

Available implementations:

• ConsoleOutput: Sends to system console.
• FileOutput / AdvancedFileOutput: Writes to files.
• StreamOutput: Sends to a stream.

You can implement your own by extending LogOutput and overriding the output method.

class ConsoleOutput extends LogOutput {
  @override
  void output(OutputEvent event) {
    for (var line in event.lines) {
      print(line);
    }
  }
}

A LogFilter determines which log events are displayed. The default DevelopmentFilter only shows logs when running in debug mode (with --enable-asserts) and suppresses all logs in release mode. You can implement your own filter by extending LogFilter and overriding shouldLog.

class MyFilter extends LogFilter {
  @override
  bool shouldLog(LogEvent event) {
    return true; // Always show logs
  }
}

To use the logger, create an instance of Logger and call its logging methods. You can pass strings or other objects like List, Map, or Set as the message.

var logger = Logger();

logger.d("Logger is working!");

To ensure logs look correct in a terminal, you can auto-detect lineLength and colors using the dart:io package. This is recommended for CLI applications, though you should avoid it on the web.

import 'dart:io' as io;

var logger = Logger(
  printer: PrettyPrinter(
    lineLength: io.stdout.terminalColumns,
    colors: io.stdout.supportsAnsiEscapes,
  ),
);

The DevelopmentFilter is a specialized LogFilter designed for Flutter or Dart applications where you want to ensure that logs are only processed during development (debug) mode.

It uses an assert block to determine whether a log should be emitted. Because assert statements are ignored in release mode, the shouldLog method will always return false in production, effectively silencing all logs. In development mode, it allows logs to pass through if their level is greater than or equal to the configured Logger.level.

// Example usage when configuring a Logger
final logger = Logger(
  filter: DevelopmentFilter(),
);

Due to potential issues with ANSI escape sequences on macOS and certain Flutter builds, you can use the PrefixPrinter decorator combined with a JetBrains IDE (like Android Studio or IntelliJ) and the 'Grep Console' plugin to achieve colored logs.

var logger = Logger(
    printer: PrefixPrinter(PrettyPrinter(colors: false))
);

When initializing Logger, you can provide custom filter, printer, and output. If you use PrettyPrinter, you can fine-tune the formatting including method call counts, line length, colors, emojis, and timestamp formats.

var logger = Logger(
  filter: null, // Use default LogFilter (only logs in debug mode)
  printer: PrettyPrinter(
      methodCount: 2, // Number of method calls to be displayed
      errorMethodCount: 8, // Number of method calls if stacktrace is provided
      lineLength: 120, // Width of the output
      colors: true, // Colorful log messages
      printEmojis: true, // Print an emoji for each log message
      dateTimeFormat: DateTimeFormat.onlyTimeAndSinceStart,
  ),
  output: null, // Use default LogOutput (send to console)
);

The Logger class provides several methods for different log levels. You can also globally control the minimum log level to show by setting Logger.level.

logger.t("Trace log");
logger.d("Debug log");
logger.i("Info log");
logger.w("Warning log");
logger.e("Error log", error: 'Test Error');
logger.f("What a fatal log", error: error, stackTrace: stackTrace);

// To show only specific log levels (e.g., warning and above):
Logger.level = Level.warning;

The Logger class provides static properties to configure the default behavior for all new logger instances:

• static Level level: Sets the global minimum logging level. Logs below this level are omitted.
• static LogFilter Function() defaultFilter: The factory for the default filter.
• static LogPrinter Function() defaultPrinter: The factory for the default printer.
• static LogOutput Function() defaultOutput: The factory for the default output.

// Set global minimum level to info
Logger.level = Level.info;

By default, PrettyPrinter wraps log messages in ASCII 'boxes' based on their Level. You can control this behavior using excludeBox and noBoxingByDefault.

• noBoxingByDefault: If true, all levels will have boxing disabled by default. You can then selectively enable it for specific levels using excludeBox.
• excludeBox: A map where setting a Level to true prevents that level from being boxed.

Example: Disable boxing for all levels except Level.error:

final printer = PrettyPrinter(
  noBoxingByDefault: true,
  excludeBox: {
    Level.error: false, // Setting to false enables boxing for this level
  },
);

// Example: Prevent boxing of trace and info levels
final printer = PrettyPrinter(
  excludeBox: {
    Level.trace: true,
    Level.info: true,
  },
);