Logging for Dart SDK

This page explains how to enable logging in the PubNub Dart Software Development Kit (SDK).

By default, logging in the Dart SDK is disabled. You can enable it either at the SDK instance level or by providing a zone-scoped logger for specific code paths.

Enable logging at the instance level

Use the logging parameter on the PubNub constructor with LoggingConfiguration to enable and control logging globally for that instance. You can also print to console automatically.

1import 'package:pubnub/pubnub.dart';
2import 'package:pubnub/logging.dart';
3

4void main() async {
5  final pubnub = PubNub(
6    defaultKeyset: Keyset(
7      subscribeKey: 'demo', // Replace with your Subscribe Key from the PubNub Admin Portal
8      publishKey: 'demo',   // Replace with your Publish Key from the PubNub Admin Portal
9      userId: UserId('loggingDemoUser'),
10    ),
11    logging: LoggingConfiguration(
12      logLevel: Level.all,     // Enable all logs
13      logToConsole: true,      // Optional: print formatted logs to console automatically
14      // loggerName: 'myApp',  // Optional: custom logger name
15    ),
16  );
17}

show all 17 lines

Change log level at runtime

1// Change logging verbosity dynamically later in your app
2pubnub.setLogLevel(Level.info);

Enable logging for a specific code path

To enable logging for specific parts of your code only, follow these steps:

1. Import logging utilities and the SDK.

   1  import 'package:pubnub/pubnub.dart';
   2  import 'package:pubnub/logging.dart';
   3  
   4  void main() {
   5    // This is the minimum required code to import logging utilities
   6    print('PubNub logging utilities imported successfully');
   7  }

2. Create a logger instance which implements the ILogger interface.

   In this example we use a logger that ships with the PubNub SDK - StreamLogger.

   1import 'package:pubnub/pubnub.dart';
   2import 'package:pubnub/logging.dart';
   3
   
   4void main() {
   5  // Create a logger with name 'myApp' that logs everything
   6  final logger = StreamLogger.root('myApp', logLevel: Level.all);
   7  
   8  // Initialize PubNub with demo keys
   9  final pubnub = PubNub(
   10    defaultKeyset: Keyset(
   11      subscribeKey: 'demo', // Replace with your Subscribe Key from the PubNub Admin Portal
   12      publishKey: 'demo',   // Replace with your Publish Key from the PubNub Admin Portal
   13      userId: UserId('loggingDemoUser'),
   14    ),
   15  );
   16  
   17  print('Logger initialized with name "myApp" and Level.all');
   18}

   show all 18 lines

   StreamLogger.root constructor requires a name for the logger. Additionally, you can pass in your desired log level and instruct the logger to record stack traces.

   StreamLogger#stream exposes a Stream<LogRecord> that you can subscribe to. You can use this stream to print log lines to the screen, send them to your debugging platform or write them to a file. Take a look at the LogRecord class to see what information is available.

   1import 'package:pubnub/pubnub.dart';
   2import 'package:pubnub/logging.dart';
   3
   
   4void main() {
   5  // Create a logger with name 'myApp' that logs everything
   6  final logger = StreamLogger.root('myApp', logLevel: Level.all);
   7  
   8  // Listen to the log stream and format messages
   9  logger.stream.listen((record) {
   10    print('[${record.time}] ${Level.getName(record.level)}: ${record.message}');
   11  });
   12  
   13  // Initialize PubNub with demo keys
   14  final pubnub = PubNub(
   15    defaultKeyset: Keyset(
   16      subscribeKey: 'demo', // Replace with your Subscribe Key from the PubNub Admin Portal
   17      publishKey: 'demo',   // Replace with your Publish Key from the PubNub Admin Portal
   18      userId: UserId('loggingDemoUser'),
   19    ),
   20  );
   21  
   22  print('Logger initialized with custom log formatting');
   23}

   show all 23 lines

   If all you want to do is to print the messages to the output you can use a LogRecord.defaultPrinter and pass that as a listener to the logger stream.

   1import 'package:pubnub/pubnub.dart';
   2import 'package:pubnub/logging.dart';
   3
   
   4void main() {
   5  // Create a logger with name 'myApp' that logs everything
   6  final logger = StreamLogger.root('myApp', logLevel: Level.all);
   7  
   8  // Use the built-in default printer
   9  logger.stream.listen(LogRecord.defaultPrinter);
   10  
   11  // Initialize PubNub with demo keys
   12  final pubnub = PubNub(
   13    defaultKeyset: Keyset(
   14      subscribeKey: 'demo', // Replace with your Subscribe Key from the PubNub Admin Portal
   15      publishKey: 'demo',   // Replace with your Publish Key from the PubNub Admin Portal
   16      userId: UserId('loggingDemoUser'),
   17    ),
   18  );
   19  
   20  print('Logger initialized with default printer');
   21}

   show all 21 lines

3. Wrap the parts of the code that you want to log in a provideLogger.

   1import 'package:pubnub/pubnub.dart';
   2import 'package:pubnub/logging.dart';
   3
   
   4Future<void> somethingThatWorks() async {
   5  print('This function works without issues');
   6}
   7
   
   8Future<void> troublesomeFunction() async {
   9  print('This is the function we want to debug with logging');
   10  
   11  // Initialize PubNub to see logs
   12  final pubnub = PubNub(
   13    defaultKeyset: Keyset(
   14      subscribeKey: 'demo', // Replace with your Subscribe Key from the PubNub Admin Portal
   15      publishKey: 'demo',   // Replace with your Publish Key from the PubNub Admin Portal
   16      userId: UserId('loggingDemoUser'),
   17    ),
   18  );
   19  
   20  // Perform an operation to generate logs
   21  await pubnub.time();
   22}
   23
   
   24Future<void> somethingElseThatWorks() async {
   25  print('This function also works without issues');
   26}
   27
   
   28void main() async {
   29  // Create a logger with name 'myApp' that logs everything
   30  final logger = StreamLogger.root('myApp', logLevel: Level.all);
   31  logger.stream.listen(LogRecord.defaultPrinter);
   32
   
   33  await somethingThatWorks();
   34
   
   35  // Apply logging only to the troublesome function
   36  await provideLogger(logger, () async {
   37    await troublesomeFunction();
   38  });
   39
   
   40  await somethingElseThatWorks();
   41}

   show all 41 lines

   In case of a Flutter app, you can wrap the entire runApp method.

   1import 'package:flutter/material.dart';
   2import 'package:pubnub/pubnub.dart';
   3import 'package:pubnub/logging.dart';
   4
   
   5// Simple Flutter app for demo purposes
   6class MyApp extends StatelessWidget {
   7  @override
   8  Widget build(BuildContext context) {
   9    return MaterialApp(
   10      home: Scaffold(
   11        appBar: AppBar(title: Text('PubNub Logging Example')),
   12        body: Center(child: Text('Check console for logs')),
   13      ),
   14    );
   15  }
   16}
   17
   
   18void main() {
   19  // Create a logger with name 'myApp' that logs everything
   20  final logger = StreamLogger.root('myApp', logLevel: Level.all);
   21  logger.stream.listen(LogRecord.defaultPrinter);
   22  
   23  // Wrap the entire app with logging
   24  provideLogger(logger, () {
   25    runApp(MyApp());
   26    
   27    // Create a PubNub instance to generate some logs
   28    final pubnub = PubNub(
   29      defaultKeyset: Keyset(
   30        subscribeKey: 'demo', // Replace with your Subscribe Key from the PubNub Admin Portal
   31        publishKey: 'demo',   // Replace with your Publish Key from the PubNub Admin Portal
   32        userId: UserId('loggingDemoUser'),
   33      ),
   34    );
   35    
   36    // This will generate logs visible in the console
   37    pubnub.time();
   38  });
   39}

   show all 39 lines

Where logs are emitted

Typical sources include:

• API operations (for example publish)
• Networking requests and responses
• Instance initialization details

Log levels

StreamLogger assigns a weight to each log record. A message is logged if its level is less than or equal to the active logLevel. For example, if logLevel is set to Level.warning (80), messages with level 80 or less will be recorded.

The threshold levels are defined in the Level class as follows:

• Level.off is 0 and turns logging off
• Level.shout is 10
• Level.fatal is 20
• Level.severe is 40
• Level.warning is 80
• Level.info is 160
• Level.verbose is 320
• Level.fine is 500
• Level.silly is 640
• Level.all is 10000 and turns logging on for all levels