Pub Bunker

Initializing

By default, the logging package does not do anything useful with the log messages. You must configure the logging level and add a handler for the log messages.

Here is a simple logging configuration that logs all messages via print.

Logger.root.level = Level.ALL; // defaults to Level.INFO
                Logger.root.onRecord.listen((record) {
                  print('${record.level.name}: ${record.time}: ${record.message}');
                });

First, set the root Level. All messages at or above the current level are sent to the onRecord stream. Available levels are:

Level.OFF
Level.SHOUT
Level.SEVERE
Level.WARNING
Level.INFO
Level.CONFIG
Level.FINE
Level.FINER
Level.FINEST

Then, listen on the onRecord stream for LogRecord events. The LogRecord class has various properties for the message, error, logger name, and more.

To listen for changed level notifications use:

Logger.root.onLevelChanged.listen((level) {
                  print('The new log level is $level');
                });

Logging messages

Create a Logger with a unique name to easily identify the source of the log messages.

final log = Logger('MyClassName');

Here is an example of logging a debug message and an error:

var future = doSomethingAsync().then((result) {
                  log.fine('Got the result: $result');
                  processResult(result);
                }).catchError((e, stackTrace) => log.severe('Oh noes!', e, stackTrace));

When logging more complex messages, you can pass a closure instead that will be evaluated only if the message is actually logged:

log.fine(() => [1, 2, 3, 4, 5].map((e) => e * 4).join("-"));

Available logging methods are:

log.shout(logged_content);
log.severe(logged_content);
log.warning(logged_content);
log.info(logged_content);
log.config(logged_content);
log.fine(logged_content);
log.finer(logged_content);
log.finest(logged_content);

Configuration

Loggers can be individually configured and listened to. When an individual logger has no specific configuration, it uses the configuration and any listeners found at Logger.root.

To begin, set the global boolean hierarchicalLoggingEnabled to true.

Then, create unique loggers and configure their level attributes and assign any listeners to their onRecord streams.

  hierarchicalLoggingEnabled = true;
                  Logger.root.level = Level.WARNING;
                  Logger.root.onRecord.listen((record) {
                    print('[ROOT][WARNING+] ${record.message}');
                  });
                
                  final log1 = Logger('FINE+');
                  log1.level = Level.FINE;
                  log1.onRecord.listen((record) {
                    print('[LOG1][FINE+] ${record.message}');
                  });
                
                  // log2 inherits LEVEL value of WARNING from `Logger.root`
                  final log2 = Logger('WARNING+');
                  log2.onRecord.listen((record) {
                    print('[LOG2][WARNING+] ${record.message}');
                  });
                
                
                  // Will NOT print because FINER is too low level for `Logger.root`.
                  log1.finer('LOG_01 FINER (X)');
                
                  // Will print twice ([LOG1] & [ROOT])
                  log1.fine('LOG_01 FINE (√√)');
                
                  // Will print ONCE because `log1` only uses root listener.
                  log1.warning('LOG_01 WARNING (√)');
                
                  // Will never print because FINE is too low level.
                  log2.fine('LOG_02 FINE (X)');
                
                  // Will print twice ([LOG2] & [ROOT]) because warning is sufficient for all
                  // loggers' levels.
                  log2.warning('LOG_02 WARNING (√√)');
                
                  // Will never print because `info` is filtered by `Logger.root.level` of
                  // `Level.WARNING`.
                  log2.info('INFO (X)');

Results in:

[LOG1][FINE+] LOG_01 FINE (√√)
                [ROOT][WARNING+] LOG_01 FINE (√√)
                [LOG1][FINE+] LOG_01 WARNING (√)
                [ROOT][WARNING+] LOG_01 WARNING (√)
                [LOG2][WARNING+] LOG_02 WARNING (√√)
                [ROOT][WARNING+] LOG_02 WARNING (√√)

1.3.0

Override empty stack traces for trace level events.
Require Dart 3.4
Move to dart-lang/core monorepo.

1.2.0

Add notification when the log level is changed. Logger onLevelChanged broadcasts a stream of level values.
Require Dart 2.19.

1.1.1

Add a check that throws if a logger name ends with '.'.
Require Dart 2.18

1.1.0

Add Logger.attachedLoggers which exposes all loggers created with the default constructor.
Enable the avoid_dynamic_calls lint.

1.0.2

Update description.
Add example.

1.0.1

List log levels in README.

1.0.0

Stable null safety release.

1.0.0-nullsafety.0

Migrate to null safety.
Removed the deprecated LoggerHandler typedef.

0.11.4

Add top level defaultLevel.
Require Dart >=2.0.0.
Make detached loggers work regardless of hierarchicalLoggingEnabled.

0.11.3+2

Set max SDK version to <3.0.0, and adjust other dependencies.

0.11.3+1

Fixed several documentation comments.

0.11.3

Added optional LogRecord.object field.
Logger.log sets LogRecord.object if the message is not a string or a function that returns a string. So that a handler can access the original object instead of just its toString().

0.11.2

Added Logger.detached - a convenience factory to obtain a logger that is not attached to this library's logger hierarchy.

0.11.1+1

Include default error with the auto-generated stack traces.

0.11.1

Add support for automatically logging the stack trace on error messages. Note this can be expensive, so it is off by default.

0.11.0

Revert change in 0.10.0. stackTrace must be an instance of StackTrace. Use the Trace class from the stack_trace package to convert strings.

0.10.0

Change type of stackTrace from StackTrace to Object.

0.9.3

Added optional LogRecord.zone field.
Record current zone (or user specified zone) when creating new LogRecords.

logging

Readme