From 0693b103e7f7fdc6cf643521210f856f2de81dd6 Mon Sep 17 00:00:00 2001 From: Mikel Blanchard Date: Wed, 5 Jun 2024 09:45:09 -0700 Subject: [PATCH] Moved ILoggingBuilder.UseOpenTelemetry back to experimental and removed obsoletions. --- .../diagnostics/experimental-apis/OTEL1000.md | 11 ++++-- .../ConsoleExporterLoggingExtensions.cs | 4 +- .../InMemoryExporterLoggingExtensions.cs | 2 +- .../OtlpLogExporterHelperExtensions.cs | 10 ++--- .../Experimental/PublicAPI.Unshipped.txt | 3 ++ .../.publicApi/Stable/PublicAPI.Unshipped.txt | 3 -- .../ILogger/OpenTelemetryLoggerOptions.cs | 6 +-- .../ILogger/OpenTelemetryLoggingExtensions.cs | 37 ++++++++++++++++--- src/Shared/DiagnosticDefinitions.cs | 2 +- 9 files changed, 54 insertions(+), 24 deletions(-) diff --git a/docs/diagnostics/experimental-apis/OTEL1000.md b/docs/diagnostics/experimental-apis/OTEL1000.md index 0064d112eab..f441f7212f8 100644 --- a/docs/diagnostics/experimental-apis/OTEL1000.md +++ b/docs/diagnostics/experimental-apis/OTEL1000.md @@ -4,14 +4,18 @@ This is an Experimental API diagnostic covering the following APIs: +* `ILoggingBuilder.UseOpenTelemetry` + +Experimental APIs may be changed or removed in the future. + +The following portions of `OTEL1000` were released stable in `1.9.0` and are no +longer considered experimental: + * `LoggerProviderBuilder` * `LoggerProvider` * `IDeferredLoggerProviderBuilder` -* `ILoggingBuilder.UseOpenTelemetry` * `OpenTelemetryBuilder.WithLogging` -Experimental APIs may be changed or removed in the future. - ## Details The OpenTelemetry Specification defines a `LoggerProvider` as part of its @@ -36,6 +40,7 @@ exposing the same dependency injection surface we have for traces and metrics. We are exposing these APIs to solve these issues and gather feedback about their usefulness. + ## Logs Bridge API The OpenTelemetry Specification defines a Logs Bridge API which is rooted off of diff --git a/src/OpenTelemetry.Exporter.Console/ConsoleExporterLoggingExtensions.cs b/src/OpenTelemetry.Exporter.Console/ConsoleExporterLoggingExtensions.cs index 38edefd6570..80c767343b7 100644 --- a/src/OpenTelemetry.Exporter.Console/ConsoleExporterLoggingExtensions.cs +++ b/src/OpenTelemetry.Exporter.Console/ConsoleExporterLoggingExtensions.cs @@ -15,7 +15,7 @@ public static class ConsoleExporterLoggingExtensions /// /// options to use. /// The instance of to chain the calls. - [Obsolete("Call LoggerProviderBuilder.AddConsoleExporter instead this method will be removed in a future version.")] + // TODO: [Obsolete("Call LoggerProviderBuilder.AddConsoleExporter instead this method will be removed in a future version.")] public static OpenTelemetryLoggerOptions AddConsoleExporter(this OpenTelemetryLoggerOptions loggerOptions) => AddConsoleExporter(loggerOptions, configure: null); @@ -25,7 +25,7 @@ public static OpenTelemetryLoggerOptions AddConsoleExporter(this OpenTelemetryLo /// options to use. /// Callback action for configuring . /// The instance of to chain the calls. - [Obsolete("Call LoggerProviderBuilder.AddConsoleExporter instead this method will be removed in a future version.")] + // TODO: [Obsolete("Call LoggerProviderBuilder.AddConsoleExporter instead this method will be removed in a future version.")] public static OpenTelemetryLoggerOptions AddConsoleExporter(this OpenTelemetryLoggerOptions loggerOptions, Action configure) { Guard.ThrowIfNull(loggerOptions); diff --git a/src/OpenTelemetry.Exporter.InMemory/InMemoryExporterLoggingExtensions.cs b/src/OpenTelemetry.Exporter.InMemory/InMemoryExporterLoggingExtensions.cs index 541cb80a13f..19b2079921e 100644 --- a/src/OpenTelemetry.Exporter.InMemory/InMemoryExporterLoggingExtensions.cs +++ b/src/OpenTelemetry.Exporter.InMemory/InMemoryExporterLoggingExtensions.cs @@ -14,7 +14,7 @@ public static class InMemoryExporterLoggingExtensions /// options to use. /// Collection which will be populated with the exported . /// The supplied instance of to chain the calls. - [Obsolete("Call LoggerProviderBuilder.AddInMemoryExporter instead this method will be removed in a future version.")] + // TODO: [Obsolete("Call LoggerProviderBuilder.AddInMemoryExporter instead this method will be removed in a future version.")] public static OpenTelemetryLoggerOptions AddInMemoryExporter( this OpenTelemetryLoggerOptions loggerOptions, ICollection exportedItems) diff --git a/src/OpenTelemetry.Exporter.OpenTelemetryProtocol/OtlpLogExporterHelperExtensions.cs b/src/OpenTelemetry.Exporter.OpenTelemetryProtocol/OtlpLogExporterHelperExtensions.cs index d2cc951e46a..3a994c8e772 100644 --- a/src/OpenTelemetry.Exporter.OpenTelemetryProtocol/OtlpLogExporterHelperExtensions.cs +++ b/src/OpenTelemetry.Exporter.OpenTelemetryProtocol/OtlpLogExporterHelperExtensions.cs @@ -25,7 +25,7 @@ public static class OtlpLogExporterHelperExtensions /// /// options to use. /// The instance of to chain the calls. - [Obsolete("Call LoggerProviderBuilder.AddOtlpExporter instead this method will be removed in a future version.")] + // TODO: [Obsolete("Call LoggerProviderBuilder.AddOtlpExporter instead this method will be removed in a future version.")] public static OpenTelemetryLoggerOptions AddOtlpExporter(this OpenTelemetryLoggerOptions loggerOptions) => AddOtlpExporter(loggerOptions, name: null, configure: null); @@ -35,7 +35,7 @@ public static OpenTelemetryLoggerOptions AddOtlpExporter(this OpenTelemetryLogge /// options to use. /// Callback action for configuring . /// The instance of to chain the calls. - [Obsolete("Call LoggerProviderBuilder.AddOtlpExporter instead this method will be removed in a future version.")] + // TODO: [Obsolete("Call LoggerProviderBuilder.AddOtlpExporter instead this method will be removed in a future version.")] public static OpenTelemetryLoggerOptions AddOtlpExporter( this OpenTelemetryLoggerOptions loggerOptions, Action configure) @@ -48,7 +48,7 @@ public static OpenTelemetryLoggerOptions AddOtlpExporter( /// Optional name which is used when retrieving options. /// Optional callback action for configuring . /// The instance of to chain the calls. - [Obsolete("Call LoggerProviderBuilder.AddOtlpExporter instead this method will be removed in a future version.")] + // TODO: [Obsolete("Call LoggerProviderBuilder.AddOtlpExporter instead this method will be removed in a future version.")] public static OpenTelemetryLoggerOptions AddOtlpExporter( this OpenTelemetryLoggerOptions loggerOptions, string? name, @@ -81,7 +81,7 @@ public static OpenTelemetryLoggerOptions AddOtlpExporter( /// options to use. /// Callback action for configuring and . /// The instance of to chain the calls. - [Obsolete("Call LoggerProviderBuilder.AddOtlpExporter instead this method will be removed in a future version.")] + // TODO: [Obsolete("Call LoggerProviderBuilder.AddOtlpExporter instead this method will be removed in a future version.")] public static OpenTelemetryLoggerOptions AddOtlpExporter( this OpenTelemetryLoggerOptions loggerOptions, Action configureExporterAndProcessor) @@ -94,7 +94,7 @@ public static OpenTelemetryLoggerOptions AddOtlpExporter( /// Optional name which is used when retrieving options. /// Optional callback action for configuring and . /// The instance of to chain the calls. - [Obsolete("Call LoggerProviderBuilder.AddOtlpExporter instead this method will be removed in a future version.")] + // TODO: [Obsolete("Call LoggerProviderBuilder.AddOtlpExporter instead this method will be removed in a future version.")] public static OpenTelemetryLoggerOptions AddOtlpExporter( this OpenTelemetryLoggerOptions loggerOptions, string? name, diff --git a/src/OpenTelemetry/.publicApi/Experimental/PublicAPI.Unshipped.txt b/src/OpenTelemetry/.publicApi/Experimental/PublicAPI.Unshipped.txt index e27f4f743ce..a6594de1a9c 100644 --- a/src/OpenTelemetry/.publicApi/Experimental/PublicAPI.Unshipped.txt +++ b/src/OpenTelemetry/.publicApi/Experimental/PublicAPI.Unshipped.txt @@ -22,5 +22,8 @@ OpenTelemetry.Metrics.MetricStreamConfiguration.CardinalityLimit.set -> void OpenTelemetry.Metrics.MetricStreamConfiguration.ExemplarReservoirFactory.get -> System.Func? OpenTelemetry.Metrics.MetricStreamConfiguration.ExemplarReservoirFactory.set -> void override sealed OpenTelemetry.Metrics.FixedSizeExemplarReservoir.Collect() -> OpenTelemetry.Metrics.ReadOnlyExemplarCollection +static Microsoft.Extensions.Logging.OpenTelemetryLoggingExtensions.UseOpenTelemetry(this Microsoft.Extensions.Logging.ILoggingBuilder! builder) -> Microsoft.Extensions.Logging.ILoggingBuilder! +static Microsoft.Extensions.Logging.OpenTelemetryLoggingExtensions.UseOpenTelemetry(this Microsoft.Extensions.Logging.ILoggingBuilder! builder, System.Action! configure) -> Microsoft.Extensions.Logging.ILoggingBuilder! +static Microsoft.Extensions.Logging.OpenTelemetryLoggingExtensions.UseOpenTelemetry(this Microsoft.Extensions.Logging.ILoggingBuilder! builder, System.Action? configureBuilder, System.Action? configureOptions) -> Microsoft.Extensions.Logging.ILoggingBuilder! static OpenTelemetry.Sdk.CreateLoggerProviderBuilder() -> OpenTelemetry.Logs.LoggerProviderBuilder! virtual OpenTelemetry.Metrics.FixedSizeExemplarReservoir.OnCollected() -> void diff --git a/src/OpenTelemetry/.publicApi/Stable/PublicAPI.Unshipped.txt b/src/OpenTelemetry/.publicApi/Stable/PublicAPI.Unshipped.txt index dad4760e3e3..4ebd84b69d9 100644 --- a/src/OpenTelemetry/.publicApi/Stable/PublicAPI.Unshipped.txt +++ b/src/OpenTelemetry/.publicApi/Stable/PublicAPI.Unshipped.txt @@ -27,9 +27,6 @@ OpenTelemetry.ReadOnlyFilteredTagCollection.Enumerator.Enumerator() -> void OpenTelemetry.ReadOnlyFilteredTagCollection.Enumerator.MoveNext() -> bool OpenTelemetry.ReadOnlyFilteredTagCollection.GetEnumerator() -> OpenTelemetry.ReadOnlyFilteredTagCollection.Enumerator OpenTelemetry.ReadOnlyFilteredTagCollection.ReadOnlyFilteredTagCollection() -> void -static Microsoft.Extensions.Logging.OpenTelemetryLoggingExtensions.UseOpenTelemetry(this Microsoft.Extensions.Logging.ILoggingBuilder! builder) -> Microsoft.Extensions.Logging.ILoggingBuilder! -static Microsoft.Extensions.Logging.OpenTelemetryLoggingExtensions.UseOpenTelemetry(this Microsoft.Extensions.Logging.ILoggingBuilder! builder, System.Action! configure) -> Microsoft.Extensions.Logging.ILoggingBuilder! -static Microsoft.Extensions.Logging.OpenTelemetryLoggingExtensions.UseOpenTelemetry(this Microsoft.Extensions.Logging.ILoggingBuilder! builder, System.Action? configureBuilder, System.Action? configureOptions) -> Microsoft.Extensions.Logging.ILoggingBuilder! static OpenTelemetry.OpenTelemetryBuilderSdkExtensions.WithLogging(this OpenTelemetry.IOpenTelemetryBuilder! builder) -> OpenTelemetry.IOpenTelemetryBuilder! static OpenTelemetry.OpenTelemetryBuilderSdkExtensions.WithLogging(this OpenTelemetry.IOpenTelemetryBuilder! builder, System.Action! configure) -> OpenTelemetry.IOpenTelemetryBuilder! static OpenTelemetry.OpenTelemetryBuilderSdkExtensions.WithLogging(this OpenTelemetry.IOpenTelemetryBuilder! builder, System.Action? configureBuilder, System.Action? configureOptions) -> OpenTelemetry.IOpenTelemetryBuilder! diff --git a/src/OpenTelemetry/Logs/ILogger/OpenTelemetryLoggerOptions.cs b/src/OpenTelemetry/Logs/ILogger/OpenTelemetryLoggerOptions.cs index 45282442b80..921fd948ce0 100644 --- a/src/OpenTelemetry/Logs/ILogger/OpenTelemetryLoggerOptions.cs +++ b/src/OpenTelemetry/Logs/ILogger/OpenTelemetryLoggerOptions.cs @@ -82,7 +82,7 @@ public class OpenTelemetryLoggerOptions /// /// Log processor to add. /// Returns for chaining. - [Obsolete("Use LoggerProviderBuilder.AddProcessor instead this method will be removed in a future version.")] + // TODO: [Obsolete("Use LoggerProviderBuilder.AddProcessor instead this method will be removed in a future version.")] public OpenTelemetryLoggerOptions AddProcessor(BaseProcessor processor) { Guard.ThrowIfNull(processor); @@ -97,7 +97,7 @@ public OpenTelemetryLoggerOptions AddProcessor(BaseProcessor processo /// /// The factory that creates the service. /// Returns for chaining. - [Obsolete("Use LoggerProviderBuilder.AddProcessor instead this method will be removed in a future version.")] + // TODO: [Obsolete("Use LoggerProviderBuilder.AddProcessor instead this method will be removed in a future version.")] public OpenTelemetryLoggerOptions AddProcessor( Func> implementationFactory) { @@ -114,7 +114,7 @@ public OpenTelemetryLoggerOptions AddProcessor( /// /// from which Resource will be built. /// Returns for chaining. - [Obsolete("Use LoggerProviderBuilder.SetResourceBuilder instead this method will be removed in a future version.")] + // TODO: [Obsolete("Use LoggerProviderBuilder.SetResourceBuilder instead this method will be removed in a future version.")] public OpenTelemetryLoggerOptions SetResourceBuilder(ResourceBuilder resourceBuilder) { Guard.ThrowIfNull(resourceBuilder); diff --git a/src/OpenTelemetry/Logs/ILogger/OpenTelemetryLoggingExtensions.cs b/src/OpenTelemetry/Logs/ILogger/OpenTelemetryLoggingExtensions.cs index bfe3feaf6dd..ba488b00df3 100644 --- a/src/OpenTelemetry/Logs/ILogger/OpenTelemetryLoggingExtensions.cs +++ b/src/OpenTelemetry/Logs/ILogger/OpenTelemetryLoggingExtensions.cs @@ -1,7 +1,6 @@ // Copyright The OpenTelemetry Authors // SPDX-License-Identifier: Apache-2.0 -using System.ComponentModel; using System.Diagnostics; #if NET6_0_OR_GREATER using System.Diagnostics.CodeAnalysis; @@ -37,9 +36,10 @@ public static class OpenTelemetryLoggingExtensions /// /// The to use. /// The supplied for call chaining. + /* TODO: // Note: We hide AddOpenTelemetry from IDEs using EditorBrowsable when UseOpenTelemetry is present to reduce confusion. [EditorBrowsable(EditorBrowsableState.Never)] - [Obsolete("Call UseOpenTelemetry instead this method will be removed in a future version.")] + [Obsolete("Call UseOpenTelemetry instead this method will be removed in a future version.")] */ public static ILoggingBuilder AddOpenTelemetry( this ILoggingBuilder builder) => AddOpenTelemetryInternal(builder, configureBuilder: null, configureOptions: null); @@ -51,14 +51,16 @@ public static ILoggingBuilder AddOpenTelemetry( /// The to use. /// Optional configuration action. /// The supplied for call chaining. + /* TODO: // Note: We hide AddOpenTelemetry from IDEs using EditorBrowsable when UseOpenTelemetry is present to reduce confusion. [EditorBrowsable(EditorBrowsableState.Never)] - [Obsolete("Call UseOpenTelemetry instead this method will be removed in a future version.")] + [Obsolete("Call UseOpenTelemetry instead this method will be removed in a future version.")]*/ public static ILoggingBuilder AddOpenTelemetry( this ILoggingBuilder builder, Action? configure) => AddOpenTelemetryInternal(builder, configureBuilder: null, configureOptions: configure); +#if EXPOSE_EXPERIMENTAL_FEATURES /// /// Adds an OpenTelemetry logger named 'OpenTelemetry' to the . /// @@ -69,10 +71,18 @@ public static ILoggingBuilder AddOpenTelemetry( /// /// The to use. /// The supplied for call chaining. - public static ILoggingBuilder UseOpenTelemetry( +#if NET8_0_OR_GREATER + [Experimental(DiagnosticDefinitions.LoggerProviderExperimentalApi, UrlFormat = DiagnosticDefinitions.ExperimentalApiUrlFormat)] +#endif + public +#else + internal +#endif + static ILoggingBuilder UseOpenTelemetry( this ILoggingBuilder builder) => AddOpenTelemetryInternal(builder, configureBuilder: null, configureOptions: null); +#if EXPOSE_EXPERIMENTAL_FEATURES /// /// Adds an OpenTelemetry logger named 'OpenTelemetry' to the . /// @@ -80,7 +90,14 @@ public static ILoggingBuilder UseOpenTelemetry( /// The to use. /// configuration action. /// The supplied for call chaining. - public static ILoggingBuilder UseOpenTelemetry( +#if NET8_0_OR_GREATER + [Experimental(DiagnosticDefinitions.LoggerProviderExperimentalApi, UrlFormat = DiagnosticDefinitions.ExperimentalApiUrlFormat)] +#endif + public +#else + internal +#endif + static ILoggingBuilder UseOpenTelemetry( this ILoggingBuilder builder, Action configure) { @@ -89,6 +106,7 @@ public static ILoggingBuilder UseOpenTelemetry( return AddOpenTelemetryInternal(builder, configureBuilder: configure, configureOptions: null); } +#if EXPOSE_EXPERIMENTAL_FEATURES /// /// Adds an OpenTelemetry logger named 'OpenTelemetry' to the . /// @@ -97,7 +115,14 @@ public static ILoggingBuilder UseOpenTelemetry( /// Optional configuration action. /// Optional configuration action. /// The supplied for call chaining. - public static ILoggingBuilder UseOpenTelemetry( +#if NET8_0_OR_GREATER + [Experimental(DiagnosticDefinitions.LoggerProviderExperimentalApi, UrlFormat = DiagnosticDefinitions.ExperimentalApiUrlFormat)] +#endif + public +#else + internal +#endif + static ILoggingBuilder UseOpenTelemetry( this ILoggingBuilder builder, Action? configureBuilder, Action? configureOptions) diff --git a/src/Shared/DiagnosticDefinitions.cs b/src/Shared/DiagnosticDefinitions.cs index 3975c312b0c..94bf1c5f52d 100644 --- a/src/Shared/DiagnosticDefinitions.cs +++ b/src/Shared/DiagnosticDefinitions.cs @@ -9,12 +9,12 @@ internal static class DiagnosticDefinitions { public const string ExperimentalApiUrlFormat = "https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/docs/diagnostics/experimental-apis/README.md#{0}"; + public const string LoggerProviderExperimentalApi = "OTEL1000"; public const string LogsBridgeExperimentalApi = "OTEL1001"; public const string CardinalityLimitExperimentalApi = "OTEL1003"; public const string ExemplarReservoirExperimentalApi = "OTEL1004"; /* Definitions which have been released stable: - public const string LoggerProviderExperimentalApi = "OTEL1000"; public const string ExemplarExperimentalApi = "OTEL1002"; */ }