Deprecate AddServiceLogEnricher method with its overloads, introduce replacements (#6529)

Author: evgenyfedorov2

docs/list-of-diagnostics.md

@@ -51,6 +51,7 @@ You may continue using obsolete APIs in your application, but we advise explorin
 | Diagnostic ID     | Description |
 | :---------------- | :---------- |
 | `EXTOBS0001` | This API is obsolete and will be removed in a future version. Consider using [Resource Monitoring observable instruments](https://learn.microsoft.com/dotnet/core/diagnostics/built-in-metrics-diagnostics#microsoftextensionsdiagnosticsresourcemonitoring). |
+| `EXTOBS0002` | This API is obsolete and will be removed in a future version. Instead of the AddServiceLogEnricher() methods, consider using the respective AddApplicationLogEnricher() methods.                                                                              |
 
 # LoggerMessage
 

src/Libraries/Microsoft.Extensions.Telemetry/Enrichment/ApplicationEnricherServiceCollectionExtensions.cs

@@ -4,6 +4,7 @@
 using System;
 using Microsoft.Extensions.Configuration;
 using Microsoft.Extensions.Diagnostics.Enrichment;
+using Microsoft.Shared.DiagnosticIds;
 using Microsoft.Shared.Diagnostics;
 
 namespace Microsoft.Extensions.DependencyInjection;
@@ -19,22 +20,63 @@ public static class ApplicationEnricherServiceCollectionExtensions
     /// <param name="services">The <see cref="IServiceCollection"/> to add the service enricher to.</param>
     /// <returns>The value of <paramref name="services"/>.</returns>
     /// <exception cref="ArgumentNullException"><paramref name="services"/> is <see langword="null"/>.</exception>
-    public static IServiceCollection AddServiceLogEnricher(this IServiceCollection services)
+    [Obsolete(
+        DiagnosticIds.Obsoletions.ObsoleteTelemetryApiMessage,
+        DiagnosticId = DiagnosticIds.Obsoletions.ObsoleteTelemetryApiDiagId,
+        UrlFormat = DiagnosticIds.UrlFormat)]
+    public static IServiceCollection AddServiceLogEnricher(this IServiceCollection services) =>
+        services.AddApplicationLogEnricher(_ => { });
+
+    /// <summary>
+    /// Adds an instance of the service enricher to the <see cref="IServiceCollection"/>.
+    /// </summary>
+    /// <param name="services">The <see cref="IServiceCollection"/> to add the service enricher to.</param>
+    /// <param name="configure">The <see cref="ApplicationLogEnricherOptions"/> configuration delegate.</param>
+    /// <returns>The value of <paramref name="services"/>.</returns>
+    /// <exception cref="ArgumentNullException">Any of the arguments is <see langword="null"/>.</exception>
+    [Obsolete(
+        DiagnosticIds.Obsoletions.ObsoleteTelemetryApiMessage,
+        DiagnosticId = DiagnosticIds.Obsoletions.ObsoleteTelemetryApiDiagId,
+        UrlFormat = DiagnosticIds.UrlFormat)]
+    public static IServiceCollection AddServiceLogEnricher(this IServiceCollection services, Action<ApplicationLogEnricherOptions> configure) =>
+        services.AddApplicationLogEnricher(configure);
+
+    /// <summary>
+    /// Adds an instance of the service enricher to the <see cref="IServiceCollection"/>.
+    /// </summary>
+    /// <param name="services">The <see cref="IServiceCollection"/> to add the service enricher to.</param>
+    /// <param name="section">The <see cref="IConfigurationSection"/> to use for configuring <see cref="ApplicationLogEnricherOptions"/> in the service enricher.</param>
+    /// <returns>The value of <paramref name="services"/>.</returns>
+    /// <exception cref="ArgumentNullException">Any of the arguments is <see langword="null"/>.</exception>
+    [Obsolete(
+        DiagnosticIds.Obsoletions.ObsoleteTelemetryApiMessage,
+        DiagnosticId = DiagnosticIds.Obsoletions.ObsoleteTelemetryApiDiagId,
+        UrlFormat = DiagnosticIds.UrlFormat)]
+    public static IServiceCollection AddServiceLogEnricher(this IServiceCollection services, IConfigurationSection section) =>
+        services.AddApplicationLogEnricher(section);
+
+    /// <summary>
+    /// Adds an instance of the application enricher to the <see cref="IServiceCollection"/>.
+    /// </summary>
+    /// <param name="services">The <see cref="IServiceCollection"/> to add the application enricher to.</param>
+    /// <returns>The value of <paramref name="services"/>.</returns>
+    /// <exception cref="ArgumentNullException"><paramref name="services"/> is <see langword="null"/>.</exception>
+    public static IServiceCollection AddApplicationLogEnricher(this IServiceCollection services)
     {
         _ = Throw.IfNull(services);
 
         return services
-            .AddServiceLogEnricher(_ => { });
+            .AddApplicationLogEnricher(_ => { });
     }
 
     /// <summary>
-    /// Adds an instance of the service enricher to the <see cref="IServiceCollection"/>.
+    /// Adds an instance of the application enricher to the <see cref="IServiceCollection"/>.
     /// </summary>
-    /// <param name="services">The <see cref="IServiceCollection"/> to add the service enricher to.</param>
+    /// <param name="services">The <see cref="IServiceCollection"/> to add the application enricher to.</param>
     /// <param name="configure">The <see cref="ApplicationLogEnricherOptions"/> configuration delegate.</param>
     /// <returns>The value of <paramref name="services"/>.</returns>
     /// <exception cref="ArgumentNullException">Any of the arguments is <see langword="null"/>.</exception>
-    public static IServiceCollection AddServiceLogEnricher(this IServiceCollection services, Action<ApplicationLogEnricherOptions> configure)
+    public static IServiceCollection AddApplicationLogEnricher(this IServiceCollection services, Action<ApplicationLogEnricherOptions> configure)
     {
         _ = Throw.IfNull(services);
         _ = Throw.IfNull(configure);
@@ -45,13 +87,13 @@ public static IServiceCollection AddServiceLogEnricher(this IServiceCollection s
     }
 
     /// <summary>
-    /// Adds an instance of the service enricher to the <see cref="IServiceCollection"/>.
+    /// Adds an instance of the application enricher to the <see cref="IServiceCollection"/>.
     /// </summary>
-    /// <param name="services">The <see cref="IServiceCollection"/> to add the service enricher to.</param>
-    /// <param name="section">The <see cref="IConfigurationSection"/> to use for configuring <see cref="ApplicationLogEnricherOptions"/> in the service enricher.</param>
+    /// <param name="services">The <see cref="IServiceCollection"/> to add the application enricher to.</param>
+    /// <param name="section">The <see cref="IConfigurationSection"/> to use for configuring <see cref="ApplicationLogEnricherOptions"/> in the application enricher.</param>
     /// <returns>The value of <paramref name="services"/>.</returns>
     /// <exception cref="ArgumentNullException">Any of the arguments is <see langword="null"/>.</exception>
-    public static IServiceCollection AddServiceLogEnricher(this IServiceCollection services, IConfigurationSection section)
+    public static IServiceCollection AddApplicationLogEnricher(this IServiceCollection services, IConfigurationSection section)
     {
         _ = Throw.IfNull(services);
         _ = Throw.IfNull(section);

src/Libraries/Microsoft.Extensions.Telemetry/Enrichment/ApplicationLogEnricherOptions.cs

@@ -6,7 +6,7 @@
 namespace Microsoft.Extensions.Diagnostics.Enrichment;
 
 /// <summary>
-/// Options for the service log enricher.
+/// Options for the application log enricher.
 /// </summary>
 public class ApplicationLogEnricherOptions
 {

src/Libraries/Microsoft.Extensions.Telemetry/Microsoft.Extensions.Telemetry.csproj

@@ -6,6 +6,8 @@
     <Workstream>Telemetry</Workstream>
     <!-- disable "Published symbols cannot be deleted to maintain compatibility" because we have different APIs for different TFMs -->
     <NoWarn Condition="!$([MSBuild]::IsTargetFrameworkCompatible('$(TargetFramework)', 'net9.0'))">$(NoWarn);LA0006</NoWarn>
+    <!-- disable "CS0436: Type conflicts with imported type" for the ObsoleteAttribute class in netstandard2.0 and net462" -->
+    <NoWarn Condition="!$([MSBuild]::IsTargetFrameworkCompatible('$(TargetFramework)', 'net8.0'))">$(NoWarn);CS0436</NoWarn>
   </PropertyGroup>
 
   <PropertyGroup>
@@ -20,6 +22,7 @@
     <InjectSharedNumericExtensions>true</InjectSharedNumericExtensions>
     <InjectSharedPools>true</InjectSharedPools>
     <InjectSharedRentedSpan>true</InjectSharedRentedSpan>
+    <InjectObsoleteAttributeOnLegacy>true</InjectObsoleteAttributeOnLegacy>
     <EnableConfigurationBindingGenerator>true</EnableConfigurationBindingGenerator>
     <UseLoggingGenerator>true</UseLoggingGenerator>
 </PropertyGroup>

src/Libraries/Microsoft.Extensions.Telemetry/Microsoft.Extensions.Telemetry.json

@@ -1,21 +1,33 @@
 {
-  "Name": "Microsoft.Extensions.Telemetry, Version=9.7.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35",
+  "Name": "Microsoft.Extensions.Telemetry, Version=10.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35",
   "Types": [
     {
       "Type": "static class Microsoft.Extensions.DependencyInjection.ApplicationEnricherServiceCollectionExtensions",
       "Stage": "Stable",
       "Methods": [
         {
-          "Member": "static Microsoft.Extensions.DependencyInjection.IServiceCollection Microsoft.Extensions.DependencyInjection.ApplicationEnricherServiceCollectionExtensions.AddServiceLogEnricher(this Microsoft.Extensions.DependencyInjection.IServiceCollection services);",
+          "Member": "static Microsoft.Extensions.DependencyInjection.IServiceCollection Microsoft.Extensions.DependencyInjection.ApplicationEnricherServiceCollectionExtensions.AddApplicationLogEnricher(this Microsoft.Extensions.DependencyInjection.IServiceCollection services);",
           "Stage": "Stable"
         },
         {
-          "Member": "static Microsoft.Extensions.DependencyInjection.IServiceCollection Microsoft.Extensions.DependencyInjection.ApplicationEnricherServiceCollectionExtensions.AddServiceLogEnricher(this Microsoft.Extensions.DependencyInjection.IServiceCollection services, System.Action<Microsoft.Extensions.Diagnostics.Enrichment.ApplicationLogEnricherOptions> configure);",
+          "Member": "static Microsoft.Extensions.DependencyInjection.IServiceCollection Microsoft.Extensions.DependencyInjection.ApplicationEnricherServiceCollectionExtensions.AddApplicationLogEnricher(this Microsoft.Extensions.DependencyInjection.IServiceCollection services, System.Action<Microsoft.Extensions.Diagnostics.Enrichment.ApplicationLogEnricherOptions> configure);",
           "Stage": "Stable"
         },
         {
-          "Member": "static Microsoft.Extensions.DependencyInjection.IServiceCollection Microsoft.Extensions.DependencyInjection.ApplicationEnricherServiceCollectionExtensions.AddServiceLogEnricher(this Microsoft.Extensions.DependencyInjection.IServiceCollection services, Microsoft.Extensions.Configuration.IConfigurationSection section);",
+          "Member": "static Microsoft.Extensions.DependencyInjection.IServiceCollection Microsoft.Extensions.DependencyInjection.ApplicationEnricherServiceCollectionExtensions.AddApplicationLogEnricher(this Microsoft.Extensions.DependencyInjection.IServiceCollection services, Microsoft.Extensions.Configuration.IConfigurationSection section);",
           "Stage": "Stable"
+        },
+        {
+          "Member": "static Microsoft.Extensions.DependencyInjection.IServiceCollection Microsoft.Extensions.DependencyInjection.ApplicationEnricherServiceCollectionExtensions.AddServiceLogEnricher(this Microsoft.Extensions.DependencyInjection.IServiceCollection services);",
+          "Stage": "Obsolete"
+        },
+        {
+          "Member": "static Microsoft.Extensions.DependencyInjection.IServiceCollection Microsoft.Extensions.DependencyInjection.ApplicationEnricherServiceCollectionExtensions.AddServiceLogEnricher(this Microsoft.Extensions.DependencyInjection.IServiceCollection services, System.Action<Microsoft.Extensions.Diagnostics.Enrichment.ApplicationLogEnricherOptions> configure);",
+          "Stage": "Obsolete"
+        },
+        {
+          "Member": "static Microsoft.Extensions.DependencyInjection.IServiceCollection Microsoft.Extensions.DependencyInjection.ApplicationEnricherServiceCollectionExtensions.AddServiceLogEnricher(this Microsoft.Extensions.DependencyInjection.IServiceCollection services, Microsoft.Extensions.Configuration.IConfigurationSection section);",
+          "Stage": "Obsolete"
         }
       ]
     },

src/Libraries/Microsoft.Extensions.Telemetry/README.md

@@ -126,16 +126,16 @@ revisited in future. Namely, this library uses `Microsoft.Extensions.Logging.Abs
 - `Microsoft.Extensions.Logging.Abstractions.BufferedLogRecord.ManagedThreadId`
 - `Microsoft.Extensions.Logging.Abstractions.BufferedLogRecord.MessageTemplate`
 
-### Service Log Enrichment
+### Application Log Enrichment
 
-Enriches logs with application-specific information based on `ApplicationMetadata` information. The bellow calls will add the service log enricher to the service collection.
+Enriches logs with application-specific information based on `ApplicationMetadata` information. The bellow calls will add the application log enricher to the service collection.
 
 ```csharp
 // Add service log enricher with default settings
-builder.Services.AddServiceLogEnricher();
+builder.Services.AddApplicationLogEnricher();
 
 // Or configure with options
-builder.Services.AddServiceLogEnricher(options =>
+builder.Services.AddApplicationLogEnricher(options =>
 {
     options.ApplicationName = true;
     options.BuildVersion = true;
@@ -197,7 +197,7 @@ builder.Logging.EnableEnrichment(options =>
     options.UseFileInfoForStackTraces = true;
 });
 
-builder.Services.AddServiceLogEnricher(); // <- This call is required in order for the enricher to be added into the service collection.
+builder.Services.AddApplicationLogEnricher(); // <- This call is required in order for the enricher to be added into the service collection.
 
 // Enable log redaction
 builder.Logging.EnableRedaction(options =>

src/Shared/DiagnosticIds/DiagnosticIds.cs

@@ -123,7 +123,11 @@ internal static class AuditReports
     internal static class Obsoletions
     {
         internal const string NonObservableResourceMonitoringApiDiagId = "EXTOBS0001";
-        internal const string NonObservableResourceMonitoringApiMessage = "This API is obsolete and will be removed in a future version. Consider using Resource Monitoring observable instruments.";
+        internal const string ObsoleteTelemetryApiDiagId = "EXTOBS0002";
+        internal const string NonObservableResourceMonitoringApiMessage =
+            "This API is obsolete and will be removed in a future version. Consider using Resource Monitoring observable instruments.";
+        internal const string ObsoleteTelemetryApiMessage =
+            "This API is obsolete and will be removed in a future version. Instead of the AddServiceLogEnricher() methods, consider using the respective AddApplicationLogEnricher() methods.";
     }
 }
 

test/Libraries/Microsoft.Extensions.Telemetry.Tests/Enrichment/ApplicationEnricherExtensionsTests.cs

@@ -18,24 +18,24 @@ public class ApplicationEnricherExtensionsTests
     public void ServiceLogEnricher_GivenAnyNullArgument_Throws()
     {
         Assert.Throws<ArgumentNullException>(() =>
-            ((IServiceCollection)null!).AddServiceLogEnricher());
+            ((IServiceCollection)null!).AddApplicationLogEnricher());
 
         Assert.Throws<ArgumentNullException>(() =>
-            ((IServiceCollection)null!).AddServiceLogEnricher(_ => { }));
+            ((IServiceCollection)null!).AddApplicationLogEnricher(_ => { }));
 
         Assert.Throws<ArgumentNullException>(() =>
-            ((IServiceCollection)null!).AddServiceLogEnricher(Mock.Of<IConfigurationSection>()));
+            ((IServiceCollection)null!).AddApplicationLogEnricher(Mock.Of<IConfigurationSection>()));
 
         Assert.Throws<ArgumentNullException>(() =>
-            new ServiceCollection().AddServiceLogEnricher((IConfigurationSection)null!));
+            new ServiceCollection().AddApplicationLogEnricher((IConfigurationSection)null!));
     }
 
     [Fact]
     public void ServiceLogEnricher_GivenNoArguments_RegistersInDI()
     {
         // Arrange & Act
         using var host = FakeHost.CreateBuilder()
-            .ConfigureServices(services => services.AddServiceLogEnricher())
+            .ConfigureServices(services => services.AddApplicationLogEnricher())
             .Build();
 
         // Assert
@@ -48,7 +48,7 @@ public void HostLogEnricher_GivenOptions_RegistersInDI()
         // Arrange & Act
         using var host = FakeHost.CreateBuilder()
             .ConfigureLogging(builder => builder
-                .Services.AddServiceLogEnricher(e =>
+                .Services.AddApplicationLogEnricher(e =>
                 {
                     e.ApplicationName = false;
                     e.EnvironmentName = false;
@@ -68,17 +68,17 @@ public void HostLogEnricher_GivenOptions_RegistersInDI()
     }
 
     [Fact]
-    public void ServiceLogEnricher_GivenConfiguration_RegistersInDI()
+    public void ApplicationLogEnricher_GivenConfiguration_RegistersInDI()
     {
         // Arrange & Act
         using var host = FakeHost.CreateBuilder()
             .ConfigureAppConfiguration(
-                ("Serviceenrichersection:ApplicationName", "true"),
-                ("Serviceenrichersection:EnvironmentName", "false"),
-                ("Serviceenrichersection:BuildVersion", "true"),
-                ("Serviceenrichersection:DeploymentRing", "true"))
+                ("Applicationenrichersection:ApplicationName", "true"),
+                ("Applicationenrichersection:EnvironmentName", "false"),
+                ("Applicationenrichersection:BuildVersion", "true"),
+                ("Applicationenrichersection:DeploymentRing", "true"))
             .ConfigureServices((context, services) => services
-                .AddServiceLogEnricher(context.Configuration.GetSection("Serviceenrichersection")))
+                .AddApplicationLogEnricher(context.Configuration.GetSection("Applicationenrichersection")))
             .Build();
 
         // Assert

test/Libraries/Microsoft.Extensions.Telemetry.Tests/Enrichment/ApplicationEnricherOptionsTests.cs

@@ -9,7 +9,7 @@ namespace Microsoft.Extensions.Diagnostics.Enrichment.Test;
 public class ApplicationEnricherOptionsTests
 {
     [Fact]
-    public void ServiceLogEnricherOptions_EnsureDefaultValues()
+    public void ApplicationLogEnricherOptions_EnsureDefaultValues()
     {
         var options = new ApplicationLogEnricherOptions();
         options.EnvironmentName.Should().BeTrue();

test/Libraries/Microsoft.Extensions.Telemetry.Tests/Enrichment/ApplicationLogEnricherTests.cs

@@ -39,20 +39,20 @@ public void HostLogEnricher_GivenInvalidArguments_Throws()
         var optionsNull = new Mock<IOptions<ApplicationLogEnricherOptions>>();
         optionsNull.Setup(o => o.Value).Returns<IOptions<ApplicationLogEnricherOptions>>(null!);
 
-        var serviceOptionsNull = new Mock<IOptions<ApplicationMetadata>>();
-        serviceOptionsNull.Setup(o => o.Value).Returns<IOptions<ApplicationMetadata>>(null!);
+        var applicationOptionsNull = new Mock<IOptions<ApplicationMetadata>>();
+        applicationOptionsNull.Setup(o => o.Value).Returns<IOptions<ApplicationMetadata>>(null!);
 
         // Act & Assert
         Assert.Throws<ArgumentException>(() => new ApplicationLogEnricher(optionsNull.Object, null!));
-        Assert.Throws<ArgumentException>(() => new ApplicationLogEnricher(options, serviceOptionsNull.Object));
+        Assert.Throws<ArgumentException>(() => new ApplicationLogEnricher(options, applicationOptionsNull.Object));
     }
 
     [Theory]
     [InlineData(true, true, true, true, null, null)]
     [InlineData(true, true, true, true, BuildVersion, DeploymentRing)]
     [InlineData(false, false, false, false, null, null)]
     [InlineData(false, false, false, false, BuildVersion, DeploymentRing)]
-    public void ServiceLogEnricher_Options(bool appName, bool envName, bool buildVer, bool depRing, string? buildVersion, string? deploymentRing)
+    public void ApplicationLogEnricher_Options(bool appName, bool envName, bool buildVer, bool depRing, string? buildVersion, string? deploymentRing)
     {
         // Arrange
         var options = new ApplicationLogEnricherOptions
@@ -63,15 +63,15 @@ public void ServiceLogEnricher_Options(bool appName, bool envName, bool buildVer
             DeploymentRing = depRing,
         };
 
-        var serviceOptions = new ApplicationMetadata
+        var metadata = new ApplicationMetadata
         {
             BuildVersion = buildVersion,
             DeploymentRing = deploymentRing,
             ApplicationName = _hostMock.Object.ApplicationName,
             EnvironmentName = _hostMock.Object.EnvironmentName
         };
 
-        var enricher = new ApplicationLogEnricher(options.ToOptions(), serviceOptions.ToOptions());
+        var enricher = new ApplicationLogEnricher(options.ToOptions(), metadata.ToOptions());
         var enrichedProperties = new TestLogEnrichmentTagCollector();
 
         // Act