v1.5 logging (version 2) (#6408)

* reworking the guts of the logging system

* fixing compilation errors resulting from conversion to new extension methods

* fixing more compilation issues

had to add missing `Akka.Event` namespace reference

* fixed final compilation errors

* added static methods for all event calls

* simplified `ILoggingAdapter` API

* added API approvals

* fixed erroneous ReSharperisms

* added docs

* fix typos and markdown linting

docs/community/whats-new/akkadotnet-v1.5-upgrade-advisories.md

@@ -160,3 +160,28 @@ akka.cluster.sharding {
 ```
 
 If you run into any trouble upgrading, [please file an issue with Akka.NET](https://github.com/akkadotnet/akka.net/issues/new/choose).
+
+### Breaking Logging Changes
+
+In v1.5, we've re-engineering the `ILoggingAdapter` construct to be more extensible and performant. Unfortunately this necessitate some breaking changes that will affect end-user code - but the remedy for those changes is trivial.
+
+After installing the v1.5 NuGet packages into your applications or libraries, you will need to add the following to all of your source files where you previously made calls to the `ILoggingAdapter`:
+
+```csharp
+using Akka.Event;
+```
+
+That `using` statement will pull in the extension methods that match all of the v1.4 API `ILoggingAdapter` signatures in v1.5.
+
+_Even better_ - if you can take advantage of [`global using` statements in C#10](https://blog.jetbrains.com/dotnet/2021/11/18/global-usings-in-csharp-10/), then this is a one-liner as either the MSBuild or project level:
+
+In `Directory.Build.props`:
+
+```xml
+<Project>
+    <ItemGroup>
+        <PackageReference Include="Akka" />
+        <Using Include="Akka.Event" />
+    </ItemGroup>
+</Project>
+```

src/benchmark/Akka.Benchmarks/Logging/LoggingBenchmarks.cs

@@ -35,68 +35,28 @@ public BenchmarkLogAdapter(int capacity) : base(DefaultLogMessageFormatter.Insta
             public override bool IsDebugEnabled { get; } = true;
             public override bool IsInfoEnabled { get; } = true;
             public override bool IsWarningEnabled { get; } = true;
-            public override bool IsErrorEnabled { get; } = true;
-
-            private void AddLogMessage(LogEvent m)
+
+            private LogEvent CreateLogEvent(LogLevel logLevel, object message, Exception cause = null)
             {
-                AllLogs[CurrentLogs++] = m;
+                return logLevel switch
+                {
+                    LogLevel.DebugLevel => new Debug(cause, _logSource, _logClass, message),
+                    LogLevel.InfoLevel => new Info(cause, _logSource, _logClass, message),
+                    LogLevel.WarningLevel => new Warning(cause, _logSource, _logClass, message),
+                    LogLevel.ErrorLevel => new Error(cause, _logSource, _logClass, message),
+                    _ => throw new ArgumentOutOfRangeException(nameof(logLevel), logLevel, null)
+                };
             }
-
-            protected override void NotifyError(object message)
+            protected override void NotifyLog(LogLevel logLevel, object message, Exception cause = null)
             {
-               AddLogMessage(new Error(null, _logSource, _logClass, message));
+                AddLogMessage(CreateLogEvent(logLevel, message, cause));
             }
 
-            /// <summary>
-            /// Publishes the error message and exception onto the LoggingBus.
-            /// </summary>
-            /// <param name="cause">The exception that caused this error.</param>
-            /// <param name="message">The error message.</param>
-            protected override void NotifyError(Exception cause, object message)
-            {
-                AddLogMessage(new Error(cause, _logSource, _logClass, message));
-            }
-
-            /// <summary>
-            /// Publishes the warning message onto the LoggingBus.
-            /// </summary>
-            /// <param name="message">The warning message.</param>
-            protected override void NotifyWarning(object message)
-            {
-                AddLogMessage(new Warning(_logSource, _logClass, message));
-            }
-
-            protected override void NotifyWarning(Exception cause, object message)
-            {
-                AddLogMessage(new Warning(cause, _logSource, _logClass, message));
-            }
-
-            /// <summary>
-            /// Publishes the info message onto the LoggingBus.
-            /// </summary>
-            /// <param name="message">The info message.</param>
-            protected override void NotifyInfo(object message)
-            {
-                AddLogMessage(new Info(_logSource, _logClass, message));
-            }
-
-            protected override void NotifyInfo(Exception cause, object message)
-            {
-                AddLogMessage(new Info(cause, _logSource, _logClass, message));
-            }
-
-            /// <summary>
-            /// Publishes the debug message onto the LoggingBus.
-            /// </summary>
-            /// <param name="message">The debug message.</param>
-            protected override void NotifyDebug(object message)
-            {
-                AddLogMessage(new Debug(_logSource, _logClass, message));
-            }
+            public override bool IsErrorEnabled { get; } = true;
 
-            protected override void NotifyDebug(Exception cause, object message)
+            private void AddLogMessage(LogEvent m)
             {
-                AddLogMessage(new Debug(cause, _logSource, _logClass, message));
+                AllLogs[CurrentLogs++] = m;
             }
         }
 

src/contrib/cluster/Akka.Cluster.Metrics/ClusterMetrics.cs

@@ -13,6 +13,7 @@
 using Akka.Cluster.Metrics.Helpers;
 using Akka.Cluster.Metrics.Serialization;
 using Akka.Configuration;
+using Akka.Event;
 using Akka.Util;
 using ConfigurationFactory = Akka.Configuration.ConfigurationFactory;
 
@@ -88,7 +89,7 @@ public ClusterMetricsStrategy Strategy
                     {
                         _system.Log.Error(
                             $"Configured strategy provider {Settings.SupervisorStrategyProvider} failed to load, " +
-                            $"using default {typeof(ClusterMetricsStrategy).Name}.");
+                            $"using default {nameof(ClusterMetricsStrategy)}.");
                         return new ClusterMetricsStrategy(Settings.SupervisorStrategyConfiguration);
                     })
                     .Get();

src/contrib/cluster/Akka.Cluster.Sharding.Tests.MultiNode/ClusterShardCoordinatorDowning2Spec.cs

@@ -11,6 +11,7 @@
 using System.Linq;
 using System.Threading;
 using Akka.Actor;
+using Akka.Event;
 using Akka.MultiNode.TestAdapter;
 using Akka.Remote.TestKit;
 using Akka.Util;

src/contrib/cluster/Akka.Cluster.Sharding.Tests.MultiNode/ClusterShardCoordinatorDowningSpec.cs

@@ -11,6 +11,7 @@
 using System.Linq;
 using System.Threading;
 using Akka.Actor;
+using Akka.Event;
 using Akka.MultiNode.TestAdapter;
 using Akka.Remote.TestKit;
 using Akka.Util;

src/contrib/cluster/Akka.Cluster.Sharding.Tests.MultiNode/ClusterShardingGetStatsSpec.cs

@@ -9,6 +9,7 @@
 using System.Linq;
 using Akka.Actor;
 using Akka.Configuration;
+using Akka.Event;
 using Akka.MultiNode.TestAdapter;
 using Akka.Remote.TestKit;
 using Akka.Util;

src/contrib/cluster/Akka.Cluster.Sharding.Tests.MultiNode/ClusterShardingLeavingSpec.cs

@@ -10,6 +10,7 @@
 using System.Collections.Immutable;
 using System.Linq;
 using Akka.Actor;
+using Akka.Event;
 using Akka.MultiNode.TestAdapter;
 using Akka.Remote.TestKit;
 using Akka.Util;

src/contrib/cluster/Akka.Cluster.Sharding.Tests/LeastShardAllocationStrategyRandomizedSpec.cs

@@ -9,6 +9,7 @@
 using System.Collections.Immutable;
 using System.Linq;
 using Akka.Actor;
+using Akka.Event;
 using Akka.TestKit;
 using FluentAssertions;
 using FluentAssertions.Execution;

src/contrib/cluster/Akka.Cluster.Sharding.Tests/PersistentStartEntitySpec.cs

@@ -10,6 +10,7 @@
 using Akka.Actor;
 using Akka.Cluster.Tools.Singleton;
 using Akka.Configuration;
+using Akka.Event;
 using Akka.TestKit;
 using Akka.Util;
 using FluentAssertions;

src/contrib/cluster/Akka.Cluster.Sharding.Tests/ShardedDaemonProcessSpec.cs

@@ -10,6 +10,7 @@
 using Akka.Actor;
 using Akka.Cluster.Tools.Singleton;
 using Akka.Configuration;
+using Akka.Event;
 using Akka.TestKit;
 using Xunit;
 

src/contrib/cluster/Akka.Cluster.Sharding.Tests/StorageHelpers.cs

@@ -9,6 +9,7 @@
 using System.IO;
 using Akka.Actor;
 using Akka.Configuration;
+using Akka.Event;
 using Akka.TestKit;
 using FluentAssertions;
 

src/contrib/cluster/Akka.Cluster.Sharding/ClusterSharding.cs

@@ -17,6 +17,7 @@
 using Akka.Cluster.Tools.Singleton;
 using Akka.Configuration;
 using Akka.Dispatch;
+using Akka.Event;
 using Akka.Pattern;
 using Akka.Util;
 
@@ -274,19 +275,19 @@ public class ClusterSharding : IExtension
         private readonly Cluster _cluster;
 
         /// <summary>
-        /// TBD
+        /// Retrieves or creates the <see cref="ClusterSharding"/> extension for the given <see cref="ActorSystem"/>.
         /// </summary>
-        /// <param name="system">TBD</param>
-        /// <returns>TBD</returns>
+        /// <param name="system">The ActorSystem.</param>
+        /// <returns>The singleton instances of the ClusterSharding extension associated with this ActorSystem.</returns>
         public static ClusterSharding Get(ActorSystem system)
         {
             return system.WithExtension<ClusterSharding, ClusterShardingExtensionProvider>();
         }
 
         /// <summary>
-        /// TBD
+        /// Instantiates the Akka.Cluster.Sharding extension for this system.
         /// </summary>
-        /// <param name="system">TBD</param>
+        /// <param name="system">The ActorSystem.</param>
         public ClusterSharding(ExtendedActorSystem system)
         {
             _system = system;
@@ -1357,7 +1358,7 @@ public Task<IActorRef> StartProxyAsync(string typeName, string role, IMessageExt
 #pragma warning disable CS0419 // Ambiguous reference in cref attribute
         /// <summary>
         /// Retrieve the actor reference of the <see cref="Sharding.ShardRegion"/> actor responsible for the named entity type.
-        /// The entity type must be registered with the <see cref="Start"/> or <see cref="StartProxy"/> method before it
+        /// The entity type must be registered with the <see cref="ClusterSharding.Start"/> or <see cref="ClusterSharding.StartProxy"/> method before it
         /// can be used here. Messages to the entity is always sent via the <see cref="Sharding.ShardRegion"/>.
         /// </summary>
         /// <param name="typeName">TBD</param>
@@ -1383,7 +1384,7 @@ public IActorRef ShardRegion(string typeName)
         /// Retrieve the actor reference of the <see cref="Sharding.ShardRegion"/> actor that will act as a proxy to the
         /// named entity type running in another data center. A proxy within the same data center can be accessed
         /// with <see cref="Sharding.ShardRegion"/> instead of this method. The entity type must be registered with the
-        /// <see cref="StartProxy"/> method before it can be used here. Messages to the entity is always sent
+        /// <see cref="ClusterSharding.StartProxy"/> method before it can be used here. Messages to the entity is always sent
         /// via the <see cref="Sharding.ShardRegion"/>.
         /// </summary>
         /// <param name="typeName"></param>

src/contrib/cluster/Akka.Cluster.Sharding/Internal/EventSourcedRememberEntitiesCoordinatorStore.cs

@@ -10,6 +10,7 @@
 using System.Collections.Immutable;
 using System.Linq;
 using Akka.Actor;
+using Akka.Event;
 using Akka.Persistence;
 
 namespace Akka.Cluster.Sharding.Internal

src/contrib/cluster/Akka.Cluster.Sharding/Internal/EventSourcedRememberEntitiesShardStore.cs

@@ -9,6 +9,7 @@
 using System.Collections.Generic;
 using System.Collections.Immutable;
 using Akka.Actor;
+using Akka.Event;
 using Akka.Persistence;
 
 namespace Akka.Cluster.Sharding.Internal

src/contrib/cluster/Akka.Cluster.Sharding/ShardedDaemonProcess.cs

@@ -9,6 +9,7 @@
 using System.Linq;
 using Akka.Actor;
 using Akka.Annotations;
+using Akka.Event;
 using Akka.Util.Internal;
 
 namespace Akka.Cluster.Sharding

src/contrib/cluster/Akka.Cluster.Tools.Tests.MultiNode/ClusterClient/ClusterClientSpec.cs

@@ -17,6 +17,7 @@
 using Akka.Cluster.Tools.PublishSubscribe;
 using Akka.Cluster.Tools.PublishSubscribe.Internal;
 using Akka.Configuration;
+using Akka.Event;
 using Akka.MultiNode.TestAdapter;
 using Akka.Remote.TestKit;
 using Akka.Remote.Transport;

src/contrib/cluster/Akka.Cluster.Tools.Tests.MultiNode/Singleton/ClusterSingletonManagerChaosSpec.cs

@@ -11,6 +11,7 @@
 using Akka.Cluster.TestKit;
 using Akka.Cluster.Tools.Singleton;
 using Akka.Configuration;
+using Akka.Event;
 using Akka.MultiNode.TestAdapter;
 using Akka.Remote.TestKit;
 using Akka.TestKit;

src/contrib/cluster/Akka.Cluster.Tools.Tests/Singleton/ClusterSingletonLeavingSpeedSpec.cs

@@ -14,6 +14,7 @@
 using Akka.Actor;
 using Akka.Cluster.Tools.Singleton;
 using Akka.Configuration;
+using Akka.Event;
 using Akka.TestKit;
 using Akka.TestKit.TestActors;
 using FluentAssertions;

src/contrib/cluster/Akka.DistributedData.Tests.MultiNode/DurableDataPocoSpec.cs

@@ -13,6 +13,7 @@
 using Akka.Cluster.TestKit;
 using Akka.Configuration;
 using Akka.DistributedData.Durable;
+using Akka.Event;
 using Akka.MultiNode.TestAdapter;
 using Akka.Remote.TestKit;
 using Akka.TestKit;

src/contrib/cluster/Akka.DistributedData.Tests.MultiNode/DurableDataSpec.cs

@@ -13,6 +13,7 @@
 using Akka.Cluster.TestKit;
 using Akka.Configuration;
 using Akka.DistributedData.Durable;
+using Akka.Event;
 using Akka.MultiNode.TestAdapter;
 using Akka.Remote.TestKit;
 using Akka.TestKit;

src/contrib/cluster/Akka.DistributedData.Tests.MultiNode/ReplicatorSpec.cs

@@ -14,6 +14,7 @@
 using System.Linq;
 using Akka.Cluster;
 using Akka.Cluster.TestKit;
+using Akka.Event;
 using Akka.MultiNode.TestAdapter;
 using Akka.Remote.Transport;
 using Akka.TestKit;

src/contrib/cluster/Akka.DistributedData.Tests/ReplicatorResiliencySpec.cs

@@ -15,6 +15,7 @@
 using Akka.Dispatch.SysMsg;
 using Akka.DistributedData.Durable;
 using Akka.DistributedData.LightningDB;
+using Akka.Event;
 using Akka.Pattern;
 using Akka.TestKit;
 using FluentAssertions;

src/contrib/cluster/Akka.DistributedData.Tests/ReplicatorSpecs.cs

@@ -16,6 +16,7 @@
 using Akka.Actor;
 using Akka.Cluster;
 using Akka.Configuration;
+using Akka.Event;
 using Akka.TestKit;
 using FluentAssertions;
 using FluentAssertions.Extensions;

src/contrib/dependencyinjection/Akka.DependencyInjection/DependencyResolverSetup.cs

@@ -46,7 +46,7 @@ public static ServiceProviderSetup Create(IServiceProvider provider)
     /// The <see cref="IDependencyResolver"/> will be used to access previously registered services
     /// in the creation of actors and other pieces of infrastructure inside Akka.NET.
     ///
-    /// The constructor is internal. Please use <see cref="Create"/> to create a new instance.
+    /// The constructor is internal. Please use <see cref="DependencyResolverSetup.Create"/> to create a new instance.
     /// </summary>
     public class DependencyResolverSetup : Setup
     {

src/contrib/testkits/Akka.TestKit.Xunit/Internals/Loggers.cs

@@ -48,7 +48,7 @@ private void Write(LogEvent e)
                 if (e.Message is LogMessage msg)
                 {
                     var message =
-                        $"Received a malformed formatted message. Log level: [{e.LogLevel()}], Template: [{msg.Format}], args: [{string.Join(",", msg.Args)}]";
+                        $"Received a malformed formatted message. Log level: [{e.LogLevel()}], Template: [{msg.Format}], args: [{string.Join(",", msg.Unformatted())}]";
                     if(e.Cause != null)
                         throw new AggregateException(message, ex, e.Cause);
                     throw new FormatException(message, ex);

src/contrib/testkits/Akka.TestKit.Xunit2/Internals/Loggers.cs

@@ -50,7 +50,7 @@ private void HandleLogEvent(LogEvent e)
                 if (e.Message is LogMessage msg)
                 {
                     var message =
-                        $"Received a malformed formatted message. Log level: [{e.LogLevel()}], Template: [{msg.Format}], args: [{string.Join(",", msg.Args)}]";
+                        $"Received a malformed formatted message. Log level: [{e.LogLevel()}], Template: [{msg.Format}], args: [{string.Join(",", msg.Unformatted())}]";
                     if (e.Cause != null)
                         throw new AggregateException(message, ex, e.Cause);
                     throw new FormatException(message, ex);