Skip to content

Commit a40ca98

Browse files
authored
Say what turning on hierarchical logging changes (#1293)
Follow-up to #1288. No behavior change, docs and one test. ## What was wrong in the docs #1288 made `setLoggingLevel` and `disableLogging` work by turning on `hierarchicalLoggingEnabled`. The doc comment said that with the switch on "nothing else changes". That is not quite true: - The switch applies to the whole isolate, so it also changes how an app's own loggers deliver records. `onRecord` on a logger other than the root one, listened to after the switch is on, delivers only the records of that logger and its children. Before, it delivered everything. - The README showed one snippet with `setLoggingLevel` and `disableLogging` back to back, which reads as if both are needed. ## What this changes - `lib/src/logger.dart`: the doc comments list what the switch changes. A logger without a level follows its parent. Records still reach `Logger.root.onRecord`. A non-root `onRecord` narrows to that logger and its children. - `README.md`: the Logging section has one snippet per call and says to listen on `Logger.root.onRecord` to keep receiving everything. - `test/logger_test.dart`: one more test, the SDK keeps its level when the root level changes after `setLoggingLevel`. ## Checked against `package:logging` 1.3.0 (`Logger.level`, `Logger.log`, `Logger._getStream`), plus a throwaway probe with loggers `a`, `a.b` and `c`. A listener on `a` added after the switch received `a` and `a.b`. One added before the switch kept receiving all three. The root listener received all three. No change file. The entry for #1288 already covers this and is in the 2.14.0 changelog.
1 parent 55ef223 commit a40ca98

3 files changed

Lines changed: 33 additions & 12 deletions

File tree

‎README.md‎

Lines changed: 10 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -621,14 +621,21 @@ Logger.root.onRecord.listen((record) {
621621
});
622622
```
623623

624-
By default the SDK follows the level of `Logger.root`. To give the SDK its own level, without changing what the rest of your app logs:
624+
By default the SDK follows the level of `Logger.root`. To give the SDK a level of its own, without changing what the rest of your app logs:
625625

626626
```dart
627627
setLoggingLevel(LoggerLevel.kFINE); // more detail from the SDK only
628-
disableLogging(); // nothing from the SDK
629628
```
630629

631-
Both calls turn on `hierarchicalLoggingEnabled`, the switch `package:logging` needs before any logger other than the root one can have a level of its own.
630+
Or to silence it:
631+
632+
```dart
633+
disableLogging();
634+
```
635+
636+
After either call the SDK keeps its own level and no longer follows `Logger.root`.
637+
638+
Both calls turn on `hierarchicalLoggingEnabled`, the switch `package:logging` needs before any logger other than the root one can have a level of its own. With it on, `onRecord` of a logger other than the root one delivers only the records of that logger and its children, so listen on `Logger.root.onRecord` as above to keep receiving everything.
632639

633640
### Diagnosing connection issues
634641

‎lib/src/logger.dart‎

Lines changed: 15 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -27,25 +27,31 @@ enum LoggerLevel {
2727
kOFF,
2828
}
2929

30-
/// The logger every part of the SDK writes to. Its records also reach
31-
/// `Logger.root.onRecord`, which is where an app usually listens.
30+
/// The SDK's logger. Its records also reach `Logger.root.onRecord`, which is
31+
/// where an app usually listens.
3232
final logger = Logger('livekit');
3333

34-
/// Stops the SDK from logging. Other loggers are not affected.
34+
/// Silences the SDK's logger. Other loggers are not affected.
3535
///
3636
/// Turns on `hierarchicalLoggingEnabled`, see [setLoggingLevel].
3737
void disableLogging() {
3838
hierarchicalLoggingEnabled = true;
3939
logger.level = Level.OFF;
4040
}
4141

42-
/// Sets how much the SDK logs, apart from the level of `Logger.root`. Other
43-
/// loggers are not affected.
42+
/// Gives the SDK's logger a level of its own. From then on it no longer
43+
/// follows the level of `Logger.root`. Other loggers are not affected.
4444
///
45-
/// Turns on `hierarchicalLoggingEnabled` of `package:logging`, a process-wide
46-
/// switch. Without it only the root logger has a level, and giving one to any
47-
/// other logger is an error. Loggers that have no level of their own keep
48-
/// following the root logger, so nothing else changes.
45+
/// Turns on `hierarchicalLoggingEnabled` of `package:logging`, which applies
46+
/// to the whole isolate. Without it only the root logger has a level, and
47+
/// giving one to any other logger is an error. With it on:
48+
///
49+
/// - a logger that has no level of its own follows its parent, which for a
50+
/// logger without a dot in its name is still the root logger
51+
/// - records still reach `Logger.root.onRecord`
52+
/// - `onRecord` of a logger other than the root one, listened to from then
53+
/// on, delivers the records of that logger and its children only, where it
54+
/// used to deliver all
4955
void setLoggingLevel(LoggerLevel level) {
5056
hierarchicalLoggingEnabled = true;
5157
switch (level) {

‎test/logger_test.dart‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -66,6 +66,14 @@ void main() {
6666
expect(messagesFrom('app'), ['headline']);
6767
});
6868

69+
test('after setLoggingLevel the SDK keeps its level when the root level changes', () {
70+
setLoggingLevel(LoggerLevel.kFINE);
71+
Logger.root.level = Level.SEVERE;
72+
logger.fine('still logged');
73+
74+
expect(messagesFrom('livekit'), ['still logged']);
75+
});
76+
6977
test('disableLogging silences the SDK and nothing else', () {
7078
final other = Logger('app');
7179
disableLogging();

0 commit comments

Comments
 (0)