diff --git a/examples/dart/pubspec.lock b/examples/dart/pubspec.lock index e142283420..b21f00065b 100644 --- a/examples/dart/pubspec.lock +++ b/examples/dart/pubspec.lock @@ -5,10 +5,15 @@ packages: dependency: transitive description: name: _fe_analyzer_shared - sha256: "0b2f2bd91ba804e53a61d757b986f89f1f9eaed5b11e4b2f5a2468d86d6c9fc7" + sha256: "5aaf60d96c4cd00fe7f21594b5ad6a1b699c80a27420f8a837f4d68473ef09e3" url: "https://pub.dev" source: hosted - version: "67.0.0" + version: "68.0.0" + _macros: + dependency: transitive + description: dart + source: sdk + version: "0.1.0" adaptive_number: dependency: transitive description: @@ -21,18 +26,18 @@ packages: dependency: transitive description: name: analyzer - sha256: "37577842a27e4338429a1cbc32679d508836510b056f1eedf0c8d20e39c1383d" + sha256: "21f1d3720fd1c70316399d5e2bccaebb415c434592d778cce8acb967b8578808" url: "https://pub.dev" source: hosted - version: "6.4.1" + version: "6.5.0" args: dependency: transitive description: name: args - sha256: eef6c46b622e0494a36c5a12d10d77fb4e855501a91c1b9ef9339326e58f0596 + sha256: "7cf60b9f0cc88203c5a190b4cd62a99feea42759a7fa695010eb5de1c0b2252a" url: "https://pub.dev" source: hosted - version: "2.4.2" + version: "2.5.0" async: dependency: transitive description: @@ -77,10 +82,10 @@ packages: dependency: transitive description: name: build_daemon - sha256: "0343061a33da9c5810b2d6cee51945127d8f4c060b7fbdd9d54917f0a3feaaa1" + sha256: "79b2aef6ac2ed00046867ed354c88778c9c0f029df8a20fe10b5436826721ef9" url: "https://pub.dev" source: hosted - version: "4.0.1" + version: "4.0.2" build_resolvers: dependency: transitive description: @@ -93,10 +98,10 @@ packages: dependency: "direct dev" description: name: build_runner - sha256: "581bacf68f89ec8792f5e5a0b2c4decd1c948e97ce659dc783688c8a88fbec21" + sha256: "1414d6d733a85d8ad2f1dfcb3ea7945759e35a123cb99ccfac75d0758f75edfa" url: "https://pub.dev" source: hosted - version: "2.4.8" + version: "2.4.10" build_runner_core: dependency: transitive description: @@ -117,10 +122,10 @@ packages: dependency: transitive description: name: built_value - sha256: a3ec2e0f967bc47f69f95009bb93db936288d61d5343b9436e378b28a2f830c6 + sha256: c7913a9737ee4007efedaffc968c049fd0f3d0e49109e778edc10de9426005cb url: "https://pub.dev" source: hosted - version: "8.9.0" + version: "8.9.2" cancellation_token: dependency: transitive description: @@ -173,10 +178,10 @@ packages: dependency: transitive description: name: coverage - sha256: "8acabb8306b57a409bf4c83522065672ee13179297a6bb0cb9ead73948df7c76" + sha256: "3945034e86ea203af7a056d98e98e42a5518fff200d6e8e6647e1886b07e936e" url: "https://pub.dev" source: hosted - version: "1.7.2" + version: "1.8.0" crypto: dependency: transitive description: @@ -189,18 +194,18 @@ packages: dependency: "direct main" description: name: dart_jsonwebtoken - sha256: "063c20d3cee2b626d8a789ba9df0ad21f35012c4e9bd846ce50e921d77123df7" + sha256: "346e9a21e4bf6e6a431e19ece00ebb2e3668e1e339cabdf6f46d18d88692a848" url: "https://pub.dev" source: hosted - version: "2.12.2" + version: "2.14.0" dart_style: dependency: transitive description: name: dart_style - sha256: "40ae61a5d43feea6d24bd22c0537a6629db858963b99b4bc1c3db80676f32368" + sha256: "99e066ce75c89d6b29903d788a7bb9369cf754f7b24bf70bf4b6d6d6b26853b9" url: "https://pub.dev" source: hosted - version: "2.3.4" + version: "2.3.6" ed25519_edwards: dependency: transitive description: @@ -237,10 +242,10 @@ packages: dependency: transitive description: name: ffi - sha256: "7bf0adc28a23d395f19f3f1eb21dd7cfd1dd9f8e1c50051c069122e6853bc878" + sha256: "493f37e7df1804778ff3a53bd691d8692ddf69702cf4c1c1096a2e41b4779e21" url: "https://pub.dev" source: hosted - version: "2.1.0" + version: "2.1.2" file: dependency: transitive description: @@ -261,10 +266,10 @@ packages: dependency: transitive description: name: frontend_server_client - sha256: "408e3ca148b31c20282ad6f37ebfa6f4bdc8fede5b74bc2f08d9d92b55db3612" + sha256: f64a0333a82f30b0cca061bc3d143813a486dc086b574bfb233b7c1372427694 url: "https://pub.dev" source: hosted - version: "3.2.0" + version: "4.0.0" glob: dependency: transitive description: @@ -285,10 +290,10 @@ packages: dependency: transitive description: name: http - sha256: a2bbf9d017fcced29139daa8ed2bba4ece450ab222871df93ca9eec6f80c34ba + sha256: "761a297c042deedc1ffbb156d6e2af13886bb305c2a343a4d972504cd67dd938" url: "https://pub.dev" source: hosted - version: "1.2.0" + version: "1.2.1" http_multi_server: dependency: transitive description: @@ -317,18 +322,18 @@ packages: dependency: transitive description: name: js - sha256: "4186c61b32f99e60f011f7160e32c89a758ae9b1d0c6d28e2c02ef0382300e2b" + sha256: c1b2e9b5ea78c45e1a0788d29606ba27dc5f71f019f32ca5140f61ef071838cf url: "https://pub.dev" source: hosted - version: "0.7.0" + version: "0.7.1" json_annotation: dependency: transitive description: name: json_annotation - sha256: b10a7b2ff83d83c777edba3c6a0f97045ddadd56c944e1a23a3fdf43a1bf4467 + sha256: "1ce844379ca14835a50d2f019a3099f419082cfdd231cd86a142af94dd5c6bb1" url: "https://pub.dev" source: hosted - version: "4.8.1" + version: "4.9.0" lints: dependency: "direct dev" description: @@ -345,6 +350,14 @@ packages: url: "https://pub.dev" source: hosted version: "1.2.0" + macros: + dependency: transitive + description: + name: macros + sha256: "12e8a9842b5a7390de7a781ec63d793527582398d16ea26c60fed58833c9ae79" + url: "https://pub.dev" + source: hosted + version: "0.1.0-main.0" matcher: dependency: transitive description: @@ -357,10 +370,10 @@ packages: dependency: transitive description: name: meta - sha256: d584fa6707a52763a52446f02cc621b077888fb63b93bbcb1143a7be5a0c0c04 + sha256: bdb68674043280c3428e9ec998512fb681678676b3c54e773629ffe74419f8c7 url: "https://pub.dev" source: hosted - version: "1.11.0" + version: "1.15.0" mime: dependency: transitive description: @@ -405,10 +418,10 @@ packages: dependency: transitive description: name: pointycastle - sha256: "43ac87de6e10afabc85c445745a7b799e04de84cebaa4fd7bf55a5e1e9604d29" + sha256: "4be0097fcf3fd3e8449e53730c631200ebc7b88016acecab2b0da2f0149222fe" url: "https://pub.dev" source: hosted - version: "3.7.4" + version: "3.9.1" pool: dependency: transitive description: @@ -429,34 +442,34 @@ packages: dependency: transitive description: name: pubspec_parse - sha256: c63b2876e58e194e4b0828fcb080ad0e06d051cb607a6be51a9e084f47cb9367 + sha256: c799b721d79eb6ee6fa56f00c04b472dcd44a30d258fac2174a6ec57302678f8 url: "https://pub.dev" source: hosted - version: "1.2.3" + version: "1.3.0" realm_common: dependency: transitive description: name: realm_common - sha256: c04b64fcbcd0afd78c06939efdedb484417697242039d5bb0b07fa150c9c021d + sha256: "1f36a224f35fd089691b631c0c9c92af274e00d524258203a937706d7d5e9d0c" url: "https://pub.dev" source: hosted - version: "2.2.0" + version: "2.3.0" realm_dart: dependency: "direct main" description: name: realm_dart - sha256: b523d392ec614ccb358e64451aca4772d56db23f93e8f58dd1d1780dadc92706 + sha256: ce2bd5dfb5eee142998fc7f395df34e349e1c179b78582d6d84bb4003c556c81 url: "https://pub.dev" source: hosted - version: "2.2.0" + version: "2.3.0" realm_generator: dependency: transitive description: name: realm_generator - sha256: a5c3c403add9d886c098509b49517f44f1d8b667ac0178f80f58fea5ce069fb8 + sha256: "183257f345ac5b01b424261dd6e3c400d414bec725d33d390b5b6942274f5a80" url: "https://pub.dev" source: hosted - version: "2.2.0" + version: "2.3.0" sane_uuid: dependency: transitive description: @@ -493,10 +506,10 @@ packages: dependency: transitive description: name: shelf_web_socket - sha256: "9ca081be41c60190ebcb4766b2486a7d50261db7bd0f5d9615f2d653637a84c1" + sha256: "073c147238594ecd0d193f3456a5fe91c4b0abbcc68bf5cd95b36c4e194ac611" url: "https://pub.dev" source: hosted - version: "1.0.4" + version: "2.0.0" source_gen: dependency: transitive description: @@ -565,10 +578,10 @@ packages: dependency: transitive description: name: tar - sha256: "1680219f82dfa81c8d0e76e849b7b34ea969c721f55a8ebd294a9a95e740dd42" + sha256: "22f67e2d77b51050436620b2a5de521c58ca6f0b75af1d9ab3c8cae2eae58fcd" url: "https://pub.dev" source: hosted - version: "1.0.3" + version: "1.0.5" term_glyph: dependency: transitive description: @@ -581,26 +594,26 @@ packages: dependency: "direct main" description: name: test - sha256: "7ee446762c2c50b3bd4ea96fe13ffac69919352bd3b4b17bac3f3465edc58073" + sha256: "47e9b601e20f24c27d08002eb635e92ddc2195010a8b3a621f4ed44ef70f6864" url: "https://pub.dev" source: hosted - version: "1.25.2" + version: "1.25.6" test_api: dependency: transitive description: name: test_api - sha256: "9955ae474176f7ac8ee4e989dadfb411a58c30415bcfb648fa04b2b8a03afa7f" + sha256: "5b8a98dafc4d5c4c9c72d8b31ab2b23fc13422348d2997120294d3bac86b4ddb" url: "https://pub.dev" source: hosted - version: "0.7.0" + version: "0.7.2" test_core: dependency: transitive description: name: test_core - sha256: "2bc4b4ecddd75309300d8096f781c0e3280ca1ef85beda558d33fcbedc2eead4" + sha256: "0c583123c86e58ab5036c92db5c7116ffddd655f1f5be762967d09f0fc66bf2d" url: "https://pub.dev" source: hosted - version: "0.6.0" + version: "0.6.3" timing: dependency: transitive description: @@ -613,10 +626,10 @@ packages: dependency: transitive description: name: type_plus - sha256: "2e33cfac2e129297d5874567bdf7587502ec359881e9318551e014d91b02f84a" + sha256: d5d1019471f0d38b91603adb9b5fd4ce7ab903c879d2fbf1a3f80a630a03fcc9 url: "https://pub.dev" source: hosted - version: "2.1.0" + version: "2.1.1" typed_data: dependency: transitive description: @@ -629,10 +642,10 @@ packages: dependency: transitive description: name: vm_service - sha256: a2662fb1f114f4296cf3f5a50786a2d888268d7776cf681aa17d660ffa23b246 + sha256: "360c4271613beb44db559547d02f8b0dc044741d0eeb9aa6ccdb47e8ec54c63a" url: "https://pub.dev" source: hosted - version: "14.0.0" + version: "14.2.3" watcher: dependency: transitive description: @@ -645,18 +658,26 @@ packages: dependency: transitive description: name: web - sha256: "4188706108906f002b3a293509234588823c8c979dc83304e229ff400c996b05" + sha256: "97da13628db363c635202ad97068d47c5b8aa555808e7a9411963c533b449b27" url: "https://pub.dev" source: hosted - version: "0.4.2" + version: "0.5.1" + web_socket: + dependency: transitive + description: + name: web_socket + sha256: "24301d8c293ce6fe327ffe6f59d8fd8834735f0ec36e4fd383ec7ff8a64aa078" + url: "https://pub.dev" + source: hosted + version: "0.1.5" web_socket_channel: dependency: transitive description: name: web_socket_channel - sha256: "939ab60734a4f8fa95feacb55804fa278de28bdeef38e616dc08e44a84adea23" + sha256: a2d56211ee4d35d9b344d9d4ce60f362e4f5d1aafb988302906bd732bc731276 url: "https://pub.dev" source: hosted - version: "2.4.3" + version: "3.0.0" webkit_inspection_protocol: dependency: transitive description: @@ -674,4 +695,4 @@ packages: source: hosted version: "3.1.2" sdks: - dart: ">=3.3.0 <4.0.0" + dart: ">=3.4.0 <4.0.0" diff --git a/examples/dart/test/logger.dart b/examples/dart/test/logger.dart index a743ff6fa8..bd7fd5ec2c 100644 --- a/examples/dart/test/logger.dart +++ b/examples/dart/test/logger.dart @@ -1,167 +1,85 @@ import 'package:test/test.dart'; -import '../bin/models/car.dart'; import 'dart:async'; -import 'dart:isolate'; -import 'package:realm_dart/src/realm_class.dart' show RealmInternal; -import 'package:logging/logging.dart'; import 'package:realm_dart/realm.dart'; import './utils.dart'; - -class LoggedMessage { - final Level level; - final String message; - - const LoggedMessage(this.level, this.message); - - factory LoggedMessage.empty() => LoggedMessage(RealmLogLevel.off, ""); - - @override - // ignore: hash_and_equals - bool operator ==(Object other) { - if (identical(this, other)) return true; - if (other is! LoggedMessage) return false; - return level == other.level && message == other.message; - } - - @override - String toString() => "level:$level message:$message"; -} +import 'schemas.dart'; void main() { - group('Set log level and customize logger', () { - test('Set the log level', () async { - LoggedMessage actual = await Isolate.run(() async { - final completer = Completer(); - - // :snippet-start: set-the-log-level - Realm.logger.level = RealmLogLevel.trace; - // :snippet-end: - // :snippet-start: attach-to-logger - Realm.logger.onRecord.listen((event) { - // Do something with the log event - for example, print to console - print("Realm log message: '$event'"); - // :remove-start: - completer.complete(LoggedMessage(event.level, event.message)); - // :remove-end: - }); - // :snippet-end: - - RealmInternal.logMessageForTesting( - RealmLogLevel.trace, "Realm log message for log level testing"); - - return await completer.future; - }); - - expect( - actual, - LoggedMessage( - RealmLogLevel.trace, "Realm log message for log level testing")); + test('Set log level and customize logger', () async { + final stringBuffer = StringBuffer(); + + // :snippet-start: set-the-log-level + // If no category is set, default is LogCategory.realm + Realm.logger.setLogLevel(LogLevel.all, category: LogCategory.realm); + // :snippet-end: + + // Customize logging behavior + // :snippet-start: set-custom-logger + Realm.logger.onRecord.listen((record) { + // Do something with the log record + // :uncomment-start: + // print(record.message); + // :uncomment-end: + // :remove-start: + // For testing + stringBuffer + .writeln('${record.category} ${record.level}: ${record.message}'); + // :remove-end: }); - test('Set a custom logger', () async { - LoggedMessage actual = await Isolate.run(() async { - final completer = Completer(); - - Realm.logger.onRecord.listen((event) { - throw RealmError( - "Default logger should not log messages if custom logger is set"); - }); - - // :snippet-start: set-custom-logger - Realm.logger = Logger.detached("custom logger"); - // :snippet-end: - Realm.logger.onRecord.listen((event) { - completer.complete(LoggedMessage(event.level, event.message)); - }); - - RealmInternal.logMessageForTesting( - RealmLogLevel.info, "Custom Realm log entry for testing"); - - return await completer.future; - }); - - expect( - actual, - LoggedMessage( - RealmLogLevel.info, "Custom Realm log entry for testing")); - }); - test('Change the log level as needed', () async { - bool logMessageReceived = false; - - Realm.logger.onRecord.listen((event) { - logMessageReceived = true; - }); - - void executeAppCode() { - // Placeholder - } + // :snippet-end: - void executeComplexCodeToDebug() { - // Placeholder - } + final config = Configuration.local([Person.schema]); + final realm = Realm(config); - // :snippet-start: change-log-level - // Set a default log level that's not too verbose - Realm.logger.level = RealmLogLevel.info; - executeAppCode(); - // Later, change the log level to debug an issue when running specific code - Realm.logger.level = RealmLogLevel.trace; - executeComplexCodeToDebug(); - // :snippet-end: + realm.write(() => realm.add(Person(ObjectId(), 'Anakin', 'Skywalker'))); - // Because we changed logging from .info to .trace, this should log a message. - RealmInternal.logMessageForTesting(RealmLogLevel.trace, - "This message should be logged because the log level was changed"); + // Hack to wait for stream to process + await delay(200); - await Future.delayed(Duration(seconds: 2)); + final logs = stringBuffer.toString(); - expect(logMessageReceived, isTrue); - }); - test('Set the log level to off', () async { - bool logMessageReceived = false; + // Expect logs to contain a substring that includes the field and value + // we set earlier + expect(logs.contains('Set \'firstName\' to "Anakin"'), isTrue); - Realm.logger.onRecord.listen((event) { - logMessageReceived = true; - }); + Future executeAppCode() async { + // Capture log length before new write transaction + final oldStringBufferLength = stringBuffer.length; - // Set the log level to the level in our test message to ensure - // the listener would log the event if logging did not turn off. - Realm.logger.level = RealmLogLevel.trace; - // :snippet-start: set-log-level-to-off - Realm.logger.level = RealmLogLevel.off; - // :snippet-end: + realm.write(() => realm.add(Person(ObjectId(), 'Leia', 'Organa'))); - // If logging was enabled at this log level, this should log a message. - // But because the log level is off, it should not log a message. - RealmInternal.logMessageForTesting(RealmLogLevel.trace, - "This message should not appear because the logger is off"); + // Hack to wait for stream to process + await delay(200); - await Future.delayed(Duration(seconds: 2)); + // Ensure that no new logs have been written after setting log level to off + // Length should not change. + expect(stringBuffer.length, oldStringBufferLength); + } - expect(logMessageReceived, isFalse); - }); + Future executeComplexCodeToDebug() async { + // Capture log length before new write transaction + final previousStringBufferLength = stringBuffer.length; - test('Disable logging by clearing listeners', () async { - bool logMessageReceived = false; + realm.write(() => realm.add(Person(ObjectId(), 'Mon', 'Mothma'))); - Realm.logger.onRecord.listen((event) { - logMessageReceived = true; - }); + // Hack to wait for stream to process + await delay(200); - // Set the log level to the level in our test message to ensure - // the listener would log the event if it was active. - Realm.logger.level = RealmLogLevel.trace; - // :snippet-start: clear-listeners - Realm.logger.clearListeners(); - // :snippet-end: + // There should be more log records than before the latest write + // transaction + expect(stringBuffer.length, greaterThan(previousStringBufferLength)); + } - // If logging was enabled at this log level, this should log a message. - // But because we have cleared log listeners, it should not log a message. - RealmInternal.logMessageForTesting(RealmLogLevel.trace, - "This message should not appear because listeners have been cleared"); + // :snippet-start: change-log-level + // :snippet-start: set-log-level-to-off + Realm.logger.setLogLevel(LogLevel.off); + // :snippet-end: + await executeAppCode(); - await Future.delayed(Duration(seconds: 2)); + Realm.logger.setLogLevel(LogLevel.debug, category: LogCategory.realm); + await executeComplexCodeToDebug(); + // :snippet-end: - expect(logMessageReceived, isFalse); - }); + cleanUpRealm(realm); }); } diff --git a/examples/dart/test/utils.dart b/examples/dart/test/utils.dart index ed245e61d0..d0917791f3 100644 --- a/examples/dart/test/utils.dart +++ b/examples/dart/test/utils.dart @@ -18,3 +18,7 @@ String generateRandomString(int len) { return List.generate(len, (index) => _chars[random.nextInt(_chars.length)]) .join(); } + +Future delay(duration) async { + await Future.delayed(Duration(milliseconds: duration)); +} diff --git a/source/examples/generated/flutter/logger.snippet.change-log-level.dart b/source/examples/generated/flutter/logger.snippet.change-log-level.dart index 71f26a4dfb..385771afe2 100644 --- a/source/examples/generated/flutter/logger.snippet.change-log-level.dart +++ b/source/examples/generated/flutter/logger.snippet.change-log-level.dart @@ -1,6 +1,5 @@ -// Set a default log level that's not too verbose -Realm.logger.level = RealmLogLevel.info; -executeAppCode(); -// Later, change the log level to debug an issue when running specific code -Realm.logger.level = RealmLogLevel.trace; -executeComplexCodeToDebug(); +Realm.logger.setLogLevel(LogLevel.off); +await executeAppCode(); + +Realm.logger.setLogLevel(LogLevel.debug, category: LogCategory.realm); +await executeComplexCodeToDebug(); diff --git a/source/examples/generated/flutter/logger.snippet.set-custom-logger.dart b/source/examples/generated/flutter/logger.snippet.set-custom-logger.dart index 41ee882000..b968e3aaf3 100644 --- a/source/examples/generated/flutter/logger.snippet.set-custom-logger.dart +++ b/source/examples/generated/flutter/logger.snippet.set-custom-logger.dart @@ -1 +1,4 @@ -Realm.logger = Logger.detached("custom logger"); +Realm.logger.onRecord.listen((record) { + // Do something with the log record + print(record.message); +}); diff --git a/source/examples/generated/flutter/logger.snippet.set-log-level-to-off.dart b/source/examples/generated/flutter/logger.snippet.set-log-level-to-off.dart index 51bce8ffa3..2932b2a7f9 100644 --- a/source/examples/generated/flutter/logger.snippet.set-log-level-to-off.dart +++ b/source/examples/generated/flutter/logger.snippet.set-log-level-to-off.dart @@ -1 +1 @@ -Realm.logger.level = RealmLogLevel.off; +Realm.logger.setLogLevel(LogLevel.off); diff --git a/source/examples/generated/flutter/logger.snippet.set-the-log-level.dart b/source/examples/generated/flutter/logger.snippet.set-the-log-level.dart index 4ad9503cf3..f2a51ddb52 100644 --- a/source/examples/generated/flutter/logger.snippet.set-the-log-level.dart +++ b/source/examples/generated/flutter/logger.snippet.set-the-log-level.dart @@ -1 +1,2 @@ -Realm.logger.level = RealmLogLevel.trace; +// If no category is set, default is LogCategory.realm +Realm.logger.setLogLevel(LogLevel.all, category: LogCategory.realm); diff --git a/source/includes/api-details/cpp/logger/logging-customize-logger-description.rst b/source/includes/api-details/cpp/logger/logging-customize-logger-description.rst new file mode 100644 index 0000000000..00c65d780a --- /dev/null +++ b/source/includes/api-details/cpp/logger/logging-customize-logger-description.rst @@ -0,0 +1,8 @@ +To set a custom logger function with the C++ SDK, create a +:cpp-sdk:`realm::logger ` +and override the virtual ``do_log()`` member function. + +.. literalinclude:: /examples/generated/cpp/logger.snippet.create-custom-logger.cpp + :language: cpp + +After setting a custom logger, you need to initialize it: diff --git a/source/includes/api-details/cpp/logger/logging-set-change-level-description.rst b/source/includes/api-details/cpp/logger/logging-set-change-level-description.rst new file mode 100644 index 0000000000..48b201654a --- /dev/null +++ b/source/includes/api-details/cpp/logger/logging-set-change-level-description.rst @@ -0,0 +1,3 @@ +For the C++ SDK, pass a +:cpp-sdk:`realm::logger::level ` +to the ``set_default_level_threshold()`` member function: diff --git a/source/includes/api-details/csharp/logger/logging-customize-logger-description.rst b/source/includes/api-details/csharp/logger/logging-customize-logger-description.rst new file mode 100644 index 0000000000..e8603e190a --- /dev/null +++ b/source/includes/api-details/csharp/logger/logging-customize-logger-description.rst @@ -0,0 +1,2 @@ +To set a custom logger with the .NET SDK, set :dotnet-sdk:`Logger.Default +` to a custom Logger function. diff --git a/source/includes/api-details/csharp/logger/logging-set-change-level-description.rst b/source/includes/api-details/csharp/logger/logging-set-change-level-description.rst new file mode 100644 index 0000000000..607283f4c3 --- /dev/null +++ b/source/includes/api-details/csharp/logger/logging-set-change-level-description.rst @@ -0,0 +1,3 @@ +For the .NET SDK, use +:dotnet-sdk:`LogLevel ` to control which +messages are logged by the client logger: \ No newline at end of file diff --git a/source/includes/api-details/dart/logger/logging-customize-logger-description.rst b/source/includes/api-details/dart/logger/logging-customize-logger-description.rst new file mode 100644 index 0000000000..0f9c1c8545 --- /dev/null +++ b/source/includes/api-details/dart/logger/logging-customize-logger-description.rst @@ -0,0 +1,10 @@ +The Flutter SDK logger conforms to the `Dart Logger class +`__. + +To get started, set a log level: + +.. literalinclude:: /examples/generated/flutter/logger.snippet.set-the-log-level.dart + :language: dart + +Define custom logging behavior by listening to :flutter-sdk:`Realm.logger.onRecord +`: diff --git a/source/includes/api-details/dart/logger/logging-set-change-level-description.rst b/source/includes/api-details/dart/logger/logging-set-change-level-description.rst new file mode 100644 index 0000000000..cfd56d52e5 --- /dev/null +++ b/source/includes/api-details/dart/logger/logging-set-change-level-description.rst @@ -0,0 +1,4 @@ +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 +:flutter-sdk:`LogLevel ` value to +:flutter-sdk:`setLogLevel `. diff --git a/source/includes/api-details/javascript/logger/logging-customize-logger-description.rst b/source/includes/api-details/javascript/logger/logging-customize-logger-description.rst new file mode 100644 index 0000000000..b0445f306d --- /dev/null +++ b/source/includes/api-details/javascript/logger/logging-customize-logger-description.rst @@ -0,0 +1,12 @@ +To get started, set a log level: + +.. literalinclude:: /examples/generated/node/v12/logger.test.snippet.set-log-level.ts + :language: javascript + +To set a custom logger with the Node.js SDK, call :js-sdk:`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". diff --git a/source/includes/api-details/javascript/logger/logging-set-change-level-description.rst b/source/includes/api-details/javascript/logger/logging-set-change-level-description.rst new file mode 100644 index 0000000000..2d97486cb5 --- /dev/null +++ b/source/includes/api-details/javascript/logger/logging-set-change-level-description.rst @@ -0,0 +1,12 @@ +To set the level of detail reported by the Node.js SDK pass a valid level to +:js-sdk:`Realm.setLogLevel() `. Refer to +:js-sdk:`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 + `__. diff --git a/source/includes/api-details/kotlin/logger/logging-customize-logger-description.rst b/source/includes/api-details/kotlin/logger/logging-customize-logger-description.rst new file mode 100644 index 0000000000..358d251923 --- /dev/null +++ b/source/includes/api-details/kotlin/logger/logging-customize-logger-description.rst @@ -0,0 +1,11 @@ +The Kotlin SDK implements the :kotlin-sdk:`RealmLogger +<-realm-logger/index.html>` interface for custom loggers. + +.. literalinclude:: /examples/generated/kotlin/SyncTest.snippet.define-custom-logger.kt + :language: kotlin + +In the Kotlin SDK, use :kotlin-sdk:`RealmLog.add() <-realm-log/add.html>` +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. diff --git a/source/includes/api-details/kotlin/logger/logging-set-change-level-description.rst b/source/includes/api-details/kotlin/logger/logging-set-change-level-description.rst new file mode 100644 index 0000000000..87318cf022 --- /dev/null +++ b/source/includes/api-details/kotlin/logger/logging-set-change-level-description.rst @@ -0,0 +1,14 @@ +The Kotlin SDK uses the global :kotlin-sdk:`RealmLog <-realm-log/index.html>` +singleton. You can set the ``RealmLog.level`` property to an entry in the +:kotlin-sdk:`LogLevel <-log-level/index.html>` 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. diff --git a/source/includes/api-details/swift/logger/logging-customize-logger-description.rst b/source/includes/api-details/swift/logger/logging-customize-logger-description.rst new file mode 100644 index 0000000000..55d34edad2 --- /dev/null +++ b/source/includes/api-details/swift/logger/logging-customize-logger-description.rst @@ -0,0 +1,9 @@ +In the Swift SDK, initialize an instance of a :swift-sdk:`Logger +` and define the function to use +for logging. + +.. literalinclude:: /examples/generated/code/start/Logging.snippet.define-custom-logger.swift + :language: swift + +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. diff --git a/source/includes/api-details/swift/logger/logging-set-change-level-description.rst b/source/includes/api-details/swift/logger/logging-set-change-level-description.rst new file mode 100644 index 0000000000..dfddf24d19 --- /dev/null +++ b/source/includes/api-details/swift/logger/logging-set-change-level-description.rst @@ -0,0 +1,12 @@ +For the Swift SDK, set the log level for the default logger with +``Logger.shared.level``. The :objc-sdk:`RLMLogLevel ` +enum represents the different levels of logging you can configure. + +.. tip:: Set the Logger Before Initializing an App Client + + When you initialize an :ref:`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. diff --git a/source/includes/sdk-examples/logger/logging-set-change-level-example-2.rst b/source/includes/sdk-examples/logger/logging-set-change-level-example-2.rst new file mode 100644 index 0000000000..b18ef5c0c0 --- /dev/null +++ b/source/includes/sdk-examples/logger/logging-set-change-level-example-2.rst @@ -0,0 +1,44 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.cpp + :language: cpp + + - id: csharp + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.cs + :language: csharp + + - id: dart + content: | + + .. literalinclude:: /examples/generated/flutter/logger.snippet.change-log-level.dart + :language: dart + + - id: javascript + content: | + + .. literalinclude:: /examples/generated/node/v12/logger.test.snippet.change-log-level.ts + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.kt + :language: kotlin + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/Logging.snippet.change-log-level.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/generated/node/v12/logger.test.snippet.change-log-level.ts + :language: typescript diff --git a/source/includes/sdk-examples/logger/logging-set-change-level-example.rst b/source/includes/sdk-examples/logger/logging-set-change-level-example.rst new file mode 100644 index 0000000000..b1fa858264 --- /dev/null +++ b/source/includes/sdk-examples/logger/logging-set-change-level-example.rst @@ -0,0 +1,44 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/generated/cpp/logger.snippet.set-default-log-level.cpp + :language: cpp + + - id: csharp + content: | + + .. literalinclude:: /examples/generated/dotnet/ErrorHandler.snippet.set-log-level.cs + :language: csharp + + - id: dart + content: | + + .. literalinclude:: /examples/generated/flutter/logger.snippet.set-the-log-level.dart + :language: dart + + - id: javascript + content: | + + .. literalinclude:: /examples/generated/node/v12/logger.test.snippet.set-log-level.ts + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/SyncTest.snippet.set-log-level-realmlog.kt + :language: kotlin + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/Logging.snippet.set-log-level.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/generated/node/v12/logger.test.snippet.set-log-level.ts + :language: typescript diff --git a/source/includes/sdk-examples/logger/logging-set-custom-logger-example.rst b/source/includes/sdk-examples/logger/logging-set-custom-logger-example.rst new file mode 100644 index 0000000000..144313deb9 --- /dev/null +++ b/source/includes/sdk-examples/logger/logging-set-custom-logger-example.rst @@ -0,0 +1,47 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/generated/cpp/logger.snippet.initialize-logger.cpp + :language: cpp + + - id: csharp + content: | + + .. literalinclude:: /examples/generated/dotnet/ErrorHandler.snippet.customize-logging-function.cs + :language: csharp + + - id: dart + content: | + + .. literalinclude:: /examples/generated/flutter/logger.snippet.set-custom-logger.dart + :language: dart + + - id: javascript + content: | + + .. literalinclude:: /examples/generated/node/v12/logger.test.snippet.set-custom-logger.js + :language: javascript + :copyable: false + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/SyncTest.snippet.set-custom-realmlog-logger.kt + :language: kotlin + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/Logging.snippet.set-default-logger.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/generated/node/v12/logger.test.snippet.set-custom-logger.ts + :language: typescript + :copyable: false + diff --git a/source/includes/sdk-examples/logger/logging-turn-off-example.rst b/source/includes/sdk-examples/logger/logging-turn-off-example.rst new file mode 100644 index 0000000000..284c492469 --- /dev/null +++ b/source/includes/sdk-examples/logger/logging-turn-off-example.rst @@ -0,0 +1,47 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.cpp + :language: cpp + :copyable: false + + - id: csharp + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.cs + :language: csharp + :copyable: false + + - id: dart + content: | + + .. literalinclude:: /examples/generated/flutter/logger.snippet.set-log-level-to-off.dart + :language: dart + + - id: javascript + content: | + + .. literalinclude:: /examples/generated/node/v12/logger.test.snippet.disable-logger.ts + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.cs + :language: kotlin + :copyable: false + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/Logging.snippet.turn-logging-off.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/generated/node/v12/logger.test.snippet.disable-logger.ts + :language: typescript diff --git a/source/sdk/test-and-debug/log.txt b/source/sdk/test-and-debug/log.txt index 5f9fc0d083..b8d16be8ea 100644 --- a/source/sdk/test-and-debug/log.txt +++ b/source/sdk/test-and-debug/log.txt @@ -4,10 +4,190 @@ Logging ======= +.. meta:: + :description: Use logging to debug your Atlas Device SDK app. + :keywords: Realm, C++ SDK, Flutter SDK, Kotlin SDK, Java SDK, .NET SDK, Node.js SDK, Swift SDK, code example + +.. facet:: + :name: genre + :values: reference + +.. facet:: + :name: programming_language + :values: cpp, csharp, dart, java, javascript/typescript, kotlin, swift + .. contents:: On this page :local: :backlinks: none :depth: 2 :class: singlecol -Placeholder page for information about logging. +.. tabs-selector:: drivers + +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. + +.. _sdks-set-the-client-log-level: + +Set or Change the Log Level +--------------------------- + +You can set the level of detail reported by Atlas Device SDK. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/logger/logging-set-change-level-description.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/logger/logging-set-change-level-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/logger/logging-set-change-level-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/logger/logging-set-change-level-description.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/logger/logging-set-change-level-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/logger/logging-set-change-level-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/logger/logging-set-change-level-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/javascript/logger/logging-set-change-level-description.rst + +.. include:: /includes/sdk-examples/logger/logging-set-change-level-example.rst + +You can change the log level to increase or decrease verbosity at different +points in your code. + +.. include:: /includes/sdk-examples/logger/logging-set-change-level-example-2.rst + +.. _sdks-customize-logger: + +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. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/logger/logging-customize-logger-description.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/logger/logging-customize-logger-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/logger/logging-customize-logger-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/logger/logging-customize-logger-description.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/logger/logging-customize-logger-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/logger/logging-customize-logger-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/logger/logging-customize-logger-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/javascript/logger/logging-customize-logger-description.rst + +.. include:: /includes/sdk-examples/logger/logging-set-custom-logger-example.rst + +.. include:: /includes/tip-sync-log-levels.rst + +.. _sdks-turn-off-logging: + +Turn Off Logging +---------------- + +You can turn off logging by setting the log level: + +.. include:: /includes/sdk-examples/logger/logging-turn-off-example.rst + +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 +:cpp-sdk:`an instance of an App's sync manager +`, +and pass a :cpp-sdk:`realm::logger::level ` +to the ``set_log_level()`` member function: + +.. literalinclude:: /examples/generated/cpp/quick-start.snippet.set-sync-log-level.cpp + :language: cpp + +Java SDK +~~~~~~~~ + +The SDK logs events to the Android system log automatically. You can +view these events using :android:`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 +:java-sdk:`LogLevel ` to +:java-sdk:`RealmLog.setLevel() `: + +.. literalinclude:: /examples/generated/java/sync/SyncDataTest.snippet.set-client-log-level.java + :language: java