Logging

On this page

Set or Change the Log Level

Customize the Logger
Turn Off Logging
Other Loggers
C++ SDK
Java SDK

Realm is now Atlas Device SDK – Learn More

You can set or change your app's log level when developing or debugging your app. You might want to change the log level to log different amounts of data depending on your development needs. You can specify different log levels or custom loggers.

Set or Change the Log Level

You can set the level of detail reported by Atlas Device SDK.

For the C++ SDK, pass a realm::logger::level to the set_default_level_threshold() member function:

For the .NET SDK, use LogLevel to control which messages are logged by the client logger:

In the Flutter SDK, you can set the level of detail in different parts of your app. To configure the log level, pass a valid LogLevel value to setLogLevel.

To set the level of detail reported by the Node.js SDK pass a valid level to Realm.setLogLevel(). Refer to LogLevel for all valid values.

Note

Performance and console.log()

You should avoid using console.log() in production because it will negatively affect your app's performance. It can also be hard to account for all of the method's quirks in Node.js.

For details about console.log() behavior, check out the Node.js docs.

The Kotlin SDK uses the global RealmLog singleton. You can set the RealmLog.level property to an entry in the LogLevel enum to specify the level of data you want to receive. If the log level priority is equal to or higher than the priority defined in RealmLog.level, the database logs the event. You can change the log level at any point during the app's lifecycle from this global singleton.

By default, all logs go to a default system logger that varies by system:

Android logs to Logcat.
JVM logs to stdout.
MacOS logs to NSLog.
iOS logs to NSLog.

By default, all logs go to a default system logger that varies by system:

Android logs to Logcat.
JVM logs to stdout.
MacOS logs to NSLog.
iOS logs to NSLog.

For the Swift SDK, set the log level for the default logger with Logger.shared.level. The RLMLogLevel enum represents the different levels of logging you can configure.

Tip

Set the Logger Before Initializing an App Client

When you initialize an App client, the Swift SDK caches the configuration for the App. Changing to the App configuration after initialization does not have any effect. This includes setting a logger. Initializing an App reads the current shared logger and stores that.

However, changing the log level for an existing logger does work at any time.

To set the level of detail reported by the Node.js SDK pass a valid level to Realm.setLogLevel(). Refer to LogLevel for all valid values.

Note

Performance and console.log()

You should avoid using console.log() in production because it will negatively affect your app's performance. It can also be hard to account for all of the method's quirks in Node.js.

For details about console.log() behavior, check out the Node.js docs.

auto logLevel = realm::logger::level::info;
realm::set_default_level_threshold(logLevel);

Logger.LogLevel = LogLevel.Debug;

// If no category is set, default is LogCategory.realm
Realm.logger.setLogLevel(LogLevel.all, category: LogCategory.realm);

Realm.setLogLevel("all");

// Set a log level using the global RealmLog singleton
RealmLog.level = LogLevel.TRACE
// Access your app and use realm
val app: App = App.create(YOUR_APP_ID) // Replace this with your App ID
val user = app.login(Credentials.emailPassword(email, password))
val config = SyncConfiguration.Builder(user, setOf(Toad::class))
    .initialSubscriptions { realm ->
        add(realm.query<Toad>("name == $0", "name value"), "sync subscription")
    }
    .build()
val realm = Realm.open(config)
// You can change the log level at any point in your app's lifecycle as needed
RealmLog.level = LogLevel.INFO

Logger.shared.level = .trace

Realm.setLogLevel("all");

You can change the log level to increase or decrease verbosity at different points in your code.

// The documentation does not currently have this code example in C++.
// Please refer to the other languages or related pages for example code.

// The documentation does not currently have this code example in C#.
// Please refer to the other languages or related pages for example code.

Realm.logger.setLogLevel(LogLevel.off);
await executeAppCode();
Realm.logger.setLogLevel(LogLevel.debug, category: LogCategory.realm);
await executeComplexCodeToDebug();

// Set a default log level that's not too verbose
Realm.setLogLevel("detail");
const realm = await Realm.open({
  schema: [Turtle],
});
// Later, change the log level to debug an issue when running specific code
Realm.setLogLevel("trace");
realm.write(() => realm.create(Turtle, newTestObject()));

// The documentation does not currently have this code example in Kotlin.
// Please refer to the other languages or related pages for example code.

// Set a log level that isn't too verbose
Logger.shared.level = .warn
// Later, when trying to debug something, change the log level for more verbosity
Logger.shared.level = .trace

// Set a default log level that's not too verbose
Realm.setLogLevel("detail");
const realm = await Realm.open({
  schema: [Turtle],
});
// Later, change the log level to debug an issue when running specific code
Realm.setLogLevel("trace");
realm.write(() => realm.create(Turtle, newTestObject()));

Customize the Logger

You can create a custom logger. You might want to customize logging to add specific tags or set specific log levels during development, testing, or debugging.

To set a custom logger function with the C++ SDK, create a realm::logger and override the virtual do_log() member function.

struct MyCustomLogger : realm::logger {
  // This could be called from any thread, so may not output visibly to the
  // console. Handle output in a queue or other cross-thread context if needed.
  void do_log(realm::logger::level level, const std::string &msg) override {
    std::cout << "Realm log entry: " << msg << std::endl;
  }
};

After setting a custom logger, you need to initialize it:

To set a custom logger with the .NET SDK, set Logger.Default to a custom Logger function.

The Flutter SDK logger conforms to the Dart Logger class.

To get started, set a log level:

// If no category is set, default is LogCategory.realm
Realm.logger.setLogLevel(LogLevel.all, category: LogCategory.realm);

Define custom logging behavior by listening to Realm.logger.onRecord:

To get started, set a log level:

Realm.setLogLevel("all");

To set a custom logger with the Node.js SDK, call setLogger(). This method recieves level and message arguments from the database logger. You can use these arguments to define your own logging behavior.

This sets the logging behavior for all database logging in your application. If you do not provide a log level, the default value is "info".

The Kotlin SDK implements the RealmLogger interface for custom loggers.

class MyLogger() : RealmLogger {
    override val tag: String = "CUSTOM_LOG_ENTRY"
    override val level: LogLevel = LogLevel.DEBUG
    override fun log(
        level: LogLevel,
        throwable: Throwable?,
        message: String?,
        vararg args: Any?
    ) {
        println(message) // Custom handling
    }
}

In the Kotlin SDK, use RealmLog.add() to set your custom logger as a logger for your app.

You can also remove a specific logger or remove all loggers, including the system logger.

The Kotlin SDK implements the RealmLogger interface for custom loggers.

class MyLogger() : RealmLogger {
    override val tag: String = "CUSTOM_LOG_ENTRY"
    override val level: LogLevel = LogLevel.DEBUG
    override fun log(
        level: LogLevel,
        throwable: Throwable?,
        message: String?,
        vararg args: Any?
    ) {
        println(message) // Custom handling
    }
}

In the Kotlin SDK, use RealmLog.add() to set your custom logger as a logger for your app.

You can also remove a specific logger or remove all loggers, including the system logger.

In the Swift SDK, initialize an instance of a Logger and define the function to use for logging.

// Create an instance of `Logger` and define the log function to invoke.
let logger = Logger(level: .detail) { level, message in
    // You may pass log information to a logging service, or
    // you could simply print the logs for debugging. Define
    // the log function that makes sense for your application.
    print("REALM DEBUG: \(Date.now) \(level) \(message) \n")
}

In the Swift SDK, use Logger.shared. After you set the default logger, you can change the log level during the app lifecycle as needed.

To get started, set a log level:

Realm.setLogLevel("all");

This sets the logging behavior for all database logging in your application. If you do not provide a log level, the default value is "info".

auto config = realm::db_config();
auto thisRealm = realm::db(config);
auto myLogger = std::make_shared<MyCustomLogger>();
realm::set_default_logger(myLogger);

using Realms.Logging;
Logger.LogLevel = LogLevel.All;
// customize the logging function:
Logger.Default = Logger.Function(message =>
{
    // Do something with the message
});

Realm.logger.onRecord.listen((record) {
  // Do something with the log record
  print(record.message);
});

let logs = [];
Realm.setLogger((level, message) => {
  logs.push({ level, message });
});

// Set an instance of a custom logger
val myCustomLogger = MyLogger()
RealmLog.add(myCustomLogger)
// You can remove a specific logger
RealmLog.remove(myCustomLogger)
// Or remove all loggers, including the default system logger
RealmLog.removeAll()

let logger = Logger(level: .info) { level, message in
    // You may pass log information to a logging service, or
    // you could simply print the logs for debugging. Define
    // the log function that makes sense for your application.
    print("REALM DEBUG: \(Date.now) \(level) \(message) \n")
}
// Set a logger as the default
Logger.shared = logger
// After setting a default logger, you can change
// the log level at any point during the app lifecycle
Logger.shared.level = .debug

type Log = {
  message: string;
  level: string;
};
let logs: Log[] = [];
Realm.setLogger((level, message) => {
  logs.push({ level, message });
});

Tip

To diagnose and troubleshoot errors while developing your application, set the log level to debug or trace. For production deployments, decrease the log level for improved performance.

Turn Off Logging

You can turn off logging by setting the log level:

// The documentation does not currently have this code example in C++.
// Please refer to the other languages or related pages for example code.

// The documentation does not currently have this code example in C#.
// Please refer to the other languages or related pages for example code.

Realm.logger.setLogLevel(LogLevel.off);

Realm.setLogLevel("off");

// The documentation does not currently have this code example in C#.
// Please refer to the other languages or related pages for example code.

Logger.shared.level = .off

Realm.setLogLevel("off");

Other Loggers

The C++ and Java SDKs have additional loggers that behave differently than the other examples on this page.

C++ SDK

The C++ SDK uses a sync logger that behaves differently than the rest of the examples on this page. You can set or change your sync client's log level to develop or debug your application. You might want to change the log level to log different amounts of data depending on the app's environment.

You can set the level of detail reported by the sync client logger to specify the level of output you want from the sync client. Get an instance of an App's sync manager, and pass a realm::logger::level to the set_log_level() member function:

auto logLevel = realm::logger::level::info;
app.get_sync_manager().set_log_level(logLevel);

Java SDK

The SDK logs events to the Android system log automatically. You can view these events using Logcat.

We recommend using the Kotlin SDK to get the latest logging updates, like changing the log level at different points in your code.

The Java SDK uses the log levels defined by Log4J. To configure the log level for database logs in your application, pass a LogLevel to RealmLog.setLevel():

RealmLog.setLevel(LogLevel.ALL);

Back

Test and Debug

Testing

Logging.leafygreen-ui-m0pgrr{-webkit-align-self:center;-ms-flex-item-align:center;align-self:center;padding:0 10px;visibility:hidden;}.leafygreen-ui-a30zj9{color:#889397;vertical-align:middle;margin-top:-2px;}.css-1l4s55v{margin-top:-175px;position:absolute;padding-bottom:2px;}

Set or Change the Log Level

Note

Performance and console.log()

Tip

Set the Logger Before Initializing an App Client

Note

Performance and console.log()

Customize the Logger

Tip

Turn Off Logging

Other Loggers

C++ SDK

Java SDK

Logging