Fox Logging #

A package containing some helpful extensions for the standard logging package. It provides a flow to make logging more structured by introducing sinks and formatters.

Sink #

A sink writes a log entry to some place, like the console, file, database,...

final sink = IoLogSink(myFormatter);

The built-in sinks are:

Hand a record to a sink with log: it applies the filter and keeps a failing sink from throwing into the program it logs for. write is the raw counterpart which every sink implements.

await sink.log(record); // filtered
await sink.write(record); // unfiltered

// override onError to find out about failing writes
class MySink with LogSinkMixin {
  @override
  final LogFilter filter = const LogFilter.none();

  @override
  Future<void> write(LogRecord logRecord) async {
    // write the record to wherever this sink goes
  }

  @override
  void onError(Object error, StackTrace stackTrace) {
    // report the failed write somewhere else
  }
}

Call dispose when you are done with a sink. It cancels the subscriptions made by listenTo, and releases whatever else the sink holds (the stream of a StreamLogSink, the sinks of a MultiLogSink,...).

Formatter #

Formatters format a LogRecord to a String in a certain way. This can be a pretty, verbose or simple, concise log. Or a complete custom implementation.

final simpleFormatter = SimpleFormatter();

The built-in formatters are SimpleFormatter, PrettyFormatter, JsonFormatter and LevelDependentFormatter, which picks a formatter based on the level of the record:

final formatter = LevelDependentFormatter(
  defaultFormatter: SimpleFormatter(),
  severe: PrettyFormatter(),
  shout: PrettyFormatter(),
);

Filter #

A filter decides which records reach a sink. Every sink takes one as its last constructor argument and does not filter anything by default.

final errorsOnly = IoLogSink(SimpleFormatter(), const LogFilter.level(Level.SEVERE));

Each sink applies its own filter, also when it is wrapped in a MultiLogSink:

final sink = MultiLogSink([
  IoLogSink(PrettyFormatter()),
  // only errors end up in the json log
  IoLogSink(const JsonFormatter(), const LogFilter.level(Level.SEVERE)),
]);

Implement LogFilter for anything else.

Parser #

Parsers turn a String back into a LogRecord, which is useful to read back logs written with the JsonFormatter.

final records = const JsonLogRecordParser().parseList(await file.readAsString());

Small example #

final logger = Logger('Simple');
final sink = IoLogSink(SimpleFormatter())
  ..listenTo(logger.onRecord);

Images below show the SimpleFormatter and PrettyFormatter when using the PrintSink. SimpleFormatter: PrettyFormatter:

For a more detailed example check out the example.