Introduce new extended logging model.

- Replace the OpenTelemetry-specific logger design with a
LoggerFactory-based approach independent of OpenTelemetry. This
delivers enrichment and redaction to all ILogger users.

The basic idea is that the code generator will no longer be responsible
for doing redaction. Instead, the generated code will accumulate
normal properties in one collection and will accumulate classified
properties in a different collection.

Within the Logger type, the classified properties are run through
redaction and added to the normal property list. This list is then
used to enrich into. And then the final thing is given to the set of
currently registered ILogger instances in the system. So all these
loggers get redacted and enriched state.

This separates static vs. dynamic log enrichment. The idea is to
reduce overhead for stuff that never changes. Thus, we have the new
IStaticLogEnricher type.

We now support structured logging as a first class concept using the
new StructuredLog extension methods around ILogger.

NOTES:

- The idea is that the customer should call AddExtendedLogging
instead of AddLogging. By virtue of using this call, they'll also
be using the newer code generator which will take advantage of the
new features.

- This PR doesn't currently include updated tests, that's coming next
after we validate the general approach.

- This PR doesn't currently include an updated logging code generator
that will take advantage of this new functionality.

- Right now, if a user calls AddLogging after they had already called
AddExtendedLogging, this will undo the extended logging stuff and leave
the system in classic mode. We need to find a strategy to deal with
this.

Author: Martin Taillefer

src/Libraries/Microsoft.Extensions.Telemetry.Abstractions/Enrichment/EnricherExtensions.cs

@@ -2,6 +2,7 @@
 // The .NET Foundation licenses this file to you under the MIT license.
 
 using System;
+using System.Diagnostics.CodeAnalysis;
 using Microsoft.Extensions.DependencyInjection;
 using Microsoft.Shared.Diagnostics;
 
@@ -42,6 +43,38 @@ public static IServiceCollection AddLogEnricher(this IServiceCollection services
         return services.AddSingleton(enricher);
     }
 
+    /// <summary>
+    /// Registers a static log enricher type.
+    /// </summary>
+    /// <param name="services">The dependency injection container to add the enricher type to.</param>
+    /// <typeparam name="T">Enricher type.</typeparam>
+    /// <returns>The value of <paramref name="services"/>.</returns>
+    /// <exception cref="ArgumentNullException"><paramref name="services"/> is <see langword="null"/>.</exception>
+    [Experimental]
+    public static IServiceCollection AddStaticLogEnricher<T>(this IServiceCollection services)
+        where T : class, IStaticLogEnricher
+    {
+        _ = Throw.IfNull(services);
+
+        return services.AddSingleton<IStaticLogEnricher, T>();
+    }
+
+    /// <summary>
+    /// Registers a static log enricher instance.
+    /// </summary>
+    /// <param name="services">The dependency injection container to add the enricher instance to.</param>
+    /// <param name="enricher">The enricher instance to add.</param>
+    /// <returns>The value of <paramref name="services"/>.</returns>
+    /// <exception cref="ArgumentNullException"><paramref name="services"/> or <paramref name="enricher"/> are <see langword="null"/>.</exception>
+    [Experimental]
+    public static IServiceCollection AddStaticLogEnricher(this IServiceCollection services, IStaticLogEnricher enricher)
+    {
+        _ = Throw.IfNull(services);
+        _ = Throw.IfNull(enricher);
+
+        return services.AddSingleton(enricher);
+    }
+
     /// <summary>
     /// Registers a metric enricher type.
     /// </summary>

src/Libraries/Microsoft.Extensions.Telemetry.Abstractions/Enrichment/IStaticLogEnricher.cs

@@ -0,0 +1,19 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System.Diagnostics.CodeAnalysis;
+
+namespace Microsoft.Extensions.Telemetry.Enrichment;
+
+/// <summary>
+/// A component that augments log records with additional properties which are unchanging over the life of the object.
+/// </summary>
+[Experimental]
+public interface IStaticLogEnricher
+{
+    /// <summary>
+    /// Called to generate properties for a log record.
+    /// </summary>
+    /// <param name="bag">Where the enricher puts the properties it is producing.</param>
+    void Enrich(IEnrichmentPropertyBag bag);
+}

src/Libraries/Microsoft.Extensions.Telemetry.Abstractions/Logging/ILogPropertyCollector.cs

@@ -2,6 +2,8 @@
 // The .NET Foundation licenses this file to you under the MIT license.
 
 using System;
+using System.Diagnostics.CodeAnalysis;
+using Microsoft.Extensions.Compliance.Classification;
 
 namespace Microsoft.Extensions.Telemetry.Logging;
 
@@ -23,4 +25,17 @@ public interface ILogPropertyCollector
     /// or when a property of the same name has already been added.
     /// </exception>
     void Add(string propertyName, object? propertyValue);
+
+    /// <summary>
+    /// Adds a property to the current log record.
+    /// </summary>
+    /// <param name="propertyName">The name of the property to add.</param>
+    /// <param name="propertyValue">The value of the property to add.</param>
+    /// <param name="classification">The data classification of the property value.</param>
+    /// <exception cref="ArgumentNullException"><paramref name="propertyName"/> is <see langword="null"/>.</exception>
+    /// <exception cref="ArgumentException"><paramref name="propertyName" /> is empty or contains exclusively whitespace,
+    /// or when a property of the same name has already been added.
+    /// </exception>
+    [Experimental]
+    void Add(string propertyName, object? propertyValue, DataClassification classification);
 }

src/Libraries/Microsoft.Extensions.Telemetry.Abstractions/Logging/LogMethodHelper.cs

@@ -6,6 +6,7 @@
 using System.Collections.Generic;
 using System.ComponentModel;
 using System.Diagnostics.CodeAnalysis;
+using Microsoft.Extensions.Compliance.Classification;
 #if NET6_0_OR_GREATER
 using Microsoft.Extensions.Logging;
 #endif
@@ -37,6 +38,10 @@ public void Add(string propertyName, object? propertyValue)
         Add(new KeyValuePair<string, object?>(fullName, propertyValue));
     }
 
+    /// <inheritdoc/>
+    [Experimental]
+    public void Add(string propertyName, object? propertyValue, DataClassification classification) => Add(propertyName, propertyValue);
+
     /// <summary>
     /// Resets state of this container as described in <see cref="IResettable.TryReset"/>.
     /// </summary>

src/Libraries/Microsoft.Extensions.Telemetry.Abstractions/Logging/LoggerExtensions.cs

@@ -0,0 +1,41 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System;
+using System.Diagnostics.CodeAnalysis;
+using Microsoft.Extensions.Logging;
+using Microsoft.Shared.Diagnostics;
+
+namespace Microsoft.Extensions.Telemetry.Logging;
+
+/// <summary>
+/// Extensions for <see cref="ILogger"/>.
+/// </summary>
+[Experimental]
+public static class LoggerExtensions
+{
+    /// <summary>
+    /// Emits a structured log entry.
+    /// </summary>
+    /// <param name="logger">The logger to emit the log entry to.</param>
+    /// <param name="logLevel">Entry will be written on this level.</param>
+    /// <param name="eventId">Id of the event.</param>
+    /// <param name="properties">The set of name/value pairs to log with this entry.</param>
+    public static void StructuredLog(this ILogger logger, LogLevel logLevel, EventId eventId, LoggerMessageProperties properties)
+    {
+        Throw.IfNull(logger).Log<LoggerMessageProperties>(logLevel, eventId, properties, null, (_, _) => string.Empty);
+    }
+
+    /// <summary>
+    /// Emits a structured log entry.
+    /// </summary>
+    /// <param name="logger">The logger to emit the log entry to.</param>
+    /// <param name="logLevel">Entry will be written on this level.</param>
+    /// <param name="eventId">Id of the event.</param>
+    /// <param name="properties">The set of name/value pairs to log with this entry.</param>
+    /// <param name="exception">The exception related to this entry.</param>
+    public static void StructuredLog(this ILogger logger, LogLevel logLevel, EventId eventId, LoggerMessageProperties properties, Exception? exception)
+    {
+        Throw.IfNull(logger).Log<LoggerMessageProperties>(logLevel, eventId, properties, exception, (_, _) => string.Empty);
+    }
+}

src/Libraries/Microsoft.Extensions.Telemetry.Abstractions/Logging/LoggerMessageHelper.cs

@@ -0,0 +1,133 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System;
+using System.Collections;
+using System.Collections.Generic;
+using System.ComponentModel;
+using System.Diagnostics.CodeAnalysis;
+using Microsoft.Extensions.ObjectPool;
+using Microsoft.Shared.Pools;
+
+namespace Microsoft.Extensions.Telemetry.Logging;
+
+/// <summary>
+/// Utility type to support generated logging methods.
+/// </summary>
+[EditorBrowsable(EditorBrowsableState.Never)]
+[Experimental]
+public static class LoggerMessageHelper
+{
+    [ThreadStatic]
+    private static LoggerMessageProperties? _properties;
+
+    /// <summary>
+    /// Gets a thread-local instance of this type.
+    /// </summary>
+    public static LoggerMessageProperties ThreadStaticLoggerMessageProperties
+    {
+        get
+        {
+            _properties ??= new();
+            _ = _properties.TryReset();
+            return _properties;
+        }
+    }
+
+    /// <summary>
+    /// Enumerates an enumerable into a string.
+    /// </summary>
+    /// <param name="enumerable">The enumerable object.</param>
+    /// <returns>
+    /// A string representation of the enumerable.
+    /// </returns>
+    public static string Stringify(IEnumerable? enumerable)
+    {
+        if (enumerable == null)
+        {
+            return "null";
+        }
+
+        var sb = PoolFactory.SharedStringBuilderPool.Get();
+        _ = sb.Append('[');
+
+        bool first = true;
+        foreach (object? e in enumerable)
+        {
+            if (!first)
+            {
+                _ = sb.Append(',');
+            }
+
+            if (e == null)
+            {
+                _ = sb.Append("null");
+            }
+            else
+            {
+                _ = sb.Append(FormattableString.Invariant($"\"{e}\""));
+            }
+
+            first = false;
+        }
+
+        _ = sb.Append(']');
+        var result = sb.ToString();
+        PoolFactory.SharedStringBuilderPool.Return(sb);
+        return result;
+    }
+
+    /// <summary>
+    /// Enumerates an enumerable of key/value pairs into a string.
+    /// </summary>
+    /// <typeparam name="TKey">Type of keys.</typeparam>
+    /// <typeparam name="TValue">Type of values.</typeparam>
+    /// <param name="enumerable">The enumerable object.</param>
+    /// <returns>
+    /// A string representation of the enumerable.
+    /// </returns>
+    public static string Stringify<TKey, TValue>(IEnumerable<KeyValuePair<TKey, TValue>>? enumerable)
+    {
+        if (enumerable == null)
+        {
+            return "null";
+        }
+
+        var sb = PoolFactory.SharedStringBuilderPool.Get();
+        _ = sb.Append('{');
+
+        bool first = true;
+        foreach (var kvp in enumerable)
+        {
+            if (!first)
+            {
+                _ = sb.Append(',');
+            }
+
+            if (typeof(TKey).IsValueType || kvp.Key is not null)
+            {
+                _ = sb.Append(FormattableString.Invariant($"\"{kvp.Key}\"="));
+            }
+            else
+            {
+                _ = sb.Append("null=");
+            }
+
+            if (typeof(TValue).IsValueType || kvp.Value is not null)
+            {
+                _ = sb.Append(FormattableString.Invariant($"\"{kvp.Value}\""));
+            }
+            else
+            {
+                _ = sb.Append("null");
+            }
+
+            first = false;
+        }
+
+        _ = sb.Append('}');
+        var result = sb.ToString();
+        PoolFactory.SharedStringBuilderPool.Return(sb);
+        return result;
+    }
+}

src/Libraries/Microsoft.Extensions.Telemetry.Abstractions/Logging/LoggerMessageProperties.ClassifiedProperty.cs

@@ -0,0 +1,45 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System.ComponentModel;
+using System.Diagnostics.CodeAnalysis;
+using Microsoft.Extensions.Compliance.Classification;
+
+namespace Microsoft.Extensions.Telemetry.Logging;
+
+public partial class LoggerMessageProperties
+{
+    /// <summary>
+    /// Represents a captured property that needs redaction.
+    /// </summary>
+    [SuppressMessage("Design", "CA1034:Nested types should not be visible", Justification = "Not for customer use and hidden from docs")]
+    [SuppressMessage("Performance", "CA1815:Override equals and operator equals on value types", Justification = "Not needed")]
+    [EditorBrowsable(EditorBrowsableState.Never)]
+    public readonly struct ClassifiedProperty
+    {
+        /// <summary>
+        /// Gets the name of the property.
+        /// </summary>
+        public readonly string Name { get; }
+
+        /// <summary>
+        /// Gets the property's value.
+        /// </summary>
+        public readonly object? Value { get; }
+
+        /// <summary>
+        /// Gets the property's data classification.
+        /// </summary>
+        public readonly DataClassification Classification { get; }
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="ClassifiedProperty"/> struct.
+        /// </summary>
+        public ClassifiedProperty(string name, object? value, DataClassification classification)
+        {
+            Name = name;
+            Value = value;
+            Classification = classification;
+        }
+    }
+}

src/Libraries/Microsoft.Extensions.Telemetry.Abstractions/Logging/LoggerMessageProperties.PropertyBag.cs

@@ -0,0 +1,53 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System;
+using System.Collections.Generic;
+using Microsoft.Extensions.Telemetry.Enrichment;
+
+namespace Microsoft.Extensions.Telemetry.Logging;
+
+public partial class LoggerMessageProperties
+{
+    private sealed class PropertyBag : IEnrichmentPropertyBag
+    {
+        private readonly List<KeyValuePair<string, object?>> _properties;
+
+        public PropertyBag(List<KeyValuePair<string, object?>> properties)
+        {
+            _properties = properties;
+        }
+
+        void IEnrichmentPropertyBag.Add(string key, object value)
+        {
+            _properties.Add(new KeyValuePair<string, object?>(key, value));
+        }
+
+        /// <inheritdoc/>
+        void IEnrichmentPropertyBag.Add(string key, string value)
+        {
+            _properties.Add(new KeyValuePair<string, object?>(key, value));
+        }
+
+        /// <inheritdoc/>
+        void IEnrichmentPropertyBag.Add(ReadOnlySpan<KeyValuePair<string, object>> properties)
+        {
+            foreach (var p in properties)
+            {
+                // we're going from KVP<string, object> to KVP<string, object?> which is strictly correct, so ignore the complaint
+#pragma warning disable CS8620 // Argument cannot be used for parameter due to differences in the nullability of reference types.
+                _properties.Add(p);
+#pragma warning restore CS8620 // Argument cannot be used for parameter due to differences in the nullability of reference types.
+            }
+        }
+
+        /// <inheritdoc/>
+        void IEnrichmentPropertyBag.Add(ReadOnlySpan<KeyValuePair<string, string>> properties)
+        {
+            foreach (var p in properties)
+            {
+                _properties.Add(new KeyValuePair<string, object?>(p.Key, p.Value));
+            }
+        }
+    }
+}