Move LoggerProvider and friends (OTEL1000) to a stable API

build/Common.nonprod.props

@@ -44,4 +44,24 @@
 
     <Message Importance="high" Text="Skipping test execution for '$(TargetPath)' because it does not contain the '$(TargetFramework)' target." Condition="'$(_SkipTests)' == 'true'" />
   </Target>
+
+  <Target Name="ResolveExposedExperimentalFeatures" BeforeTargets="CoreCompile">
+    <!-- Note: What this does is look for $(ProjectReferenceName).BuildFlags.txt
+        files for all the dependencies of the project being compiled. If
+        ExposeExperimentalFeatures=true is found in those files we set compiler
+        constants for each project where experimental features were exposed.
+        Example:
+        OPENTELEMETRY_EXPORTER_INMEMORY_EXPERIMENTAL_FEATURES_EXPOSED;OPENTELEMETRY_EXPERIMENTAL_FEATURES_EXPOSED;OPENTELEMETRY_API_EXPERIMENTAL_FEATURES_EXPOSED;OPENTELEMETRY_API_PROVIDERBUILDEREXTENSIONS_EXPERIMENTAL_FEATURES_EXPOSED
+        -->
+    <ItemGroup>
+      <DependenciesWithExposedExperimentalFeatures
+        Include="@(_ResolvedProjectReferencePaths->'%(Filename)')"
+        Condition="$([System.IO.File]::Exists('%(RootDir)%(Directory)%(Filename).BuildFlags.txt')) AND $([System.IO.File]::ReadAllText('%(RootDir)%(Directory)%(Filename).BuildFlags.txt').Contains('ExposeExperimentalFeatures=true'))" />
+      <CompilerConstantsForDependenciesWithExposedExperimentalFeatures Include="@(DependenciesWithExposedExperimentalFeatures->'$([System.String]::Copy('%(DependenciesWithExposedExperimentalFeatures.Identity)').ToUpper().Replace('.', '_'))_EXPERIMENTAL_FEATURES_EXPOSED')" />
+    </ItemGroup>
+
+    <PropertyGroup Condition="'@(CompilerConstantsForDependenciesWithExposedExperimentalFeatures)' != ''">
+      <DefineConstants>$(DefineConstants);@(CompilerConstantsForDependenciesWithExposedExperimentalFeatures)</DefineConstants>
+    </PropertyGroup>
+  </Target>
 </Project>

build/Common.prod.props

@@ -39,6 +39,10 @@
   <ItemGroup>
     <None Include="$(MSBuildThisFileDirectory)opentelemetry-icon-color.png" Pack="true" PackagePath="\" />
     <SourceRoot Condition="'$(Deterministic)'=='true'" Include="$(MSBuildThisFileDirectory)/" />
+    <None Include="$(IntermediateOutputPath)$(ProjectName).BuildFlags.txt"
+          Link="$(ProjectName).BuildFlags.txt"
+          CopyToOutputDirectory="PreserveNewest"
+          Visible="false" />
     <!-- Note: This includes all the PublicApiAnalyzers files in projects to make editing easier in the IDE -->
     <None Include=".publicApi\**\PublicAPI.*.txt" />
   </ItemGroup>
@@ -82,6 +86,15 @@
       <DefineConstants>$(DefineConstants);EXPOSE_EXPERIMENTAL_FEATURES</DefineConstants>
     </PropertyGroup>
 
+    <!-- Note: We write a file into the output dir which captures the state of
+    ExposeExperimentalFeatures for the current compilation. This is used by
+    consuming projects (tests, benchmarks, examples, etc) to add compiler
+    constants which can be used to detect experimental APIs -->
+    <WriteLinesToFile
+      File="$(IntermediateOutputPath)$(ProjectName).BuildFlags.txt"
+      Lines="ExposeExperimentalFeatures=$(ExposeExperimentalFeatures)"
+      Overwrite="true"/>
+
     <!-- Note: This selects the correct PublicApiAnalyzers files based on $(ExposeExperimentalFeatures) -->
     <ItemGroup>
       <AdditionalFiles Include=".publicApi\Stable\PublicAPI.*.txt" />

docs/diagnostics/experimental-apis/OTEL1000.md

@@ -7,6 +7,8 @@ This is an Experimental API diagnostic covering the following APIs:
 * `LoggerProviderBuilder`
 * `LoggerProvider`
 * `IDeferredLoggerProviderBuilder`
+* `ILoggingBuilder.UseOpenTelemetry`
+* `OpenTelemetryBuilder.WithLogging`
 
 Experimental APIs may be changed or removed in the future.
 

docs/diagnostics/experimental-apis/OTEL1001.md

@@ -9,6 +9,7 @@ This is an Experimental API diagnostic covering the following APIs:
 * `LogRecordAttributeList`
 * `LogRecordData`
 * `LogRecordSeverity`
+* `Sdk.CreateLoggerProviderBuilder`
 
 Experimental APIs may be changed or removed in the future.
 

docs/logs/complex-objects/Program.cs

@@ -6,7 +6,7 @@
 
 var loggerFactory = LoggerFactory.Create(builder =>
 {
-    builder.AddOpenTelemetry(logging =>
+    builder.UseOpenTelemetry(logging =>
     {
         logging.AddConsoleExporter();
     });

docs/logs/correlation/Program.cs

@@ -20,7 +20,7 @@ public static void Main()
 
         var loggerFactory = LoggerFactory.Create(builder =>
         {
-            builder.AddOpenTelemetry(logging =>
+            builder.UseOpenTelemetry(logging =>
             {
                 logging.AddConsoleExporter();
             });

docs/logs/customizing-the-sdk/Program.cs

@@ -7,14 +7,15 @@
 
 var loggerFactory = LoggerFactory.Create(builder =>
 {
-    builder.AddOpenTelemetry(logging =>
-    {
-        logging.IncludeScopes = true;
-        logging.SetResourceBuilder(ResourceBuilder.CreateDefault().AddService(
-            serviceName: "MyService",
-            serviceVersion: "1.0.0"));
-        logging.AddConsoleExporter();
-    });
+    builder.UseOpenTelemetry(
+        logging =>
+        {
+            logging.SetResourceBuilder(ResourceBuilder.CreateDefault().AddService(
+                serviceName: "MyService",
+                serviceVersion: "1.0.0"));
+            logging.AddConsoleExporter();
+        },
+        options => options.IncludeScopes = true);
 });
 
 var logger = loggerFactory.CreateLogger<Program>();

docs/logs/dedicated-pipeline/DedicatedLogging/DedicatedLoggingServiceCollectionExtensions.cs

@@ -11,7 +11,7 @@ public static class DedicatedLoggingServiceCollectionExtensions
     public static IServiceCollection AddDedicatedLogging(
         this IServiceCollection services,
         IConfiguration configuration,
-        Action<OpenTelemetryLoggerOptions> configureOpenTelemetry)
+        Action<LoggerProviderBuilder> configureOpenTelemetry)
     {
         ArgumentNullException.ThrowIfNull(configureOpenTelemetry);
 
@@ -21,7 +21,7 @@ public static IServiceCollection AddDedicatedLogging(
             {
                 builder.AddConfiguration(configuration);
 
-                builder.AddOpenTelemetry(configureOpenTelemetry);
+                builder.UseOpenTelemetry(configureOpenTelemetry);
             });
 
             return new DedicatedLoggerFactory(loggerFactory);

docs/logs/dedicated-pipeline/Program.cs

@@ -8,10 +8,10 @@
 
 builder.Logging.ClearProviders();
 
-builder.Logging.AddOpenTelemetry(options =>
+builder.Logging.UseOpenTelemetry(builder =>
 {
     // Set up primary pipeline for common app logs
-    options.AddConsoleExporter();
+    builder.AddConsoleExporter();
 });
 
 builder.Services.AddDedicatedLogging(

docs/logs/extending-the-sdk/LoggerExtensions.cs

@@ -6,13 +6,13 @@
 
 internal static class LoggerExtensions
 {
-    public static OpenTelemetryLoggerOptions AddMyExporter(this OpenTelemetryLoggerOptions options)
+    public static LoggerProviderBuilder AddMyExporter(this LoggerProviderBuilder builder)
     {
-        if (options == null)
+        if (builder == null)
         {
-            throw new ArgumentNullException(nameof(options));
+            throw new ArgumentNullException(nameof(builder));
         }
 
-        return options.AddProcessor(new BatchLogRecordExportProcessor(new MyExporter()));
+        return builder.AddProcessor(new BatchLogRecordExportProcessor(new MyExporter()));
     }
 }

docs/logs/extending-the-sdk/Program.cs

@@ -3,6 +3,7 @@
 
 using Microsoft.Extensions.Logging;
 using OpenTelemetry;
+using OpenTelemetry.Logs;
 
 namespace ExtendingTheSdk;
 
@@ -11,14 +12,13 @@ public class Program
     public static void Main()
     {
         using var loggerFactory = LoggerFactory.Create(builder =>
-            builder.AddOpenTelemetry(options =>
-            {
-                options.IncludeScopes = true;
-                options.AddProcessor(new MyProcessor("ProcessorA"))
-                       .AddProcessor(new MyProcessor("ProcessorB"))
-                       .AddProcessor(new SimpleLogRecordExportProcessor(new MyExporter("ExporterX")))
-                       .AddMyExporter();
-            }));
+            builder.UseOpenTelemetry(
+                logging => logging
+                    .AddProcessor(new MyProcessor("ProcessorA"))
+                    .AddProcessor(new MyProcessor("ProcessorB"))
+                    .AddProcessor(new SimpleLogRecordExportProcessor(new MyExporter("ExporterX")))
+                    .AddMyExporter(),
+                options => options.IncludeScopes = true));
 
         var logger = loggerFactory.CreateLogger<Program>();
 

docs/logs/getting-started-aspnetcore/Program.cs

@@ -13,13 +13,14 @@
 // clear these providers.
 builder.Logging.ClearProviders();
 
-builder.Logging.AddOpenTelemetry(logging =>
+builder.Logging.UseOpenTelemetry(logging =>
 {
     var resourceBuilder = ResourceBuilder
         .CreateDefault()
         .AddService(builder.Environment.ApplicationName);
 
-    logging.SetResourceBuilder(resourceBuilder)
+    logging
+        .SetResourceBuilder(resourceBuilder)
 
         // ConsoleExporter is used for demo purpose only.
         // In production environment, ConsoleExporter should be replaced with other exporters (e.g. OTLP Exporter).

docs/logs/getting-started-console/Program.cs

@@ -6,7 +6,7 @@
 
 var loggerFactory = LoggerFactory.Create(builder =>
 {
-    builder.AddOpenTelemetry(logging =>
+    builder.UseOpenTelemetry(logging =>
     {
         logging.AddConsoleExporter();
     });

docs/logs/redaction/Program.cs

@@ -6,7 +6,7 @@
 
 var loggerFactory = LoggerFactory.Create(builder =>
 {
-    builder.AddOpenTelemetry(logging =>
+    builder.UseOpenTelemetry(logging =>
     {
         logging.AddProcessor(new MyRedactionProcessor());
         logging.AddConsoleExporter();

docs/resources/extending-the-sdk/Program.cs

@@ -5,6 +5,7 @@
 using System.Diagnostics.Metrics;
 using Microsoft.Extensions.Logging;
 using OpenTelemetry;
+using OpenTelemetry.Logs;
 using OpenTelemetry.Metrics;
 using OpenTelemetry.Resources;
 using OpenTelemetry.Trace;
@@ -31,9 +32,9 @@ public static void Main()
 
         using var loggerFactory = LoggerFactory.Create(builder =>
         {
-            builder.AddOpenTelemetry(options =>
+            builder.UseOpenTelemetry(logging =>
             {
-                options.SetResourceBuilder(ResourceBuilder.CreateDefault().AddDetector(
+                logging.SetResourceBuilder(ResourceBuilder.CreateDefault().AddDetector(
                     new MyResourceDetector()));
             });
         });

examples/AspNetCore/Program.cs

@@ -34,7 +34,10 @@
 // for manual instrumentation
 appBuilder.Services.AddSingleton<Instrumentation>();
 
-// Configure OpenTelemetry tracing & metrics with auto-start using the
+// Clear default logging providers used by WebApplication host.
+appBuilder.Logging.ClearProviders();
+
+// Configure OpenTelemetry logging, metrics, & tracing with auto-start using the
 // AddOpenTelemetry extension from OpenTelemetry.Extensions.Hosting.
 appBuilder.Services.AddOpenTelemetry()
     .ConfigureResource(configureResource)
@@ -121,34 +124,29 @@
                 builder.AddConsoleExporter();
                 break;
         }
-    });
-
-// Clear default logging providers used by WebApplication host.
-appBuilder.Logging.ClearProviders();
-
-// Configure OpenTelemetry Logging.
-appBuilder.Logging.AddOpenTelemetry(options =>
-{
-    // Note: See appsettings.json Logging:OpenTelemetry section for configuration.
+    })
+    .WithLogging(builder =>
+    {
+        // Note: See appsettings.json Logging:OpenTelemetry section for configuration.
 
-    var resourceBuilder = ResourceBuilder.CreateDefault();
-    configureResource(resourceBuilder);
-    options.SetResourceBuilder(resourceBuilder);
+        var resourceBuilder = ResourceBuilder.CreateDefault();
+        configureResource(resourceBuilder);
+        builder.SetResourceBuilder(resourceBuilder);
 
-    switch (logExporter)
-    {
-        case "otlp":
-            options.AddOtlpExporter(otlpOptions =>
-            {
-                // Use IConfiguration directly for Otlp exporter endpoint option.
-                otlpOptions.Endpoint = new Uri(appBuilder.Configuration.GetValue("Otlp:Endpoint", defaultValue: "http://localhost:4317")!);
-            });
-            break;
-        default:
-            options.AddConsoleExporter();
-            break;
-    }
-});
+        switch (logExporter)
+        {
+            case "otlp":
+                builder.AddOtlpExporter(otlpOptions =>
+                {
+                    // Use IConfiguration directly for Otlp exporter endpoint option.
+                    otlpOptions.Endpoint = new Uri(appBuilder.Configuration.GetValue("Otlp:Endpoint", defaultValue: "http://localhost:4317")!);
+                });
+                break;
+            default:
+                builder.AddConsoleExporter();
+                break;
+        }
+    });
 
 appBuilder.Services.AddControllers();
 

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

@@ -1,9 +0,0 @@
-OpenTelemetry.Logs.OpenTelemetryDependencyInjectionLoggerProviderBuilderExtensions
-OpenTelemetry.Logs.OpenTelemetryDependencyInjectionLoggingServiceCollectionExtensions
-static OpenTelemetry.Logs.OpenTelemetryDependencyInjectionLoggerProviderBuilderExtensions.AddInstrumentation<T>(this OpenTelemetry.Logs.LoggerProviderBuilder! loggerProviderBuilder) -> OpenTelemetry.Logs.LoggerProviderBuilder!
-static OpenTelemetry.Logs.OpenTelemetryDependencyInjectionLoggerProviderBuilderExtensions.AddInstrumentation<T>(this OpenTelemetry.Logs.LoggerProviderBuilder! loggerProviderBuilder, System.Func<System.IServiceProvider!, OpenTelemetry.Logs.LoggerProvider!, T!>! instrumentationFactory) -> OpenTelemetry.Logs.LoggerProviderBuilder!
-static OpenTelemetry.Logs.OpenTelemetryDependencyInjectionLoggerProviderBuilderExtensions.AddInstrumentation<T>(this OpenTelemetry.Logs.LoggerProviderBuilder! loggerProviderBuilder, System.Func<System.IServiceProvider!, T!>! instrumentationFactory) -> OpenTelemetry.Logs.LoggerProviderBuilder!
-static OpenTelemetry.Logs.OpenTelemetryDependencyInjectionLoggerProviderBuilderExtensions.AddInstrumentation<T>(this OpenTelemetry.Logs.LoggerProviderBuilder! loggerProviderBuilder, T! instrumentation) -> OpenTelemetry.Logs.LoggerProviderBuilder!
-static OpenTelemetry.Logs.OpenTelemetryDependencyInjectionLoggerProviderBuilderExtensions.ConfigureServices(this OpenTelemetry.Logs.LoggerProviderBuilder! loggerProviderBuilder, System.Action<Microsoft.Extensions.DependencyInjection.IServiceCollection!>! configure) -> OpenTelemetry.Logs.LoggerProviderBuilder!
-static OpenTelemetry.Logs.OpenTelemetryDependencyInjectionLoggingServiceCollectionExtensions.ConfigureOpenTelemetryLoggerProvider(this Microsoft.Extensions.DependencyInjection.IServiceCollection! services, System.Action<OpenTelemetry.Logs.LoggerProviderBuilder!>! configure) -> Microsoft.Extensions.DependencyInjection.IServiceCollection!
-static OpenTelemetry.Logs.OpenTelemetryDependencyInjectionLoggingServiceCollectionExtensions.ConfigureOpenTelemetryLoggerProvider(this Microsoft.Extensions.DependencyInjection.IServiceCollection! services, System.Action<System.IServiceProvider!, OpenTelemetry.Logs.LoggerProviderBuilder!>! configure) -> Microsoft.Extensions.DependencyInjection.IServiceCollection!

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

@@ -0,0 +1,9 @@
+OpenTelemetry.Logs.OpenTelemetryDependencyInjectionLoggerProviderBuilderExtensions
+OpenTelemetry.Logs.OpenTelemetryDependencyInjectionLoggingServiceCollectionExtensions
+static OpenTelemetry.Logs.OpenTelemetryDependencyInjectionLoggerProviderBuilderExtensions.AddInstrumentation<T>(this OpenTelemetry.Logs.LoggerProviderBuilder! loggerProviderBuilder) -> OpenTelemetry.Logs.LoggerProviderBuilder!
+static OpenTelemetry.Logs.OpenTelemetryDependencyInjectionLoggerProviderBuilderExtensions.AddInstrumentation<T>(this OpenTelemetry.Logs.LoggerProviderBuilder! loggerProviderBuilder, System.Func<System.IServiceProvider!, OpenTelemetry.Logs.LoggerProvider!, T!>! instrumentationFactory) -> OpenTelemetry.Logs.LoggerProviderBuilder!
+static OpenTelemetry.Logs.OpenTelemetryDependencyInjectionLoggerProviderBuilderExtensions.AddInstrumentation<T>(this OpenTelemetry.Logs.LoggerProviderBuilder! loggerProviderBuilder, System.Func<System.IServiceProvider!, T!>! instrumentationFactory) -> OpenTelemetry.Logs.LoggerProviderBuilder!
+static OpenTelemetry.Logs.OpenTelemetryDependencyInjectionLoggerProviderBuilderExtensions.AddInstrumentation<T>(this OpenTelemetry.Logs.LoggerProviderBuilder! loggerProviderBuilder, T! instrumentation) -> OpenTelemetry.Logs.LoggerProviderBuilder!
+static OpenTelemetry.Logs.OpenTelemetryDependencyInjectionLoggerProviderBuilderExtensions.ConfigureServices(this OpenTelemetry.Logs.LoggerProviderBuilder! loggerProviderBuilder, System.Action<Microsoft.Extensions.DependencyInjection.IServiceCollection!>! configure) -> OpenTelemetry.Logs.LoggerProviderBuilder!
+static OpenTelemetry.Logs.OpenTelemetryDependencyInjectionLoggingServiceCollectionExtensions.ConfigureOpenTelemetryLoggerProvider(this Microsoft.Extensions.DependencyInjection.IServiceCollection! services, System.Action<OpenTelemetry.Logs.LoggerProviderBuilder!>! configure) -> Microsoft.Extensions.DependencyInjection.IServiceCollection!
+static OpenTelemetry.Logs.OpenTelemetryDependencyInjectionLoggingServiceCollectionExtensions.ConfigureOpenTelemetryLoggerProvider(this Microsoft.Extensions.DependencyInjection.IServiceCollection! services, System.Action<System.IServiceProvider!, OpenTelemetry.Logs.LoggerProviderBuilder!>! configure) -> Microsoft.Extensions.DependencyInjection.IServiceCollection!

src/OpenTelemetry.Api.ProviderBuilderExtensions/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## Unreleased
 
+* The experimental APIs previously covered by `OTEL1000`
+  (`LoggerProviderBuilder` `AddInstrumentation` & `ConfigureServices` extensions
+  and `IServiceCollection.ConfigureOpenTelemetryLoggerProvider` extension) will
+  now be part of the public API and supported in stable builds.
+  ([#5648](https://github.com/open-telemetry/opentelemetry-dotnet/pull/5648))
+
 ## 1.9.0-alpha.1
 
 Released 2024-May-20