diff --git a/README.md b/README.md index 5b96de1..70f1660 100644 --- a/README.md +++ b/README.md @@ -77,6 +77,69 @@ Available logging methods are: + `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. + + +```dart + 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 (√√) +``` + ## Publishing automation For information about our publishing automation and release process, see