diff --git a/docs/list-of-diagnostics.md b/docs/list-of-diagnostics.md index 4ba19ed1099..e38d4905e2b 100644 --- a/docs/list-of-diagnostics.md +++ b/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 diff --git a/src/Libraries/Microsoft.Extensions.Telemetry/Enrichment/ApplicationEnricherServiceCollectionExtensions.cs b/src/Libraries/Microsoft.Extensions.Telemetry/Enrichment/ApplicationEnricherServiceCollectionExtensions.cs index b42eb799105..c45d46cb7da 100644 --- a/src/Libraries/Microsoft.Extensions.Telemetry/Enrichment/ApplicationEnricherServiceCollectionExtensions.cs +++ b/src/Libraries/Microsoft.Extensions.Telemetry/Enrichment/ApplicationEnricherServiceCollectionExtensions.cs @@ -2,8 +2,10 @@ // The .NET Foundation licenses this file to you under the MIT license. using System; +using System.Diagnostics.CodeAnalysis; using Microsoft.Extensions.Configuration; using Microsoft.Extensions.Diagnostics.Enrichment; +using Microsoft.Shared.DiagnosticIds; using Microsoft.Shared.Diagnostics; namespace Microsoft.Extensions.DependencyInjection; @@ -19,22 +21,65 @@ public static class ApplicationEnricherServiceCollectionExtensions /// The to add the service enricher to. /// The value of . /// is . - 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(_ => { }); + + /// + /// Adds an instance of the service enricher to the . + /// + /// The to add the service enricher to. + /// The configuration delegate. + /// The value of . + /// Any of the arguments is . + [Obsolete( + DiagnosticIds.Obsoletions.ObsoleteTelemetryApiMessage, + DiagnosticId = DiagnosticIds.Obsoletions.ObsoleteTelemetryApiDiagId, + UrlFormat = DiagnosticIds.UrlFormat)] + public static IServiceCollection AddServiceLogEnricher(this IServiceCollection services, Action configure) => + services.AddApplicationLogEnricher(configure); + + /// + /// Adds an instance of the service enricher to the . + /// + /// The to add the service enricher to. + /// The to use for configuring in the service enricher. + /// The value of . + /// Any of the arguments is . + [Obsolete( + DiagnosticIds.Obsoletions.ObsoleteTelemetryApiMessage, + DiagnosticId = DiagnosticIds.Obsoletions.ObsoleteTelemetryApiDiagId, + UrlFormat = DiagnosticIds.UrlFormat)] + public static IServiceCollection AddServiceLogEnricher(this IServiceCollection services, IConfigurationSection section) => + services.AddApplicationLogEnricher(section); + + /// + /// Adds an instance of the application enricher to the . + /// + /// The to add application enricher to. + /// The value of . + /// is . + [Experimental(diagnosticId: DiagnosticIds.Experiments.Telemetry, UrlFormat = DiagnosticIds.UrlFormat)] + public static IServiceCollection AddApplicationLogEnricher(this IServiceCollection services) { _ = Throw.IfNull(services); return services - .AddServiceLogEnricher(_ => { }); + .AddApplicationLogEnricher(_ => { }); } /// - /// Adds an instance of the service enricher to the . + /// Adds an instance of the application enricher to the . /// - /// The to add the service enricher to. + /// The to add the application enricher to. /// The configuration delegate. /// The value of . /// Any of the arguments is . - public static IServiceCollection AddServiceLogEnricher(this IServiceCollection services, Action configure) + [Experimental(diagnosticId: DiagnosticIds.Experiments.Telemetry, UrlFormat = DiagnosticIds.UrlFormat)] + public static IServiceCollection AddApplicationLogEnricher(this IServiceCollection services, Action configure) { _ = Throw.IfNull(services); _ = Throw.IfNull(configure); @@ -45,13 +90,14 @@ public static IServiceCollection AddServiceLogEnricher(this IServiceCollection s } /// - /// Adds an instance of the service enricher to the . + /// Adds an instance of the application enricher to the . /// - /// The to add the service enricher to. + /// The to add the application enricher to. /// The to use for configuring in the service enricher. /// The value of . /// Any of the arguments is . - public static IServiceCollection AddServiceLogEnricher(this IServiceCollection services, IConfigurationSection section) + [Experimental(diagnosticId: DiagnosticIds.Experiments.Telemetry, UrlFormat = DiagnosticIds.UrlFormat)] + public static IServiceCollection AddApplicationLogEnricher(this IServiceCollection services, IConfigurationSection section) { _ = Throw.IfNull(services); _ = Throw.IfNull(section); diff --git a/src/Libraries/Microsoft.Extensions.Telemetry/Enrichment/ApplicationLogEnricherOptions.cs b/src/Libraries/Microsoft.Extensions.Telemetry/Enrichment/ApplicationLogEnricherOptions.cs index f89d774bf66..5521cdbffef 100644 --- a/src/Libraries/Microsoft.Extensions.Telemetry/Enrichment/ApplicationLogEnricherOptions.cs +++ b/src/Libraries/Microsoft.Extensions.Telemetry/Enrichment/ApplicationLogEnricherOptions.cs @@ -6,7 +6,7 @@ namespace Microsoft.Extensions.Diagnostics.Enrichment; /// -/// Options for the service log enricher. +/// Options for the application log enricher. /// public class ApplicationLogEnricherOptions { diff --git a/src/Libraries/Microsoft.Extensions.Telemetry/Microsoft.Extensions.Telemetry.csproj b/src/Libraries/Microsoft.Extensions.Telemetry/Microsoft.Extensions.Telemetry.csproj index 81d379cd381..f0ef19bc5a9 100644 --- a/src/Libraries/Microsoft.Extensions.Telemetry/Microsoft.Extensions.Telemetry.csproj +++ b/src/Libraries/Microsoft.Extensions.Telemetry/Microsoft.Extensions.Telemetry.csproj @@ -3,6 +3,7 @@ Microsoft.Extensions.Diagnostics Provides canonical implementations of telemetry abstractions. Telemetry + $(NoWarn);CS0436 @@ -17,6 +18,7 @@ true true true + true true true diff --git a/src/Libraries/Microsoft.Extensions.Telemetry/README.md b/src/Libraries/Microsoft.Extensions.Telemetry/README.md index d9f34b42eab..1ce4788c610 100644 --- a/src/Libraries/Microsoft.Extensions.Telemetry/README.md +++ b/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 => diff --git a/src/Shared/DiagnosticIds/DiagnosticIds.cs b/src/Shared/DiagnosticIds/DiagnosticIds.cs index 0fafcb46879..b63bce21f36 100644 --- a/src/Shared/DiagnosticIds/DiagnosticIds.cs +++ b/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."; } } diff --git a/test/Libraries/Microsoft.Extensions.Telemetry.Tests/Enrichment/ApplicationEnricherExtensionsTests.cs b/test/Libraries/Microsoft.Extensions.Telemetry.Tests/Enrichment/ApplicationEnricherExtensionsTests.cs index b71fac38d5a..dff7bc423b2 100644 --- a/test/Libraries/Microsoft.Extensions.Telemetry.Tests/Enrichment/ApplicationEnricherExtensionsTests.cs +++ b/test/Libraries/Microsoft.Extensions.Telemetry.Tests/Enrichment/ApplicationEnricherExtensionsTests.cs @@ -18,16 +18,16 @@ public class ApplicationEnricherExtensionsTests public void ServiceLogEnricher_GivenAnyNullArgument_Throws() { Assert.Throws(() => - ((IServiceCollection)null!).AddServiceLogEnricher()); + ((IServiceCollection)null!).AddApplicationLogEnricher()); Assert.Throws(() => - ((IServiceCollection)null!).AddServiceLogEnricher(_ => { })); + ((IServiceCollection)null!).AddApplicationLogEnricher(_ => { })); Assert.Throws(() => - ((IServiceCollection)null!).AddServiceLogEnricher(Mock.Of())); + ((IServiceCollection)null!).AddApplicationLogEnricher(Mock.Of())); Assert.Throws(() => - new ServiceCollection().AddServiceLogEnricher((IConfigurationSection)null!)); + new ServiceCollection().AddApplicationLogEnricher((IConfigurationSection)null!)); } [Fact] @@ -35,7 +35,7 @@ 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 diff --git a/test/Libraries/Microsoft.Extensions.Telemetry.Tests/Enrichment/ApplicationEnricherOptionsTests.cs b/test/Libraries/Microsoft.Extensions.Telemetry.Tests/Enrichment/ApplicationEnricherOptionsTests.cs index d1961b96ca5..cd416cb7d86 100644 --- a/test/Libraries/Microsoft.Extensions.Telemetry.Tests/Enrichment/ApplicationEnricherOptionsTests.cs +++ b/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(); diff --git a/test/Libraries/Microsoft.Extensions.Telemetry.Tests/Enrichment/ApplicationLogEnricherTests.cs b/test/Libraries/Microsoft.Extensions.Telemetry.Tests/Enrichment/ApplicationLogEnricherTests.cs index 525d7eadf73..d6afc9054f9 100644 --- a/test/Libraries/Microsoft.Extensions.Telemetry.Tests/Enrichment/ApplicationLogEnricherTests.cs +++ b/test/Libraries/Microsoft.Extensions.Telemetry.Tests/Enrichment/ApplicationLogEnricherTests.cs @@ -39,12 +39,12 @@ public void HostLogEnricher_GivenInvalidArguments_Throws() var optionsNull = new Mock>(); optionsNull.Setup(o => o.Value).Returns>(null!); - var serviceOptionsNull = new Mock>(); - serviceOptionsNull.Setup(o => o.Value).Returns>(null!); + var applicationOptionsNull = new Mock>(); + applicationOptionsNull.Setup(o => o.Value).Returns>(null!); // Act & Assert Assert.Throws(() => new ApplicationLogEnricher(optionsNull.Object, null!)); - Assert.Throws(() => new ApplicationLogEnricher(options, serviceOptionsNull.Object)); + Assert.Throws(() => new ApplicationLogEnricher(options, applicationOptionsNull.Object)); } [Theory] @@ -52,7 +52,7 @@ public void HostLogEnricher_GivenInvalidArguments_Throws() [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,7 +63,7 @@ public void ServiceLogEnricher_Options(bool appName, bool envName, bool buildVer DeploymentRing = depRing, }; - var serviceOptions = new ApplicationMetadata + var metadata = new ApplicationMetadata { BuildVersion = buildVersion, DeploymentRing = deploymentRing, @@ -71,7 +71,7 @@ public void ServiceLogEnricher_Options(bool appName, bool envName, bool buildVer 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 diff --git a/test/Libraries/Microsoft.Extensions.Telemetry.Tests/Enrichment/ServiceEnricherExtensionsTests.cs b/test/Libraries/Microsoft.Extensions.Telemetry.Tests/Enrichment/ServiceEnricherExtensionsTests.cs new file mode 100644 index 00000000000..f2360e0c928 --- /dev/null +++ b/test/Libraries/Microsoft.Extensions.Telemetry.Tests/Enrichment/ServiceEnricherExtensionsTests.cs @@ -0,0 +1,96 @@ +// 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 Microsoft.Extensions.Configuration; +using Microsoft.Extensions.DependencyInjection; +using Microsoft.Extensions.Hosting; +using Microsoft.Extensions.Hosting.Testing; +using Microsoft.Extensions.Options; +using Moq; +using Xunit; + +namespace Microsoft.Extensions.Diagnostics.Enrichment.Test; + +[Obsolete("Testing obsolete API")] +public class ServiceEnricherExtensionsTests +{ + [Fact] + public void ServiceLogEnricher_GivenAnyNullArgument_Throws() + { + Assert.Throws(() => + ((IServiceCollection)null!).AddServiceLogEnricher()); + + Assert.Throws(() => + ((IServiceCollection)null!).AddServiceLogEnricher(_ => { })); + + Assert.Throws(() => + ((IServiceCollection)null!).AddServiceLogEnricher(Mock.Of())); + + Assert.Throws(() => + new ServiceCollection().AddServiceLogEnricher((IConfigurationSection)null!)); + } + + [Fact] + public void ServiceLogEnricher_GivenNoArguments_RegistersInDI() + { + // Arrange & Act + using var host = FakeHost.CreateBuilder() + .ConfigureServices(services => services.AddServiceLogEnricher()) + .Build(); + + // Assert + Assert.NotNull(host.Services.GetRequiredService()); + } + + [Fact] + public void ServiceLogEnricher_GivenOptions_RegistersInDI() + { + // Arrange & Act + using var host = FakeHost.CreateBuilder() + .ConfigureLogging(builder => builder + .Services.AddServiceLogEnricher(e => + { + e.ApplicationName = false; + e.EnvironmentName = false; + e.BuildVersion = false; + e.DeploymentRing = false; + })) + .Build(); + + // Assert + Assert.NotNull(host.Services.GetRequiredService()); + var options = host.Services.GetRequiredService>().Value; + Assert.NotNull(options); + Assert.False(options.ApplicationName); + Assert.False(options.EnvironmentName); + Assert.False(options.BuildVersion); + Assert.False(options.DeploymentRing); + } + + [Fact] + public void ServiceLogEnricher_GivenConfiguration_RegistersInDI() + { + // Arrange & Act + using var host = FakeHost.CreateBuilder() + .ConfigureAppConfiguration( + ("Serviceenrichersection:ApplicationName", "true"), + ("Serviceenrichersection:EnvironmentName", "false"), + ("Serviceenrichersection:BuildVersion", "true"), + ("Serviceenrichersection:DeploymentRing", "true")) + .ConfigureServices((context, services) => services + .AddServiceLogEnricher(context.Configuration.GetSection("Serviceenrichersection"))) + .Build(); + + // Assert + var enricher = host.Services.GetRequiredService(); + Assert.NotNull(enricher); + Assert.IsType(enricher); + var options = host.Services.GetRequiredService>().Value; + Assert.NotNull(options); + Assert.True(options.ApplicationName); + Assert.False(options.EnvironmentName); + Assert.True(options.BuildVersion); + Assert.True(options.DeploymentRing); + } +} diff --git a/test/Libraries/Microsoft.Extensions.Telemetry.Tests/Microsoft.Extensions.Telemetry.Tests.csproj b/test/Libraries/Microsoft.Extensions.Telemetry.Tests/Microsoft.Extensions.Telemetry.Tests.csproj index 7273b05c6c7..b52f7b92d76 100644 --- a/test/Libraries/Microsoft.Extensions.Telemetry.Tests/Microsoft.Extensions.Telemetry.Tests.csproj +++ b/test/Libraries/Microsoft.Extensions.Telemetry.Tests/Microsoft.Extensions.Telemetry.Tests.csproj @@ -2,11 +2,13 @@ Microsoft.Extensions.Telemetry Unit tests for Microsoft.Extensions.Telemetry. + $(NoWarn);CS0436 false false + true false