RNET-1161: Implement support for using a log level for a specific log category

CHANGELOG.md

@@ -1,9 +1,29 @@
 ## vNext (TBD)
 
+### Deprecations
+* The `Logger.LogLevel` `set` and `get` accessors have been deprecated. Please use `Logger.SetLogLevel()` and `Logger.GetLogLevel()` (see **Enhancements** below).
+* The `Logger.Function(Action<LogLevel, string> logFunction)` have been deprecated. Please use `Logger.Function(Action<LogLevel, LogCategory, string> logFunction)` (see **Enhancements** below).
+
 ### Enhancements
 * Allow `ShouldCompactOnLaunch` to be set on `SyncConfiguration`, not only `RealmConfiguration`. (Issue [#3617](https://github.com/realm/realm-dotnet/issues/3617))
 * Reduce the size of the local transaction log produced by creating objects, improving the performance of insertion-heavy transactions (Core 14.10.0).
 * Performance has been improved for range queries on integers and timestamps. Requires that you use the "BETWEEN" operation in `Realm.All<T>().Filter(...)`. (Core 14.10.1)
+* Allowed `ShouldCompactOnLaunch` to be set on `SyncConfiguration`, not only `RealmConfiguration`. (Issue [#3617](https://github.com/realm/realm-dotnet/issues/3617))
+* Introduced a `LogCategory` and allowed for more control over which category of messages should be logged and at which criticality level:
+  * Allowed setting and getting a `LogLevel` for a given `LogCategory`. The hierarchy of categories starts at `LogCategory.Realm`.
+    ```csharp
+    Logger.SetLogLevel(LogLevel.Warn, LogCategory.Realm.Sync);
+    Logger.GetLogLevel(LogCategory.Realm.Sync.Client.Session); // LogLevel.Warn
+    ```
+  * Added a function logger that accepts a callback that will receive the `LogLevel`, `LogCategory`, and the message when invoked.
+    ```csharp
+    Logger.Default = Logger.Function((level, category, message) => /* custom implementation */);
+    ```
+  * Added an optional category as a last parameter to `Logger.Log()`. If unset, `LogCategory.Realm.SDK` will be used.
+    ```csharp
+    Logger.Default.Log(LogLevel.Warn, "A warning message", LogCategory.Realm);
+    ```
+    (PR [#3634](https://github.com/realm/realm-dotnet/pull/3634))
 
 ### Fixed
 * A `ForCurrentlyOutstandingWork` progress notifier would not immediately call its callback after registration. Instead you would have to wait for some data to be received to get your first update - if you were already caught up when you registered the notifier you could end up waiting a long time for the server to deliver a download that would call/expire your notifier. (Core 14.8.0)

Realm/Realm.UnityUtils/UnityLogger.cs

@@ -22,9 +22,9 @@ namespace UnityUtils
 {
     public class UnityLogger : Logger
     {
-        protected override void LogImpl(LogLevel level, string message)
+        protected override void LogImpl(LogLevel level, string message, LogCategory? category = null)
         {
-            var toLog = FormatLog(level, message);
+            var toLog = FormatLog(level, message, category!);
             switch (level)
             {
                 case LogLevel.Fatal:

Realm/Realm/Handles/SharedRealmHandle.cs

@@ -19,6 +19,7 @@
 using System;
 using System.Collections.Generic;
 using System.Diagnostics.CodeAnalysis;
+using System.Linq;
 using System.Runtime.InteropServices;
 using System.Threading;
 using System.Threading.Tasks;
@@ -48,6 +49,17 @@
 
         private static class NativeMethods
         {
+            // This is a wrapper struct around MarshaledVector since P/Invoke doesn't like it
+            // when the MarshaledVector is returned as the top-level return value from a native
+            // function. This only manifests in .NET Framework and is not an issue with Mono/.NET.
+            // The native return value is MarshaledVector without the wrapper because they are binary
+            // compatible.
+            [StructLayout(LayoutKind.Sequential)]
+            public struct CategoryNamesContainer
+            {
+                public MarshaledVector<StringValue> CategoryNames;
+            }
+
 #pragma warning disable IDE0049 // Use built-in type alias
 #pragma warning disable SA1121 // Use built-in type alias
 
@@ -63,8 +75,9 @@
             [UnmanagedFunctionPointer(CallingConvention.Cdecl)]
             public delegate void DisposeGCHandleCallback(IntPtr handle);
 
+            // TODO(lj): Update arg order to be the same across the SDK.
             [UnmanagedFunctionPointer(CallingConvention.Cdecl)]
-            public delegate void LogMessageCallback(StringValue message, LogLevel level);
+            public delegate void LogMessageCallback(StringValue message, LogLevel level, StringValue categoryName);
 
             [UnmanagedFunctionPointer(CallingConvention.Cdecl)]
             public delegate void HandleTaskCompletionCallback(IntPtr tcs_ptr, [MarshalAs(UnmanagedType.U1)] bool invoke_async, NativeException ex);
@@ -223,8 +236,14 @@
             [DllImport(InteropConfig.DLL_NAME, EntryPoint = "shared_realm_refresh_async", CallingConvention = CallingConvention.Cdecl)]
             public static extern bool refresh_async(SharedRealmHandle realm, IntPtr tcs_handle, out NativeException ex);
 
+            [DllImport(InteropConfig.DLL_NAME, EntryPoint = "shared_realm_get_log_level", CallingConvention = CallingConvention.Cdecl)]
+            public static extern LogLevel get_log_level([MarshalAs(UnmanagedType.LPWStr)] string category_name, IntPtr category_name_len);
+
             [DllImport(InteropConfig.DLL_NAME, EntryPoint = "shared_realm_set_log_level", CallingConvention = CallingConvention.Cdecl)]
-            public static extern bool set_log_level(LogLevel level);
+            public static extern void set_log_level(LogLevel level, [MarshalAs(UnmanagedType.LPWStr)] string category_name, IntPtr category_name_len);
+
+            [DllImport(InteropConfig.DLL_NAME, EntryPoint = "shared_realm_get_log_category_names", CallingConvention = CallingConvention.Cdecl)]
+            public static extern CategoryNamesContainer get_log_category_names();
 
             [DllImport(InteropConfig.DLL_NAME, EntryPoint = "shared_realm_get_operating_system", CallingConvention = CallingConvention.Cdecl)]
             public static extern IntPtr get_operating_system(IntPtr buffer, IntPtr buffer_length);
@@ -271,7 +290,15 @@
                 notifyObject, notifyDictionary, onMigration, shouldCompact, handleTaskCompletion, onInitialization);
         }
 
-        public static void SetLogLevel(LogLevel level) => NativeMethods.set_log_level(level);
+        public static LogLevel GetLogLevel(LogCategory category) => NativeMethods.get_log_level(category.Name, (IntPtr)category.Name.Length);
+
+        public static void SetLogLevel(LogLevel level, LogCategory category) => NativeMethods.set_log_level(level, category.Name, (IntPtr)category.Name.Length);
+
+        public static string[] GetLogCategoryNames() => NativeMethods.get_log_category_names()
+            .CategoryNames
+            .ToEnumerable()
+            .Select(name => name.ToDotnetString()!)
+            .ToArray();
 
         [Preserve]
         protected SharedRealmHandle(IntPtr handle) : base(handle)
@@ -822,9 +849,9 @@
         }
 
         [MonoPInvokeCallback(typeof(NativeMethods.LogMessageCallback))]
-        private static void LogMessage(StringValue message, LogLevel level)
+        private static void LogMessage(StringValue message, LogLevel level, StringValue categoryName)
         {
-            Logger.LogDefault(level, message!);
+            Logger.LogDefault(level, message!, LogCategory.FromName(categoryName!));
         }
 
         [MonoPInvokeCallback(typeof(NativeMethods.MigrationCallback))]

Realm/Realm/Logging/LogCategory.cs

@@ -0,0 +1,226 @@
+////////////////////////////////////////////////////////////////////////////
+//
+// Copyright 2024 Realm Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License")
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+////////////////////////////////////////////////////////////////////////////
+
+using System.Collections.Generic;
+using Realms.Helpers;
+
+namespace Realms.Logging
+{
+    /// <summary>
+    /// Specifies the category to receive log messages for when logged by the default
+    /// logger. The <see cref="LogLevel"/> will always be set for a specific category.
+    /// Setting the log level for one category will automatically set the same level
+    /// for all of its subcategories.
+    /// <code>
+    /// Realm
+    /// ├─► Storage
+    /// │   ├─► Transaction
+    /// │   ├─► Query
+    /// │   ├─► Object
+    /// │   └─► Notification
+    /// ├─► Sync
+    /// │   ├─► Client
+    /// │   │   ├─► Session
+    /// │   │   ├─► Changeset
+    /// │   │   ├─► Network
+    /// │   │   └─► Reset
+    /// │   └─► Server
+    /// ├─► App
+    /// └─► Sdk
+    /// </code>
+    /// </summary>
+    /// <example>
+    /// <code>
+    /// LogCategory.Realm.Sync.Client
+    /// </code>
+    /// </example>
+    public class LogCategory
+    {
+        /// <summary>
+        /// Gets the name of the category.
+        /// </summary>
+        public string Name { get; }
+
+        /// <summary>
+        /// Gets the top-level category for receiving log messages for all categories.
+        /// </summary>
+        public static RealmLogCategory Realm { get; } = new();
+
+        internal static readonly Dictionary<string, LogCategory> NameToCategory = new()
+        {
+            { Realm.Name, Realm },
+            { Realm.Storage.Name, Realm.Storage },
+            { Realm.Storage.Transaction.Name, Realm.Storage.Transaction },
+            { Realm.Storage.Query.Name, Realm.Storage.Query },
+            { Realm.Storage.Object.Name, Realm.Storage.Object },
+            { Realm.Storage.Notification.Name, Realm.Storage.Notification },
+            { Realm.Sync.Name, Realm.Sync },
+            { Realm.Sync.Client.Name, Realm.Sync.Client },
+            { Realm.Sync.Client.Session.Name, Realm.Sync.Client.Session },
+            { Realm.Sync.Client.Changeset.Name, Realm.Sync.Client.Changeset },
+            { Realm.Sync.Client.Network.Name, Realm.Sync.Client.Network },
+            { Realm.Sync.Client.Reset.Name, Realm.Sync.Client.Reset },
+            { Realm.Sync.Server.Name, Realm.Sync.Server },
+            { Realm.App.Name, Realm.App },
+            { Realm.SDK.Name, Realm.SDK },
+        };
+
+        private LogCategory(string name, LogCategory? parent) => Name = parent == null ? name : $"{parent}.{name}";
+
+        internal static LogCategory FromName(string name)
+        {
+            Argument.Ensure(NameToCategory.TryGetValue(name, out var category), $"Unexpected category name: '{name}'", nameof(name));
+
+            return category;
+        }
+
+        /// <summary>
+        /// Returns a string that represents the category, equivalent to its name.
+        /// </summary>
+        /// <returns>A string that represents the category, equivalent to its name.</returns>
+        public override string ToString() => Name;
+
+        /// <summary>
+        /// The top-level category for receiving log messages for all categories.
+        /// </summary>
+        public class RealmLogCategory : LogCategory
+        {
+            /// <summary>
+            /// Gets the category for receiving log messages pertaining to database events.
+            /// </summary>
+            public StorageLogCategory Storage { get; }
+
+            /// <summary>
+            /// Gets the category for receiving log messages pertaining to Atlas Device Sync.
+            /// </summary>
+            public SyncLogCategory Sync { get; }
+
+            /// <summary>
+            /// Gets the category for receiving log messages pertaining to Atlas App.
+            /// </summary>
+            public LogCategory App { get; }
+
+            // TODO(lj): Prefer `SDK` or `Sdk` for c#?
+            /// <summary>
+            /// Gets the category for receiving log messages pertaining to the SDK.
+            /// </summary>
+            public LogCategory SDK { get; }
+
+            internal RealmLogCategory() : base("Realm", null)
+            {
+                Storage = new StorageLogCategory(this);
+                Sync = new SyncLogCategory(this);
+                App = new LogCategory("App", this);
+                SDK = new LogCategory("SDK", this);
+            }
+        }
+
+        /// <summary>
+        /// The category for receiving log messages pertaining to database events.
+        /// </summary>
+        public class StorageLogCategory : LogCategory
+        {
+            /// <summary>
+            /// Gets the category for receiving log messages when creating, advancing, and
+            /// committing transactions.
+            /// </summary>
+            public LogCategory Transaction { get; }
+
+            /// <summary>
+            /// Gets the category for receiving log messages when querying the database.
+            /// </summary>
+            public LogCategory Query { get; }
+
+            /// <summary>
+            /// Gets the category for receiving log messages when mutating the database.
+            /// </summary>
+            public LogCategory Object { get; }
+
+            /// <summary>
+            /// Gets the category for receiving log messages when there are notifications
+            /// of changes to the database.
+            /// </summary>
+            public LogCategory Notification { get; }
+
+            internal StorageLogCategory(LogCategory parent) : base("Storage", parent)
+            {
+                Transaction = new LogCategory("Transaction", this);
+                Query = new LogCategory("Query", this);
+                Object = new LogCategory("Object", this);
+                Notification = new LogCategory("Notification", this);
+            }
+        }
+
+        /// <summary>
+        /// The category for receiving log messages pertaining to Atlas Device Sync.
+        /// </summary>
+        public class SyncLogCategory : LogCategory
+        {
+            /// <summary>
+            /// Gets the category for receiving log messages pertaining to sync client operations.
+            /// </summary>
+            public ClientLogCategory Client { get; }
+
+            /// <summary>
+            /// Gets the category for receiving log messages pertaining to sync server operations.
+            /// </summary>
+            public LogCategory Server { get; }
+
+            internal SyncLogCategory(LogCategory parent) : base("Sync", parent)
+            {
+                Client = new ClientLogCategory(this);
+                Server = new LogCategory("Server", this);
+            }
+        }
+
+        /// <summary>
+        /// The category for receiving log messages pertaining to sync client operations.
+        /// </summary>
+        public class ClientLogCategory : LogCategory
+        {
+            /// <summary>
+            /// Gets the category for receiving log messages pertaining to the sync session.
+            /// </summary>
+            public LogCategory Session { get; }
+
+            /// <summary>
+            /// Gets the category for receiving log messages when receiving, uploading, and
+            /// integrating changesets.
+            /// </summary>
+            public LogCategory Changeset { get; }
+
+            /// <summary>
+            /// Gets the category for receiving log messages pertaining to low-level network activity.
+            /// </summary>
+            public LogCategory Network { get; }
+
+            /// <summary>
+            /// Gets the category for receiving log messages when there are client reset operations.
+            /// </summary>
+            public LogCategory Reset { get; }
+
+            internal ClientLogCategory(LogCategory parent) : base("Client", parent)
+            {
+                Session = new LogCategory("Session", this);
+                Changeset = new LogCategory("Changeset", this);
+                Network = new LogCategory("Network", this);
+                Reset = new LogCategory("Reset", this);
+            }
+        }
+    }
+}