[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/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.Api/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.Extensions.Hosting/.publicApi/Experimental/PublicAPI.Unshipped.txt

@@ -1,3 +0,0 @@
-OpenTelemetry.OpenTelemetryBuilder.WithLogging() -> OpenTelemetry.OpenTelemetryBuilder!
-OpenTelemetry.OpenTelemetryBuilder.WithLogging(System.Action<OpenTelemetry.Logs.LoggerProviderBuilder!>! configure) -> OpenTelemetry.OpenTelemetryBuilder!
-OpenTelemetry.OpenTelemetryBuilder.WithLogging(System.Action<OpenTelemetry.Logs.LoggerProviderBuilder!>? configureBuilder, System.Action<OpenTelemetry.Logs.OpenTelemetryLoggerOptions!>? configureOptions) -> OpenTelemetry.OpenTelemetryBuilder!

src/OpenTelemetry.Extensions.Hosting/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## Unreleased
 
+* **Breaking change for users of experimental APIs (pre-release builds only):**
+  Removed `WithLogging` experimental APIs on `OpenTelemetryBuilder`. These have
+  been replaced by new extension methods in the SDK targeting
+  `IOpenTelemetryBuilder`.
+  ([#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>
@@ -21,7 +20,6 @@
     <!-- Note: When '$(ExposeExperimentalFeatures)' == 'false' these links are
     NOT required because this project sees API internals -->
     <Compile Include="$(RepoRoot)\src\Shared\Guard.cs" Link="Includes\Guard.cs" RequiresExposedExperimentalFeatures="true" />
-    <Compile Include="$(RepoRoot)\src\Shared\DiagnosticDefinitions.cs" Link="Includes\DiagnosticDefinitions.cs" RequiresExposedExperimentalFeatures="true" />
     <Compile Include="$(RepoRoot)\src\Shared\ExceptionExtensions.cs" Link="Includes\ExceptionExtensions.cs" RequiresExposedExperimentalFeatures="true" />
   </ItemGroup>
 

src/OpenTelemetry.Extensions.Hosting/OpenTelemetryBuilder.cs

@@ -1,14 +1,9 @@
 // Copyright The OpenTelemetry Authors
 // SPDX-License-Identifier: Apache-2.0
 
-#if EXPOSE_EXPERIMENTAL_FEATURES && NET8_0_OR_GREATER
-using System.Diagnostics.CodeAnalysis;
-#endif
 using Microsoft.Extensions.DependencyInjection;
 using Microsoft.Extensions.Diagnostics.Metrics;
-using Microsoft.Extensions.Logging;
 using OpenTelemetry.Internal;
-using OpenTelemetry.Logs;
 using OpenTelemetry.Metrics;
 using OpenTelemetry.Resources;
 using OpenTelemetry.Trace;
@@ -19,7 +14,13 @@ namespace OpenTelemetry;
 /// Contains methods for configuring the OpenTelemetry SDK inside an <see
 /// cref="IServiceCollection"/>.
 /// </summary>
-public sealed class OpenTelemetryBuilder
+// [Obsolete] <- This class is not marked obsolete because there would be a big
+// impact to do that but it technically is obsolete. If we do a major release
+// with breaking changes this class can be deleted. IOpenTelemetryBuilder has
+// source-compatible extensions via the SDK. We maintain this for binary
+// compatibility only. Something like this might help:
+// https://github.com/dotnet/csharplang/issues/7706
+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,126 +109,7 @@ public OpenTelemetryBuilder WithTracing()
     /// calls.</returns>
     public OpenTelemetryBuilder WithTracing(Action<TracerProviderBuilder> configure)
     {
-        Guard.ThrowIfNull(configure);
-
-        var builder = new TracerProviderBuilderBase(this.Services);
-
-        configure(builder);
-
-        return this;
-    }
-
-#if EXPOSE_EXPERIMENTAL_FEATURES
-    /// <summary>
-    /// Adds logging services into the builder.
-    /// </summary>
-    /// <remarks>
-    /// <para><b>WARNING</b>: This is an experimental API which might change or
-    /// be removed in the future. Use at your own risk.</para>
-    /// Notes:
-    /// <list type="bullet">
-    /// <item>This is safe to be called multiple times and by library authors.
-    /// Only a single <see cref="LoggerProvider"/> will be created for a given
-    /// <see cref="IServiceCollection"/>.</item>
-    /// <item>This method automatically registers an <see
-    /// cref="ILoggerProvider"/> named 'OpenTelemetry' into the <see
-    /// cref="IServiceCollection"/>.</item>
-    /// </list>
-    /// </remarks>
-    /// <returns>The supplied <see cref="OpenTelemetryBuilder"/> for chaining
-    /// calls.</returns>
-#if NET8_0_OR_GREATER
-    [Experimental(DiagnosticDefinitions.LoggerProviderExperimentalApi, UrlFormat = DiagnosticDefinitions.ExperimentalApiUrlFormat)]
-#endif
-    public
-#else
-    /// <summary>
-    /// Adds logging services into the builder.
-    /// </summary>
-    /// <remarks>
-    /// Notes:
-    /// <list type="bullet">
-    /// <item>This is safe to be called multiple times and by library authors.
-    /// Only a single <see cref="LoggerProvider"/> will be created for a given
-    /// <see cref="IServiceCollection"/>.</item>
-    /// <item>This method automatically registers an <see
-    /// cref="ILoggerProvider"/> named 'OpenTelemetry' into the <see
-    /// cref="IServiceCollection"/>.</item>
-    /// </list>
-    /// </remarks>
-    /// <returns>The supplied <see cref="OpenTelemetryBuilder"/> for chaining
-    /// calls.</returns>
-    internal
-#endif
-        OpenTelemetryBuilder WithLogging()
-        => this.WithLogging(configureBuilder: null, configureOptions: null);
-
-#if EXPOSE_EXPERIMENTAL_FEATURES
-    /// <summary>
-    /// Adds logging services into the builder.
-    /// </summary>
-    /// <remarks><inheritdoc cref="WithLogging()" path="/remarks"/></remarks>
-    /// <param name="configure"><see cref="LoggerProviderBuilder"/>
-    /// configuration callback.</param>
-    /// <returns>The supplied <see cref="OpenTelemetryBuilder"/> for chaining
-    /// calls.</returns>
-#if NET8_0_OR_GREATER
-    [Experimental(DiagnosticDefinitions.LoggerProviderExperimentalApi, UrlFormat = DiagnosticDefinitions.ExperimentalApiUrlFormat)]
-#endif
-    public
-#else
-    /// <summary>
-    /// Adds logging services into the builder.
-    /// </summary>
-    /// <remarks><inheritdoc cref="WithLogging()" path="/remarks"/></remarks>
-    /// <param name="configure"><see cref="LoggerProviderBuilder"/>
-    /// configuration callback.</param>
-    /// <returns>The supplied <see cref="OpenTelemetryBuilder"/> for chaining
-    /// calls.</returns>
-    internal
-#endif
-        OpenTelemetryBuilder WithLogging(Action<LoggerProviderBuilder> configure)
-    {
-        Guard.ThrowIfNull(configure);
-
-        return this.WithLogging(configureBuilder: configure, configureOptions: null);
-    }
-
-#if EXPOSE_EXPERIMENTAL_FEATURES
-    /// <summary>
-    /// Adds logging services into the builder.
-    /// </summary>
-    /// <remarks><inheritdoc cref="WithLogging()" path="/remarks"/></remarks>
-    /// <param name="configureBuilder">Optional <see
-    /// cref="LoggerProviderBuilder"/> configuration callback.</param>
-    /// <param name="configureOptions">Optional <see
-    /// cref="OpenTelemetryLoggerOptions"/> configuration callback.</param>
-    /// <returns>The supplied <see cref="OpenTelemetryBuilder"/> for chaining
-    /// calls.</returns>
-#if NET8_0_OR_GREATER
-    [Experimental(DiagnosticDefinitions.LoggerProviderExperimentalApi, UrlFormat = DiagnosticDefinitions.ExperimentalApiUrlFormat)]
-#endif
-    public
-#else
-    /// <summary>
-    /// Adds logging services into the builder.
-    /// </summary>
-    /// <remarks><inheritdoc cref="WithLogging()" path="/remarks"/></remarks>
-    /// <param name="configureBuilder">Optional <see
-    /// cref="LoggerProviderBuilder"/> configuration callback.</param>
-    /// <param name="configureOptions">Optional <see
-    /// cref="OpenTelemetryLoggerOptions"/> configuration callback.</param>
-    /// <returns>The supplied <see cref="OpenTelemetryBuilder"/> for chaining
-    /// calls.</returns>
-    internal
-#endif
-        OpenTelemetryBuilder WithLogging(
-            Action<LoggerProviderBuilder>? configureBuilder,
-            Action<OpenTelemetryLoggerOptions>? configureOptions)
-    {
-        this.Services.AddLogging(
-            logging => logging.UseOpenTelemetry(configureBuilder, configureOptions));
-
+        OpenTelemetryBuilderSdkExtensions.WithTracing(this, configure);
         return this;
     }
 }

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

@@ -30,6 +30,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

@@ -19,6 +19,16 @@
   export.
   [#5255](https://github.com/open-telemetry/opentelemetry-dotnet/pull/5255)
 
+* 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>