feat: Add native semantic logging support with property extraction (#7933)

* feat: Add native semantic logging support to Akka.NET core

Implements semantic/structured logging with support for both positional ({0})
and named ({PropertyName}) message templates, enabling structured property
extraction for external logging frameworks.

Key Features:
- MessageTemplateParser with ThreadStatic LRU cache for template parsing
- LogMessage enhanced with PropertyNames and GetProperties() APIs
- SemanticLogMessageFormatter for Serilog-style template formatting
- LogEventExtensions helper methods for easy property extraction
- StandardOutLogger updated to display semantic properties
- Zero new dependencies - pure BCL implementation
- Full backward compatibility maintained

Performance Optimizations:
- ThreadStatic caching avoids lock contention
- Lazy property evaluation (zero cost if not used)
- FrozenDictionary on .NET 8+ for optimal read performance
- LRU eviction prevents unbounded cache growth

Testing:
- 25 new unit tests covering template parsing, property extraction, and formatting
- All 79 existing logger tests pass (full backward compatibility)
- Tests validate positional templates, named templates, edge cases, and caching

This enables external logger plugins (Serilog, NLog, MEL) to easily extract
structured properties using logEvent.TryGetProperties() for integration with
their native structured logging capabilities.

Addresses #7932

* perf: optimize semantic logging memory allocations (75% reduction)

Implemented Priority 1 performance optimizations to reduce GC pressure
in semantic logging operations.

Changes:
- LogMessage.GetProperties(): Avoid ToArray() when Parameters() returns
  IReadOnlyList<object> (LogValues<T> structs), saving ~200-300 bytes
- SemanticLogMessageFormatter.Format(): Check args type before conversion,
  use IReadOnlyList directly for named templates, only convert to array
  when required by string.Format(), saving ~500-800 bytes
- SemanticLoggingBenchmarks: Add comprehensive benchmark suite (34 benchmarks)
  and fix GlobalSetup to include GetProperties benchmarks

Performance Results:
- Full E2E pipeline: 1592B → 400B (75% reduction) 🎯
- Format 3 params: 1248B → 680B (45% reduction)
- GetProperties access: 526ns → 1.7ns (99.7% faster)
- Template cache hits: 70ns → 47ns (33% faster)
- E2E semantic logging: 1.34μs → 284ns (79% faster)

All 79 unit tests passing. Benchmarks confirm optimizations maintain
correctness while achieving target allocation reductions.

Addresses #7932

* Enable SemanticLogMessageFormatter as default logger formatter

Changed the default logger formatter from DefaultLogMessageFormatter to SemanticLogMessageFormatter to enable semantic logging support by default. This allows both positional {0} and named {PropertyName} templates to work out of the box.

Changes:
- Updated akka.conf to use SemanticLogMessageFormatter as default
- Added special case handling in Settings.cs for SemanticLogMessageFormatter singleton instance

All 62 existing logger tests pass, confirming backward compatibility with positional templates while enabling new semantic logging capabilities.

* feat: Add EventFilter support for semantic logging templates

Enables EventFilter to match against semantic logging templates in unit tests, resolving the core issue from GitHub #7932 where EventFilter.Info("BetId:{BetId}") would fail to match log messages using named property syntax.

Changes:
- Modified EventFilterBase.InternalDoMatch to check LogMessage.Format template before falling back to formatted output
- Allows matching against both template patterns ("{UserId}") and formatted values ("12345")
- Added comprehensive tests for EventFilter with semantic templates (exact match, contains, starts with)
- Removed FormatException catching for positional templates to maintain backward compatibility with DefaultLogMessageFormatter

All 66 logger tests pass, including 4 new EventFilter semantic logging tests and existing backward compatibility tests.

* test: Add semantic logging integration tests for log filtering

Added 8 comprehensive tests verifying that log filtering works correctly with semantic logging templates. Tests cover:

- Filtering by formatted message content with named properties
- Filtering by property values (e.g., {AlertLevel} = "CRITICAL")
- Multiple properties in single log message
- Positional templates with filtering (backward compatibility)
- Source filtering combined with semantic logging
- Format specifiers in templates (e.g., {Amount:N2})
- Messages that should pass through filters

All 25 log filter tests pass (17 existing + 8 new), confirming semantic logging integrates seamlessly with the log filtering system introduced in v1.5.21.

* fix: Update ConfigurationSpec to expect SemanticLogMessageFormatter as default

Updated the configuration validation test to expect SemanticLogMessageFormatter instead of DefaultLogMessageFormatter as the default logger formatter, matching the change made in commit f9a2d2c.

All 4 configuration tests pass.

* fix: enable nullable reference types in LogEventExtensions

- Added #nullable enable directive
- Marked 'properties' out parameter as nullable in TryGetProperties
- Ensures proper null safety for the semantic logging API

* test: Add semantic logging edge cases verification test

- Added ShouldHandleSemanticLogEdgeCases test to DefaultLogFormatSpec
- Tests named properties, positional properties, mixed types, null values,
  special characters, booleans, dates, and formatting alignment
- Reuses existing sanitization methods from DefaultLogFormatSpec
- Verifies semantic logging formatter output for various edge cases

* Update API Approval list

* Add new edge case unit tests (failing)

* docs: Add Message Templates spec reference to SemanticLogMessageFormatter

- Added link to https://messagetemplates.org/ specification
- Documented supported syntax (named/positional properties, format specifiers, alignment, escaped braces)
- Documented unsupported syntax (destructuring operators, empty property names)

* fix: Correct escaped brace handling in semantic logging per Message Templates spec

Parser fixes:
- Removed incorrect }} check after placeholder closing brace
- Parser now correctly extracts {UserId} from "{UserId}}" and "{{{UserId}}}"

Formatter fixes:
- Rewrote FormatNamedTemplate to handle }} in literal text correctly
- Added UnescapeBraces helper for templates with no placeholders
- "Use {{ and }}" now correctly produces "Use { and }"

Test updates:
- Updated {:N2} test to document as invalid per Message Templates spec
- Invalid templates have "garbage in, garbage out" behavior (not crashing)

Fixes edge cases reported in commit 1c58a6b.
All 34 semantic logging tests now pass.

* fix: Use culture-independent format specifiers in verify test

The ShouldHandleSemanticLogEdgeCases verify test was failing on CI due
to locale differences:
- {Amount:C} produces $123.45 on US locale but ¤123.45 on invariant
- DateTime.ToString() produces different formats per locale

Changed to culture-independent formats:
- Use ${Amount:F2} (literal $ + fixed-point number) instead of {Amount:C}
- Use {JoinDate:yyyy-MM-dd} (ISO 8601) for dates

* test: Add escaped brace benchmarks and .NET Framework verified file

- Added benchmark category for escaped brace handling to track
  performance of edge case fixes
- Added .Net.verified.txt baseline for .NET Framework 4.8 CI runs

* Add unit tests

* fix: Implement alignment specifiers and null ToString() handling in SemanticLogMessageFormatter

- Add support for alignment specifiers in named templates per Message Templates spec
  - Parse {Name,alignment:format} syntax correctly
  - Apply PadLeft() for positive alignment (right-align)
  - Apply PadRight() for negative alignment (left-align)

- Fix null handling when ToString() returns null
  - Check ToString() result before attempting format operations
  - Return "null" string instead of empty string for null ToString() results
  - Handles both plain and formatted property cases

- Fix test bug: missing '>' character in alignment test format string

These changes ensure the semantic logging formatter correctly implements the
Message Templates specification for alignment and handles defensive edge cases.

---------

Co-authored-by: Gregorius Soedharmo <[email protected]>

Author: Aaronontheweb

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

@@ -32,9 +32,9 @@ public DefaultLogFormatSpec() : base(CustomLoggerSetup())
     {
         _logger = (CustomLogger)Sys.Settings.StdoutLogger;
     }
-    
+
     private readonly CustomLogger _logger;
-    
+
     public class CustomLogger : StandardOutLogger
     {
         protected override void Log(object message)
@@ -44,13 +44,13 @@ protected override void Log(object message)
             {
                 _events.Add(e);
             }
-           
+
         }
-            
+
         private readonly ConcurrentBag<LogEvent> _events = new();
         public IReadOnlyCollection<LogEvent> Events => _events;
     }
-    
+
     public static ActorSystemSetup CustomLoggerSetup()
     {
         var hocon = @$"
@@ -115,6 +115,58 @@ await AwaitConditionAsync(() =>
         await Verifier.Verify(text);
     }
 
+    [Fact]
+    public async Task ShouldHandleSemanticLogEdgeCases()
+    {
+        // arrange
+        var filePath = Path.GetTempFileName();
+
+        // act
+        using (new OutputRedirector(filePath))
+        {
+            // Named properties
+            Sys.Log.Debug("User {UserId} logged in from {IpAddress}", 12345, "192.168.1.1");
+            Sys.Log.Info("Processing order {OrderId} for customer {CustomerId}", "ORD-001", "CUST-999");
+
+            // Positional properties (old style)
+            Sys.Log.Warning("Processing item {0} of {1}", 5, 10);
+
+            // Mixed types - use F2 instead of C for culture-independent output
+            Sys.Log.Info("Order total is ${Amount:F2} with {ItemCount} items", 123.45m, 3);
+
+            // Edge cases
+            Sys.Log.Debug("Empty template");
+            Sys.Log.Info("Single property {Value}", 42);
+            Sys.Log.Warning("Null value: {NullValue}", null);
+            Sys.Log.Error("Exception occurred for user {UserId}", 999);
+
+            // Special characters and escaping
+            Sys.Log.Debug("Path: {FilePath}, Size: {FileSize} bytes", @"C:\temp\file.txt", 1024);
+
+            // Boolean and date types - use explicit date format for culture-independent output
+            Sys.Log.Info("User {Username} is active: {IsActive}, joined on {JoinDate:yyyy-MM-dd}", "john.doe", true, DateTime.Parse("2024-01-15"));
+
+            // Long strings and alignment
+            Sys.Log.Debug("Request from {RemoteAddress} to endpoint {Endpoint} took {DurationMs}ms", "192.168.1.100:54321", "/api/v1/users", 250);
+
+            // force all logs to be received - wait for the last log message
+            await AwaitConditionAsync(() => Task.FromResult(_logger.Events.Any(e => e.Message.ToString()!.Contains("took 250ms"))), TimeSpan.FromSeconds(5));
+        }
+
+        // assert
+        // ReSharper disable once MethodHasAsyncOverload
+        var text = File.ReadAllText(filePath);
+
+        // need to sanitize the thread id and timestamps
+        text = SanitizeDateTime(text);
+        text = SanitizeThreadNumber(text);
+        text = SanitizeTestEventListener(text);
+        text = SanitizeDefaultLoggersStarted(text);
+        text = SanitizeCustomLoggerRemoved(text);
+
+        await Verifier.Verify(text);
+    }
+
     private static string SanitizeDefaultLoggersStarted(string logs)
     {
         var pattern = @"^.*Default Loggers started.*$\r?\n?";

src/core/Akka.API.Tests/LogFormatSpec.cs

@@ -3472,6 +3472,17 @@ namespace Akka.Event
         public abstract Akka.Event.LogLevel LogLevel();
         public override string ToString() { }
     }
+    [System.Runtime.CompilerServices.NullableAttribute(0)]
+    public class static LogEventExtensions
+    {
+        public static System.Collections.Generic.IEnumerable<object> GetParameters(this Akka.Event.LogEvent evt) { }
+        public static System.Collections.Generic.IReadOnlyList<string> GetPropertyNames(this Akka.Event.LogEvent evt) { }
+        public static string GetTemplate(this Akka.Event.LogEvent evt) { }
+        public static bool TryGetProperties(this Akka.Event.LogEvent evt, [System.Runtime.CompilerServices.NullableAttribute(new byte[] {
+                2,
+                1,
+                1})] out System.Collections.Generic.IReadOnlyDictionary<string, object> properties) { }
+    }
     public abstract class LogFilterBase : Akka.Actor.INoSerializationVerificationNeeded, Akka.Event.IDeadLetterSuppression
     {
         protected LogFilterBase() { }
@@ -3531,6 +3542,8 @@ namespace Akka.Event
         protected readonly Akka.Event.ILogMessageFormatter Formatter;
         public LogMessage(Akka.Event.ILogMessageFormatter formatter, string format) { }
         public string Format { get; }
+        public System.Collections.Generic.IReadOnlyList<string> PropertyNames { get; }
+        public System.Collections.Generic.IReadOnlyDictionary<string, object> GetProperties() { }
         [Akka.Annotations.InternalApiAttribute()]
         public abstract System.Collections.Generic.IEnumerable<object> Parameters();
         [Akka.Annotations.InternalApiAttribute()]
@@ -3708,6 +3721,12 @@ namespace Akka.Event
         public override Akka.Event.LogFilterType FilterType { get; }
         public override Akka.Event.LogFilterDecision ShouldKeepMessage(Akka.Event.LogEvent content, [System.Runtime.CompilerServices.NullableAttribute(2)] string expandedMessage = null) { }
     }
+    public sealed class SemanticLogMessageFormatter : Akka.Event.ILogMessageFormatter
+    {
+        public static readonly Akka.Event.SemanticLogMessageFormatter Instance;
+        public string Format(string format, params object[] args) { }
+        public string Format(string format, System.Collections.Generic.IEnumerable<object> args) { }
+    }
     public class StandardOutLogger : Akka.Event.MinimalLogger
     {
         public StandardOutLogger() { }

src/core/Akka.API.Tests/verify/CoreAPISpec.ApproveCore.DotNet.verified.txt

@@ -3483,6 +3483,17 @@ namespace Akka.Event
         public abstract Akka.Event.LogLevel LogLevel();
         public override string ToString() { }
     }
+    [System.Runtime.CompilerServices.NullableAttribute(0)]
+    public class static LogEventExtensions
+    {
+        public static System.Collections.Generic.IEnumerable<object> GetParameters(this Akka.Event.LogEvent evt) { }
+        public static System.Collections.Generic.IReadOnlyList<string> GetPropertyNames(this Akka.Event.LogEvent evt) { }
+        public static string GetTemplate(this Akka.Event.LogEvent evt) { }
+        public static bool TryGetProperties(this Akka.Event.LogEvent evt, [System.Runtime.CompilerServices.NullableAttribute(new byte[] {
+                2,
+                1,
+                1})] out System.Collections.Generic.IReadOnlyDictionary<string, object> properties) { }
+    }
     public abstract class LogFilterBase : Akka.Actor.INoSerializationVerificationNeeded, Akka.Event.IDeadLetterSuppression
     {
         protected LogFilterBase() { }
@@ -3542,6 +3553,8 @@ namespace Akka.Event
         protected readonly Akka.Event.ILogMessageFormatter Formatter;
         public LogMessage(Akka.Event.ILogMessageFormatter formatter, string format) { }
         public string Format { get; }
+        public System.Collections.Generic.IReadOnlyList<string> PropertyNames { get; }
+        public System.Collections.Generic.IReadOnlyDictionary<string, object> GetProperties() { }
         [Akka.Annotations.InternalApiAttribute()]
         public abstract System.Collections.Generic.IEnumerable<object> Parameters();
         [Akka.Annotations.InternalApiAttribute()]
@@ -3717,6 +3730,12 @@ namespace Akka.Event
         public override Akka.Event.LogFilterType FilterType { get; }
         public override Akka.Event.LogFilterDecision ShouldKeepMessage(Akka.Event.LogEvent content, [System.Runtime.CompilerServices.NullableAttribute(2)] string expandedMessage = null) { }
     }
+    public sealed class SemanticLogMessageFormatter : Akka.Event.ILogMessageFormatter
+    {
+        public static readonly Akka.Event.SemanticLogMessageFormatter Instance;
+        public string Format(string format, params object[] args) { }
+        public string Format(string format, System.Collections.Generic.IEnumerable<object> args) { }
+    }
     public class StandardOutLogger : Akka.Event.MinimalLogger
     {
         public StandardOutLogger() { }

src/core/Akka.API.Tests/verify/CoreAPISpec.ApproveCore.Net.verified.txt

@@ -0,0 +1,11 @@
+[DEBUG][DateTime][Thread 0001][ActorSystem(test)] User 12345 logged in from 192.168.1.1
+[INFO][DateTime][Thread 0001][ActorSystem(test)] Processing order ORD-001 for customer CUST-999
+[WARNING][DateTime][Thread 0001][ActorSystem(test)] Processing item 5 of 10
+[INFO][DateTime][Thread 0001][ActorSystem(test)] Order total is $123.45 with 3 items
+[DEBUG][DateTime][Thread 0001][ActorSystem(test)] Empty template
+[INFO][DateTime][Thread 0001][ActorSystem(test)] Single property 42
+[WARNING][DateTime][Thread 0001][ActorSystem(test)] Null value: {NullValue}
+[ERROR][DateTime][Thread 0001][ActorSystem(test)] Exception occurred for user 999
+[DEBUG][DateTime][Thread 0001][ActorSystem(test)] Path: C:\temp\file.txt, Size: 1024 bytes
+[INFO][DateTime][Thread 0001][ActorSystem(test)] User john.doe is active: True, joined on 2024-01-15
+[DEBUG][DateTime][Thread 0001][ActorSystem(test)] Request from 192.168.1.100:54321 to endpoint /api/v1/users took 250ms

src/core/Akka.API.Tests/verify/DefaultLogFormatSpec.ShouldHandleSemanticLogEdgeCases.DotNet.verified.txt

@@ -0,0 +1,11 @@
+[DEBUG][DateTime][Thread 0001][ActorSystem(test)] User 12345 logged in from 192.168.1.1
+[INFO][DateTime][Thread 0001][ActorSystem(test)] Processing order ORD-001 for customer CUST-999
+[WARNING][DateTime][Thread 0001][ActorSystem(test)] Processing item 5 of 10
+[INFO][DateTime][Thread 0001][ActorSystem(test)] Order total is $123.45 with 3 items
+[DEBUG][DateTime][Thread 0001][ActorSystem(test)] Empty template
+[INFO][DateTime][Thread 0001][ActorSystem(test)] Single property 42
+[WARNING][DateTime][Thread 0001][ActorSystem(test)] Null value: {NullValue}
+[ERROR][DateTime][Thread 0001][ActorSystem(test)] Exception occurred for user 999
+[DEBUG][DateTime][Thread 0001][ActorSystem(test)] Path: C:\temp\file.txt, Size: 1024 bytes
+[INFO][DateTime][Thread 0001][ActorSystem(test)] User john.doe is active: True, joined on 2024-01-15
+[DEBUG][DateTime][Thread 0001][ActorSystem(test)] Request from 192.168.1.100:54321 to endpoint /api/v1/users took 250ms

src/core/Akka.API.Tests/verify/DefaultLogFormatSpec.ShouldHandleSemanticLogEdgeCases.Net.verified.txt

@@ -87,8 +87,26 @@ protected virtual void OnEventMatched(LogEvent logEvent)
     /// <returns>TBD</returns>
     protected bool InternalDoMatch(string src, object? msg)
     {
+        // Check source matcher first (fast path)
+        if (!_sourceMatcher.IsMatch(src))
+            return false;
+
+        // For semantic logging support, try matching against both the formatted message
+        // and the unformatted template pattern
+        if (msg is LogMessage logMessage)
+        {
+            // Try matching against the template pattern first (e.g., "User {UserId} logged in")
+            if (_messageMatcher.IsMatch(logMessage.Format))
+                return true;
+
+            // Fall back to matching the formatted message (e.g., "User 12345 logged in")
+            var formattedMsg = logMessage.ToString() ?? "null";
+            return _messageMatcher.IsMatch(formattedMsg);
+        }
+
+        // Non-semantic logging or legacy messages
         var msgstr = msg == null ? "null" : msg.ToString() ?? "null";
-        return _sourceMatcher.IsMatch(src) && _messageMatcher.IsMatch(msgstr);
+        return _messageMatcher.IsMatch(msgstr);
     }
 
     /// <summary>

src/core/Akka.TestKit/EventFilter/Internal/EventFilterBase.cs

@@ -50,7 +50,7 @@ public void The_default_configuration_file_contain_all_configuration_properties(
             settings.LogDeadLetters.ShouldBe(10);
             settings.LogDeadLettersDuringShutdown.ShouldBeFalse();
             settings.LogDeadLettersSuspendDuration.ShouldBe(TimeSpan.FromMinutes(5));
-            settings.LogFormatter.Should().BeOfType<DefaultLogMessageFormatter>();
+            settings.LogFormatter.Should().BeOfType<SemanticLogMessageFormatter>();
 
             settings.ProviderClass.ShouldBe(typeof (LocalActorRefProvider).FullName);
             settings.SupervisorStrategyClass.ShouldBe(typeof (DefaultSupervisorStrategy).FullName);