Skip to content

Commit f9a7dc7

Browse files
authored
Make setLoggingLevel and disableLogging work without app setup (#1288)
## Problem `setLoggingLevel()` and `disableLogging()` throw in an app that has not set up `package:logging` in a particular way: ``` Unsupported operation: Please set "hierarchicalLoggingEnabled" to true if you want to change the level on a non-root logger. ``` ## Cause Both functions set a level on the SDK's own logger, `Logger('livekit')`. `package:logging` has two modes. In the default one only the root logger has a level, every other logger follows it, and setting a level on another logger is an error, because it would never be consulted. A logger gets a level of its own only once `hierarchicalLoggingEnabled` is on. The SDK never turned that on. So the functions have thrown since they were added in #244, unless the app had turned it on for its own reasons. Every `logging` release the SDK has allowed since then (1.0.0 to 1.3.0) behaves this way. ## Fix Both functions turn `hierarchicalLoggingEnabled` on before they set the level. It is a process-wide switch, and turning it on changes nothing for code that does not use it: - A logger without a level of its own keeps following `Logger.root`. - SDK records still reach `Logger.root.onRecord`. In this mode a record goes to its logger and to every parent. No signature changes. The README gets a short Logging section, it had none. ## Testing New `test/logger_test.dart`, six tests that start from an app that has set up nothing. All six fail without the fix. - neither function throws - with the SDK at FINE and the root at INFO, an SDK record at FINE reaches a root listener, and one at FINEST does not - another logger stays on the root level - `disableLogging()` silences the SDK and nothing else - a level can be set again after logging was disabled Full suite: 580 passed, 1 skipped. Analyze, format, import order and the version check pass. ## Notes - Found while writing an e2e-flutter scenario that needed the SDK at its most verbose level. - One difference in hierarchical mode: `onRecord` on a logger other than the root one delivers that logger's records only. In the default mode it delivers everything, because it is the root stream. An app that listens on `Logger.root.onRecord`, which is what the README now shows, sees no difference. - Not needed for 2.14.0. The functions fail the same way in every published release.
1 parent 5e490e3 commit f9a7dc7

4 files changed

Lines changed: 123 additions & 2 deletions

File tree

‎.changes/logging-level-setters‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
patch type="fixed" "`setLoggingLevel` and `disableLogging` no longer throw `UnsupportedError` in an app that has not turned on `hierarchicalLoggingEnabled` itself. They now turn it on, so the SDK logger can have a level of its own. Loggers without their own level keep following `Logger.root`"

‎README.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -609,6 +609,27 @@ These controls are accessible on the `RemoteTrackPublication` object.
609609

610610
For more info, see [Subscribing to tracks](https://docs.livekit.io/home/client/tracks/subscribe/).
611611

612+
### Logging
613+
614+
The SDK logs through [`package:logging`](https://pub.dev/packages/logging), on a logger named `livekit`. Listen on the root logger to receive its records:
615+
616+
```dart
617+
import 'package:logging/logging.dart';
618+
619+
Logger.root.onRecord.listen((record) {
620+
print('${record.level.name} ${record.loggerName}: ${record.message}');
621+
});
622+
```
623+
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:
625+
626+
```dart
627+
setLoggingLevel(LoggerLevel.kFINE); // more detail from the SDK only
628+
disableLogging(); // nothing from the SDK
629+
```
630+
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.
632+
612633
### Diagnosing connection issues
613634

614635
`ConnectionCheck` runs a set of connection diagnostics against a LiveKit server — the same checks that power [livekit.io/connection-test](https://livekit.io/connection-test). Run it proactively at app start, or reactively when `room.connect()` fails, to determine why a connection cannot be established (firewall, VPN, blocked TURN, etc.).

‎lib/src/logger.dart‎

Lines changed: 14 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -27,15 +27,27 @@ 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.
3032
final logger = Logger('livekit');
3133

32-
/// disable logging
34+
/// Stops the SDK from logging. Other loggers are not affected.
35+
///
36+
/// Turns on `hierarchicalLoggingEnabled`, see [setLoggingLevel].
3337
void disableLogging() {
38+
hierarchicalLoggingEnabled = true;
3439
logger.level = Level.OFF;
3540
}
3641

37-
/// set the logging level
42+
/// Sets how much the SDK logs, apart from the level of `Logger.root`. Other
43+
/// loggers are not affected.
44+
///
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.
3849
void setLoggingLevel(LoggerLevel level) {
50+
hierarchicalLoggingEnabled = true;
3951
switch (level) {
4052
case LoggerLevel.kALL:
4153
logger.level = Level.ALL;

‎test/logger_test.dart‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
// Copyright 2026 LiveKit, Inc.
2+
//
3+
// Licensed under the Apache License, Version 2.0 (the "License");
4+
// you may not use this file except in compliance with the License.
5+
// You may obtain a copy of the License at
6+
//
7+
// http://www.apache.org/licenses/LICENSE-2.0
8+
//
9+
// Unless required by applicable law or agreed to in writing, software
10+
// distributed under the License is distributed on an "AS IS" BASIS,
11+
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
// See the License for the specific language governing permissions and
13+
// limitations under the License.
14+
15+
import 'package:flutter_test/flutter_test.dart';
16+
import 'package:logging/logging.dart';
17+
18+
import 'package:livekit_client/livekit_client.dart';
19+
20+
void main() {
21+
late List<LogRecord> records;
22+
23+
setUp(() {
24+
// What an app has before it touches any logging setting.
25+
hierarchicalLoggingEnabled = false;
26+
Logger.root.level = Level.INFO;
27+
records = [];
28+
final subscription = Logger.root.onRecord.listen(records.add);
29+
addTearDown(() async {
30+
await subscription.cancel();
31+
hierarchicalLoggingEnabled = true;
32+
logger.level = null;
33+
hierarchicalLoggingEnabled = false;
34+
Logger.root.level = Level.INFO;
35+
});
36+
});
37+
38+
List<String> messagesFrom(String loggerName) => [
39+
for (final record in records)
40+
if (record.loggerName == loggerName) record.message,
41+
];
42+
43+
test('setLoggingLevel works in an app that has not set up logging', () {
44+
expect(() => setLoggingLevel(LoggerLevel.kFINE), returnsNormally);
45+
});
46+
47+
test('disableLogging works in an app that has not set up logging', () {
48+
expect(disableLogging, returnsNormally);
49+
});
50+
51+
test('setLoggingLevel lets SDK records below the root level through to the root listener', () {
52+
logger.fine('before');
53+
setLoggingLevel(LoggerLevel.kFINE);
54+
logger.fine('after');
55+
logger.finest('too detailed');
56+
57+
expect(messagesFrom('livekit'), ['after']);
58+
});
59+
60+
test('setLoggingLevel leaves other loggers on the root level', () {
61+
final other = Logger('app');
62+
setLoggingLevel(LoggerLevel.kALL);
63+
other.fine('detail');
64+
other.info('headline');
65+
66+
expect(messagesFrom('app'), ['headline']);
67+
});
68+
69+
test('disableLogging silences the SDK and nothing else', () {
70+
final other = Logger('app');
71+
disableLogging();
72+
logger.severe('from the sdk');
73+
other.info('from the app');
74+
75+
expect(messagesFrom('livekit'), isEmpty);
76+
expect(messagesFrom('app'), ['from the app']);
77+
});
78+
79+
test('a level can be raised again after logging was disabled', () {
80+
disableLogging();
81+
setLoggingLevel(LoggerLevel.kWARNING);
82+
logger.info('quiet');
83+
logger.warning('loud');
84+
85+
expect(messagesFrom('livekit'), ['loud']);
86+
});
87+
}

0 commit comments

Comments
 (0)