[api+sdk] Groundwork for cross-cutting builder extensions

src/OpenTelemetry.Api.ProviderBuilderExtensions/.publicApi/Stable/PublicAPI.Unshipped.txt

@@ -0,0 +1,2 @@
+OpenTelemetry.IOpenTelemetryBuilder
+OpenTelemetry.IOpenTelemetryBuilder.Services.get -> Microsoft.Extensions.DependencyInjection.IServiceCollection!

src/OpenTelemetry.Api.ProviderBuilderExtensions/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+* Added `IOpenTelemetryBuilder` interface to support authoring extensions which
+  can configure multiple OpenTelemetry signals (tracing, metrics, and/or logs).
+  ([#5265](https://github.com/open-telemetry/opentelemetry-dotnet/pull/5265))
+
 ## 1.7.0
 
 Released 2023-Dec-08

src/OpenTelemetry.Api.ProviderBuilderExtensions/IOpenTelemetryBuilder.cs

@@ -0,0 +1,19 @@
+// Copyright The OpenTelemetry Authors
+// SPDX-License-Identifier: Apache-2.0
+
+using Microsoft.Extensions.DependencyInjection;
+
+namespace OpenTelemetry;
+
+/// <summary>
+/// An interface for configuring OpenTelemetry inside an <see
+/// cref="IServiceCollection"/>.
+/// </summary>
+public interface IOpenTelemetryBuilder
+{
+    /// <summary>
+    /// Gets the <see cref="IServiceCollection"/> where OpenTelemetry services
+    /// are configured.
+    /// </summary>
+    IServiceCollection Services { get; }
+}

src/OpenTelemetry.Extensions.Hosting/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ## Unreleased
 
+* `OpenTelemetryBuilder` has been marked obsolete. Component authors using
+  `OpenTelemetryBuilder` for cross-cutting signal configuration extensions
+  should switch to targeting `IOpenTelemetryBuilder` instead.
+  ([#5265](https://github.com/open-telemetry/opentelemetry-dotnet/pull/5265))
+
 ## 1.7.0
 
 Released 2023-Dec-08

src/OpenTelemetry.Extensions.Hosting/OpenTelemetry.Extensions.Hosting.csproj

@@ -10,7 +10,6 @@
 
   <ItemGroup>
     <PackageReference Include="Microsoft.Extensions.Hosting.Abstractions" />
-    <PackageReference Include="Microsoft.Extensions.Diagnostics.Abstractions" />
   </ItemGroup>
 
   <ItemGroup>

src/OpenTelemetry.Extensions.Hosting/OpenTelemetryBuilder.cs

@@ -19,7 +19,8 @@ namespace OpenTelemetry;
 /// Contains methods for configuring the OpenTelemetry SDK inside an <see
 /// cref="IServiceCollection"/>.
 /// </summary>
-public sealed class OpenTelemetryBuilder
+[Obsolete("Use IOpenTelemetryBuilder instead this class will be removed in a future version.")]
+public sealed class OpenTelemetryBuilder : IOpenTelemetryBuilder
 {
     internal OpenTelemetryBuilder(IServiceCollection services)
     {
@@ -30,9 +31,7 @@ internal OpenTelemetryBuilder(IServiceCollection services)
         this.Services = services;
     }
 
-    /// <summary>
-    /// Gets the <see cref="IServiceCollection"/> behind the builder.
-    /// </summary>
+    /// <inheritdoc />
     public IServiceCollection Services { get; }
 
     /// <summary>
@@ -50,17 +49,7 @@ internal OpenTelemetryBuilder(IServiceCollection services)
     public OpenTelemetryBuilder ConfigureResource(
         Action<ResourceBuilder> configure)
     {
-        Guard.ThrowIfNull(configure);
-
-        this.Services.ConfigureOpenTelemetryMeterProvider(
-            builder => builder.ConfigureResource(configure));
-
-        this.Services.ConfigureOpenTelemetryTracerProvider(
-            builder => builder.ConfigureResource(configure));
-
-        this.Services.ConfigureOpenTelemetryLoggerProvider(
-            builder => builder.ConfigureResource(configure));
-
+        OpenTelemetryBuilderSdkExtensions.ConfigureResource(this, configure);
         return this;
     }
 
@@ -93,10 +82,7 @@ public OpenTelemetryBuilder WithMetrics()
     /// calls.</returns>
     public OpenTelemetryBuilder WithMetrics(Action<MeterProviderBuilder> configure)
     {
-        OpenTelemetryMetricsBuilderExtensions.RegisterMetricsListener(
-            this.Services,
-            configure);
-
+        OpenTelemetryBuilderSdkExtensions.WithMetrics(this, configure);
         return this;
     }
 
@@ -123,12 +109,7 @@ public OpenTelemetryBuilder WithTracing()
     /// calls.</returns>
     public OpenTelemetryBuilder WithTracing(Action<TracerProviderBuilder> configure)
     {
-        Guard.ThrowIfNull(configure);
-
-        var builder = new TracerProviderBuilderBase(this.Services);
-
-        configure(builder);
-
+        OpenTelemetryBuilderSdkExtensions.WithTracing(this, configure);
         return this;
     }
 
@@ -240,8 +221,7 @@ OpenTelemetryBuilder WithLogging(
             Action<LoggerProviderBuilder>? configureBuilder,
             Action<OpenTelemetryLoggerOptions>? configureOptions)
     {
-        this.Services.AddLogging(
-            logging => logging.UseOpenTelemetry(configureBuilder, configureOptions));
+        OpenTelemetryBuilderSdkExtensions.WithLogging(this, configureBuilder, configureOptions);
 
         return this;
     }

src/OpenTelemetry.Extensions.Hosting/OpenTelemetryServicesExtensions.cs

@@ -36,7 +36,12 @@ public static class OpenTelemetryServicesExtensions
     /// <param name="services"><see cref="IServiceCollection"/>.</param>
     /// <returns>The supplied <see cref="OpenTelemetryBuilder"/> for chaining
     /// calls.</returns>
+#pragma warning disable CS0618 // Type or member is obsolete
+    // Note: OpenTelemetryBuilder is obsolete because users should target
+    // IOpenTelemetryBuilder for extensions but this method is valid and
+    // expected to be called to obtain a root builder.
     public static OpenTelemetryBuilder AddOpenTelemetry(this IServiceCollection services)
+#pragma warning restore CS0618 // Type or member is obsolete
     {
         Guard.ThrowIfNull(services);
 

src/OpenTelemetry/.publicApi/Experimental/PublicAPI.Unshipped.txt

@@ -32,6 +32,9 @@ static OpenTelemetry.Logs.LoggerProviderExtensions.AddProcessor(this OpenTelemet
 static OpenTelemetry.Logs.LoggerProviderExtensions.ForceFlush(this OpenTelemetry.Logs.LoggerProvider! provider, int timeoutMilliseconds = -1) -> bool
 static OpenTelemetry.Logs.LoggerProviderExtensions.Shutdown(this OpenTelemetry.Logs.LoggerProvider! provider, int timeoutMilliseconds = -1) -> bool
 static OpenTelemetry.Metrics.MeterProviderBuilderExtensions.SetExemplarFilter(this OpenTelemetry.Metrics.MeterProviderBuilder! meterProviderBuilder, OpenTelemetry.Metrics.ExemplarFilter! exemplarFilter) -> OpenTelemetry.Metrics.MeterProviderBuilder!
+static OpenTelemetry.OpenTelemetryBuilderSdkExtensions.WithLogging(this OpenTelemetry.IOpenTelemetryBuilder! builder) -> OpenTelemetry.IOpenTelemetryBuilder!
+static OpenTelemetry.OpenTelemetryBuilderSdkExtensions.WithLogging(this OpenTelemetry.IOpenTelemetryBuilder! builder, System.Action<OpenTelemetry.Logs.LoggerProviderBuilder!>! configure) -> OpenTelemetry.IOpenTelemetryBuilder!
+static OpenTelemetry.OpenTelemetryBuilderSdkExtensions.WithLogging(this OpenTelemetry.IOpenTelemetryBuilder! builder, System.Action<OpenTelemetry.Logs.LoggerProviderBuilder!>? configureBuilder, System.Action<OpenTelemetry.Logs.OpenTelemetryLoggerOptions!>? configureOptions) -> OpenTelemetry.IOpenTelemetryBuilder!
 static OpenTelemetry.Sdk.CreateLoggerProviderBuilder() -> OpenTelemetry.Logs.LoggerProviderBuilder!
 abstract OpenTelemetry.Metrics.ExemplarFilter.ShouldSample(double value, System.ReadOnlySpan<System.Collections.Generic.KeyValuePair<string!, object?>> tags) -> bool
 abstract OpenTelemetry.Metrics.ExemplarFilter.ShouldSample(long value, System.ReadOnlySpan<System.Collections.Generic.KeyValuePair<string!, object?>> tags) -> bool

src/OpenTelemetry/.publicApi/Stable/PublicAPI.Unshipped.txt

@@ -0,0 +1,6 @@
+OpenTelemetry.OpenTelemetryBuilderSdkExtensions
+static OpenTelemetry.OpenTelemetryBuilderSdkExtensions.ConfigureResource(this OpenTelemetry.IOpenTelemetryBuilder! builder, System.Action<OpenTelemetry.Resources.ResourceBuilder!>! configure) -> OpenTelemetry.IOpenTelemetryBuilder!
+static OpenTelemetry.OpenTelemetryBuilderSdkExtensions.WithMetrics(this OpenTelemetry.IOpenTelemetryBuilder! builder) -> OpenTelemetry.IOpenTelemetryBuilder!
+static OpenTelemetry.OpenTelemetryBuilderSdkExtensions.WithMetrics(this OpenTelemetry.IOpenTelemetryBuilder! builder, System.Action<OpenTelemetry.Metrics.MeterProviderBuilder!>! configure) -> OpenTelemetry.IOpenTelemetryBuilder!
+static OpenTelemetry.OpenTelemetryBuilderSdkExtensions.WithTracing(this OpenTelemetry.IOpenTelemetryBuilder! builder) -> OpenTelemetry.IOpenTelemetryBuilder!
+static OpenTelemetry.OpenTelemetryBuilderSdkExtensions.WithTracing(this OpenTelemetry.IOpenTelemetryBuilder! builder, System.Action<OpenTelemetry.Trace.TracerProviderBuilder!>! configure) -> OpenTelemetry.IOpenTelemetryBuilder!

src/OpenTelemetry/CHANGELOG.md

@@ -28,6 +28,16 @@
   experimental Log Bridge API.
   [#5317](https://github.com/open-telemetry/opentelemetry-dotnet/pull/5317)
 
+* Added `OpenTelemetryBuilderSdkExtensions` class which contains extension
+  methods (`ConfigureResource`, `WithMetrics`, `WithTracing`, and experimental
+  `WithLogging`) for the `IOpenTelemetryBuilder` interface.
+  ([#5265](https://github.com/open-telemetry/opentelemetry-dotnet/pull/5265))
+
+* Added `Microsoft.Extensions.Diagnostics.Abstractions` dependency so that the
+  `IOpenTelemetryBuilder.WithMetrics` extension method can configure
+  [IMetricsListener](https://learn.microsoft.com/dotNet/api/microsoft.extensions.diagnostics.metrics.imetricslistener).
+  ([#5265](https://github.com/open-telemetry/opentelemetry-dotnet/pull/5265))
+
 ## 1.7.0
 
 Released 2023-Dec-08

src/OpenTelemetry/OpenTelemetry.csproj

@@ -6,6 +6,7 @@
   </PropertyGroup>
 
   <ItemGroup>
+    <PackageReference Include="Microsoft.Extensions.Diagnostics.Abstractions" />
     <PackageReference Include="Microsoft.Extensions.Logging.Configuration" />
   </ItemGroup>