diff --git a/examples/enrichment/Examples.Enrichment/Program.cs b/examples/enrichment/Examples.Enrichment/Program.cs index 7d1cca1801..5a05e33c28 100644 --- a/examples/enrichment/Examples.Enrichment/Program.cs +++ b/examples/enrichment/Examples.Enrichment/Program.cs @@ -25,8 +25,8 @@ public static void Main() .AddSource("MyCompany.MyProduct.MyLibrary") // Register an enricher class. - // Important: AddTraceEnricher() must be called before any exporters. - .AddTraceEnricher() + // Important: TryAddTraceEnricher() must be called before any exporters. + .TryAddTraceEnricher() // Add Console exporter to see the output of this example. .AddConsoleExporter() diff --git a/src/OpenTelemetry.Extensions.Enrichment/.publicApi/PublicAPI.Unshipped.txt b/src/OpenTelemetry.Extensions.Enrichment/.publicApi/PublicAPI.Unshipped.txt index a037573dcc..36f768caaa 100644 --- a/src/OpenTelemetry.Extensions.Enrichment/.publicApi/PublicAPI.Unshipped.txt +++ b/src/OpenTelemetry.Extensions.Enrichment/.publicApi/PublicAPI.Unshipped.txt @@ -7,12 +7,12 @@ OpenTelemetry.Extensions.Enrichment.TraceEnrichmentBag.Add(string! key, object? OpenTelemetry.Extensions.Enrichment.TraceEnrichmentBag.TraceEnrichmentBag() -> void OpenTelemetry.Extensions.Enrichment.TraceEnrichmentBag.TraceEnrichmentBag(System.Diagnostics.Activity! activity) -> void OpenTelemetry.Extensions.Enrichment.TraceEnrichmentProviderBuilderExtensions -static Microsoft.Extensions.DependencyInjection.TraceEnrichmentServiceCollectionExtensions.AddTraceEnricher(this Microsoft.Extensions.DependencyInjection.IServiceCollection! services, OpenTelemetry.Extensions.Enrichment.TraceEnricher! enricher) -> Microsoft.Extensions.DependencyInjection.IServiceCollection! +static Microsoft.Extensions.DependencyInjection.TraceEnrichmentServiceCollectionExtensions.TryAddTraceEnricher(this Microsoft.Extensions.DependencyInjection.IServiceCollection! services, OpenTelemetry.Extensions.Enrichment.TraceEnricher! enricher) -> Microsoft.Extensions.DependencyInjection.IServiceCollection! static Microsoft.Extensions.DependencyInjection.TraceEnrichmentServiceCollectionExtensions.AddTraceEnricher(this Microsoft.Extensions.DependencyInjection.IServiceCollection! services, System.Action! enrichmentAction) -> Microsoft.Extensions.DependencyInjection.IServiceCollection! static Microsoft.Extensions.DependencyInjection.TraceEnrichmentServiceCollectionExtensions.AddTraceEnricher(this Microsoft.Extensions.DependencyInjection.IServiceCollection! services, System.Func! enricherImplementationFactory) -> Microsoft.Extensions.DependencyInjection.IServiceCollection! -static Microsoft.Extensions.DependencyInjection.TraceEnrichmentServiceCollectionExtensions.AddTraceEnricher(this Microsoft.Extensions.DependencyInjection.IServiceCollection! services) -> Microsoft.Extensions.DependencyInjection.IServiceCollection! -static OpenTelemetry.Extensions.Enrichment.TraceEnrichmentProviderBuilderExtensions.AddTraceEnricher(this OpenTelemetry.Trace.TracerProviderBuilder! builder, OpenTelemetry.Extensions.Enrichment.TraceEnricher! enricher) -> OpenTelemetry.Trace.TracerProviderBuilder! +static Microsoft.Extensions.DependencyInjection.TraceEnrichmentServiceCollectionExtensions.TryAddTraceEnricher(this Microsoft.Extensions.DependencyInjection.IServiceCollection! services) -> Microsoft.Extensions.DependencyInjection.IServiceCollection! +static OpenTelemetry.Extensions.Enrichment.TraceEnrichmentProviderBuilderExtensions.TryAddTraceEnricher(this OpenTelemetry.Trace.TracerProviderBuilder! builder, OpenTelemetry.Extensions.Enrichment.TraceEnricher! enricher) -> OpenTelemetry.Trace.TracerProviderBuilder! static OpenTelemetry.Extensions.Enrichment.TraceEnrichmentProviderBuilderExtensions.AddTraceEnricher(this OpenTelemetry.Trace.TracerProviderBuilder! builder, System.Action! enrichmentAction) -> OpenTelemetry.Trace.TracerProviderBuilder! static OpenTelemetry.Extensions.Enrichment.TraceEnrichmentProviderBuilderExtensions.AddTraceEnricher(this OpenTelemetry.Trace.TracerProviderBuilder! builder, System.Func! enricherImplementationFactory) -> OpenTelemetry.Trace.TracerProviderBuilder! -static OpenTelemetry.Extensions.Enrichment.TraceEnrichmentProviderBuilderExtensions.AddTraceEnricher(this OpenTelemetry.Trace.TracerProviderBuilder! builder) -> OpenTelemetry.Trace.TracerProviderBuilder! +static OpenTelemetry.Extensions.Enrichment.TraceEnrichmentProviderBuilderExtensions.TryAddTraceEnricher(this OpenTelemetry.Trace.TracerProviderBuilder! builder) -> OpenTelemetry.Trace.TracerProviderBuilder! virtual OpenTelemetry.Extensions.Enrichment.TraceEnricher.EnrichOnActivityStart(in OpenTelemetry.Extensions.Enrichment.TraceEnrichmentBag bag) -> void diff --git a/src/OpenTelemetry.Extensions.Enrichment/CHANGELOG.md b/src/OpenTelemetry.Extensions.Enrichment/CHANGELOG.md index 4ccadd544d..dc60fb3f0a 100644 --- a/src/OpenTelemetry.Extensions.Enrichment/CHANGELOG.md +++ b/src/OpenTelemetry.Extensions.Enrichment/CHANGELOG.md @@ -2,6 +2,11 @@ ## Unreleased +* **Breaking change**: Renamed some extension methods from `AddTraceEnricher*()` + to `TryAddTraceEnricer*()` pattern to more accurately reflect their behavior of + only adding the enricher if it hasn't already been added. + ([#3085](https://github.com/open-telemetry/opentelemetry-dotnet-contrib/pull/3085)) + ## 1.12.0-alpha.1 Released 2025-Aug-18 diff --git a/src/OpenTelemetry.Extensions.Enrichment/OpenTelemetry.Extensions.Enrichment.csproj b/src/OpenTelemetry.Extensions.Enrichment/OpenTelemetry.Extensions.Enrichment.csproj index 47c496cb93..8bf5176816 100644 --- a/src/OpenTelemetry.Extensions.Enrichment/OpenTelemetry.Extensions.Enrichment.csproj +++ b/src/OpenTelemetry.Extensions.Enrichment/OpenTelemetry.Extensions.Enrichment.csproj @@ -21,7 +21,6 @@ - diff --git a/src/OpenTelemetry.Extensions.Enrichment/README.md b/src/OpenTelemetry.Extensions.Enrichment/README.md index 2b9f1767e5..4b34d0db3d 100644 --- a/src/OpenTelemetry.Extensions.Enrichment/README.md +++ b/src/OpenTelemetry.Extensions.Enrichment/README.md @@ -79,7 +79,7 @@ in your application. ### Step 3: Register enricher class Add your custom enricher class to the `TracerProviderBuilder` by calling the -`AddTraceEnricher()` method. Configure other services via +`TryAddTraceEnricher()` method. Configure other services via `ConfigureServices()`, add `ActivitySource` and an exporter as usual: ```csharp @@ -87,7 +87,7 @@ using var MyActivitySource = new ActivitySource("MyCompany.MyProduct.MyLibrary") using var tracerProvider = Sdk.CreateTracerProviderBuilder() .ConfigureServices(services => services.AddSingleton()) .AddSource("MyCompany.MyProduct.MyLibrary") - .AddTraceEnricher() + .TryAddTraceEnricher() .AddConsoleExporter() .Build(); ``` @@ -103,7 +103,7 @@ public void ConfigureServices(IServiceCollection services) services.AddSingleton(); services.AddOpenTelemetry().WithTracing((builder) => builder .AddSource("MyCompany.MyProduct.MyLibrary") - .AddTraceEnricher() + .TryAddTraceEnricher() .AddConsoleExporter()); } ``` @@ -155,16 +155,16 @@ enricher class. In this case, the enricher class will be created for you by Dependency Injection: ```csharp -public static AddTraceEnricher(this IServiceCollection services) -public static AddTraceEnricher(this TracerProviderBuilder builder) +public static TryAddTraceEnricher(this IServiceCollection services) +public static TryAddTraceEnricher(this TracerProviderBuilder builder) ``` If you prefer to instantiate your enricher class on your own, you may use one of these methods which allow for the usage of pre-existing enricher objects: ```csharp -public static AddTraceEnricher(this IServiceCollection services, TraceEnricher enricher) -public static AddTraceEnricher(this TracerProviderBuilder builder, TraceEnricher enricher) +public static TryAddTraceEnricher(this IServiceCollection services, TraceEnricher enricher) +public static TryAddTraceEnricher(this TracerProviderBuilder builder, TraceEnricher enricher) ``` If you only need to enrich a small amount of data, it may not be necessary to create diff --git a/src/OpenTelemetry.Extensions.Enrichment/TraceEnrichmentProviderBuilderExtensions.cs b/src/OpenTelemetry.Extensions.Enrichment/TraceEnrichmentProviderBuilderExtensions.cs index 871bc63850..68fe83b32b 100644 --- a/src/OpenTelemetry.Extensions.Enrichment/TraceEnrichmentProviderBuilderExtensions.cs +++ b/src/OpenTelemetry.Extensions.Enrichment/TraceEnrichmentProviderBuilderExtensions.cs @@ -16,7 +16,7 @@ namespace OpenTelemetry.Extensions.Enrichment; public static class TraceEnrichmentProviderBuilderExtensions { /// - /// Adds trace enricher. + /// Adds a implementation of type as a Singleton to the specified if one has not already been registered. /// /// being configured. /// Enricher object type. @@ -26,20 +26,20 @@ public static class TraceEnrichmentProviderBuilderExtensions /// Add this enricher *before* exporter related Activity processors. /// #if NET - public static TracerProviderBuilder AddTraceEnricher<[DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.PublicConstructors)] T>(this TracerProviderBuilder builder) + public static TracerProviderBuilder TryAddTraceEnricher<[DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.PublicConstructors)] T>(this TracerProviderBuilder builder) #else - public static TracerProviderBuilder AddTraceEnricher(this TracerProviderBuilder builder) + public static TracerProviderBuilder TryAddTraceEnricher(this TracerProviderBuilder builder) #endif where T : TraceEnricher { Guard.ThrowIfNull(builder); return builder - .ConfigureServices(services => services.AddTraceEnricher()); + .ConfigureServices(services => services.TryAddTraceEnricher()); } /// - /// Adds trace enricher. + /// Adds a implementation of type as a Singleton to the specified if one has not already been registered. /// /// being configured. /// The object being added. @@ -48,17 +48,17 @@ public static TracerProviderBuilder AddTraceEnricher(this TracerProviderBuild /// /// Add this enricher *before* exporter related Activity processors. /// - public static TracerProviderBuilder AddTraceEnricher(this TracerProviderBuilder builder, TraceEnricher enricher) + public static TracerProviderBuilder TryAddTraceEnricher(this TracerProviderBuilder builder, TraceEnricher enricher) { Guard.ThrowIfNull(builder); Guard.ThrowIfNull(enricher); return builder - .ConfigureServices(services => services.AddTraceEnricher(enricher)); + .ConfigureServices(services => services.TryAddTraceEnricher(enricher)); } /// - /// Adds trace enricher. + /// Adds a trace enricher delegate to the specified . /// /// being configured. /// The delegate to enrich traces. @@ -77,7 +77,7 @@ public static TracerProviderBuilder AddTraceEnricher(this TracerProviderBuilder } /// - /// Adds trace enricher. + /// Adds a trace enricher factory to the specified . /// /// being configured. /// The object being added using implementation factory. diff --git a/src/OpenTelemetry.Extensions.Enrichment/TraceEnrichmentServiceCollectionExtensions.cs b/src/OpenTelemetry.Extensions.Enrichment/TraceEnrichmentServiceCollectionExtensions.cs index 3741f04e0c..b4efa7198b 100644 --- a/src/OpenTelemetry.Extensions.Enrichment/TraceEnrichmentServiceCollectionExtensions.cs +++ b/src/OpenTelemetry.Extensions.Enrichment/TraceEnrichmentServiceCollectionExtensions.cs @@ -17,7 +17,7 @@ namespace Microsoft.Extensions.DependencyInjection; public static class TraceEnrichmentServiceCollectionExtensions { /// - /// Adds trace enricher. + /// Adds a implementation of type as a Singleton to the specified if one has not already been registered. /// /// being configured. /// Enricher object type. @@ -27,21 +27,21 @@ public static class TraceEnrichmentServiceCollectionExtensions /// Add this enricher *before* exporter related Activity processors. /// #if NET - public static IServiceCollection AddTraceEnricher<[DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.PublicConstructors)] T>(this IServiceCollection services) + public static IServiceCollection TryAddTraceEnricher<[DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.PublicConstructors)] T>(this IServiceCollection services) #else - public static IServiceCollection AddTraceEnricher(this IServiceCollection services) + public static IServiceCollection TryAddTraceEnricher(this IServiceCollection services) #endif where T : TraceEnricher { Guard.ThrowIfNull(services); - return services - .TryAddEnrichment() - .AddSingleton(); + services.TryAddEnumerable(ServiceDescriptor.Singleton()); + + return services.TryAddEnrichment(); } /// - /// Adds trace enricher. + /// Adds a implementation of type as a Singleton to the specified if one has not already been registered. /// /// being configured. /// The object being added. @@ -50,18 +50,18 @@ public static IServiceCollection AddTraceEnricher(this IServiceCollection ser /// /// Add this enricher *before* exporter related Activity processors. /// - public static IServiceCollection AddTraceEnricher(this IServiceCollection services, TraceEnricher enricher) + public static IServiceCollection TryAddTraceEnricher(this IServiceCollection services, TraceEnricher enricher) { Guard.ThrowIfNull(services); Guard.ThrowIfNull(enricher); - return services - .TryAddEnrichment() - .AddSingleton(enricher); + services.TryAddEnumerable(ServiceDescriptor.Singleton(enricher)); + + return services.TryAddEnrichment(); } /// - /// Adds trace enricher. + /// Adds a trace enricher delegate to the specified . /// /// being configured. /// The delegate to enrich traces. @@ -83,7 +83,7 @@ public static IServiceCollection AddTraceEnricher(this IServiceCollection servic } /// - /// Adds trace enricher. + /// Adds a trace enricher factory to the specified . /// /// being configured. /// The object being added using implementation factory. @@ -99,7 +99,7 @@ public static IServiceCollection AddTraceEnricher(this IServiceCollection servic return services .TryAddEnrichment() - .AddSingleton((serviceProvider) => enricherImplementationFactory(serviceProvider)); + .AddSingleton(enricherImplementationFactory); } private static IServiceCollection TryAddEnrichment(this IServiceCollection services) diff --git a/test/OpenTelemetry.Extensions.Enrichment.Tests/OpenTelemetryEnrichmentProviderBuilderExtensions.cs b/test/OpenTelemetry.Extensions.Enrichment.Tests/OpenTelemetryEnrichmentProviderBuilderExtensions.cs index 86976d8f5d..171b5f787d 100644 --- a/test/OpenTelemetry.Extensions.Enrichment.Tests/OpenTelemetryEnrichmentProviderBuilderExtensions.cs +++ b/test/OpenTelemetry.Extensions.Enrichment.Tests/OpenTelemetryEnrichmentProviderBuilderExtensions.cs @@ -12,14 +12,14 @@ public sealed class OpenTelemetryEnrichmentProviderBuilderExtensions private const string SourceName = nameof(OpenTelemetryEnrichmentProviderBuilderExtensions); [Fact] - public void AddTraceEnricherOfTRegistersEnricher() + public void GenericMethod_RegistersEnricher() { var exportedItems = new List(); using var tracerProvider = Sdk.CreateTracerProviderBuilder() .AddSource(SourceName) - .AddTraceEnricher() - .AddTraceEnricher() + .TryAddTraceEnricher() + .TryAddTraceEnricher() .AddInMemoryExporter(exportedItems) .Build(); @@ -41,14 +41,14 @@ public void AddTraceEnricherOfTRegistersEnricher() } [Fact] - public void AddTraceEnricherRegistersEnricher() + public void InstanceMethod_RegistersEnricher() { var exportedItems = new List(); using var tracerProvider = Sdk.CreateTracerProviderBuilder() .AddSource(SourceName) - .AddTraceEnricher(new MyTraceEnricher()) - .AddTraceEnricher(new MyTraceEnricher2()) + .TryAddTraceEnricher(new MyTraceEnricher()) + .TryAddTraceEnricher(new MyTraceEnricher2()) .AddInMemoryExporter(exportedItems) .Build(); @@ -71,7 +71,7 @@ public void AddTraceEnricherRegistersEnricher() } [Fact] - public void AddTraceEnricherActionRegistersEnricher() + public void DelegateMethod_RegistersEnricher() { var exportedItems = new List(); @@ -106,7 +106,7 @@ public void AddTraceEnricherActionRegistersEnricher() } [Fact] - public void AddTraceEnricherFactoryRegistersEnricher() + public void FactoryMethod_RegistersEnricher() { var exportedItems = new List(); diff --git a/test/OpenTelemetry.Extensions.Enrichment.Tests/OpenTelemetryEnrichmentServiceCollectionExtensionsTests.cs b/test/OpenTelemetry.Extensions.Enrichment.Tests/OpenTelemetryEnrichmentServiceCollectionExtensionsTests.cs index 19448cb7dc..cb1d244a1d 100644 --- a/test/OpenTelemetry.Extensions.Enrichment.Tests/OpenTelemetryEnrichmentServiceCollectionExtensionsTests.cs +++ b/test/OpenTelemetry.Extensions.Enrichment.Tests/OpenTelemetryEnrichmentServiceCollectionExtensionsTests.cs @@ -14,7 +14,7 @@ public sealed class OpenTelemetryEnrichmentServiceCollectionExtensionsTests private const string SourceName = nameof(OpenTelemetryEnrichmentServiceCollectionExtensionsTests); [Fact] - public async Task AddTraceEnricherOfTRegistersEnricher() + public async Task GenericMethod_TRegistersEnricher() { var exportedItems = new List(); @@ -25,8 +25,8 @@ public async Task AddTraceEnricherOfTRegistersEnricher() .AddSource(SourceName) .AddInMemoryExporter(exportedItems)) .Services - .AddTraceEnricher() - .AddTraceEnricher()) + .TryAddTraceEnricher() + .TryAddTraceEnricher()) .Build(); await host.StartAsync(); @@ -62,7 +62,7 @@ public async Task AddTraceEnricherOfTRegistersEnricher() } [Fact] - public async Task AddTraceEnricherRegistersEnricher() + public async Task InstanceMethod_RegistersEnricher() { var exportedItems = new List(); @@ -73,8 +73,8 @@ public async Task AddTraceEnricherRegistersEnricher() .AddSource(SourceName) .AddInMemoryExporter(exportedItems)) .Services - .AddTraceEnricher(new MyTraceEnricher()) - .AddTraceEnricher(new MyTraceEnricher2())) + .TryAddTraceEnricher(new MyTraceEnricher()) + .TryAddTraceEnricher(new MyTraceEnricher2())) .Build(); await host.StartAsync(); @@ -103,7 +103,7 @@ public async Task AddTraceEnricherRegistersEnricher() } [Fact] - public async Task AddTraceEnricherActionRegistersEnricher() + public async Task DelegateMethod_RegistersEnricher() { var exportedItems = new List(); @@ -144,7 +144,7 @@ public async Task AddTraceEnricherActionRegistersEnricher() } [Fact] - public async Task AddTraceEnricherFactoryRegistersEnricher() + public async Task FactoryMethod_RegistersEnricher() { var exportedItems = new List();