[sdk-logs] ExperimentalAttribute decorations for experimental log APIs (#5151)

CodeBlanch · web-flow · commit 13791e268e9c · 2023-12-08T21:45:55.000-08:00
diff --git a/docs/diagnostics/experimental-apis/OTEL1000.md b/docs/diagnostics/experimental-apis/OTEL1000.md
@@ -34,9 +34,9 @@ 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.
 
-## Log Bridge API
+## Logs Bridge API
 
-The OpenTelemetry Specification defines a Log Bridge API which is rooted off of
+The OpenTelemetry Specification defines a Logs Bridge API which is rooted off of
 the `LoggerProvider` (`GetLogger`) and exposes a `Logger` API to submit log
-records. See [OTEL1001](./OTEL1001.md) for details about the Log Bridge API
+records. See [OTEL1001](./OTEL1001.md) for details about the Logs Bridge API
 implementation status.
diff --git a/docs/diagnostics/experimental-apis/OTEL1001.md b/docs/diagnostics/experimental-apis/OTEL1001.md
@@ -17,8 +17,8 @@ Experimental APIs may be changed or removed in the future.
 The OpenTelemetry Specification defines a [Logs Bridge
 API](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/bridge-api.md).
 
-The log bridge API is used by library authors to build log appenders which route
-messages from different log frameworks into OpenTelemetry.
+The Logs Bridge API is used by library authors to build log appenders which
+route messages from different log frameworks into OpenTelemetry.
 
 Today the OpenTelemetry .NET log pipeline is built on top of the
 Microsoft.Extensions.Logging `ILogger` \ `ILoggerProvider` \ `ILoggerFactory`
diff --git a/docs/diagnostics/experimental-apis/README.md b/docs/diagnostics/experimental-apis/README.md
@@ -23,7 +23,7 @@ Details: [OTEL1000](./OTEL1000.md)
 
 ### OTEL1001
 
-Description: Log Bridge API
+Description: Logs Bridge API
 
 Details: [OTEL1001](./OTEL1001.md)
 
diff --git a/src/OpenTelemetry.Api/Logs/LogRecordAttributeList.cs b/src/OpenTelemetry.Api/Logs/LogRecordAttributeList.cs
@@ -20,7 +20,7 @@ namespace OpenTelemetry.Logs;
 /// </summary>
 /// <remarks><inheritdoc cref="Logger" path="/remarks"/></remarks>
 #if NET8_0_OR_GREATER
-[Experimental(DiagnosticDefinitions.LogBridgeApiExperimentalApi, UrlFormat = DiagnosticDefinitions.ExperimentalApiUrlFormat)]
+[Experimental(DiagnosticDefinitions.LogsBridgeExperimentalApi, UrlFormat = DiagnosticDefinitions.ExperimentalApiUrlFormat)]
 #endif
 public
 #else
diff --git a/src/OpenTelemetry.Api/Logs/LogRecordData.cs b/src/OpenTelemetry.Api/Logs/LogRecordData.cs
@@ -17,7 +17,7 @@ namespace OpenTelemetry.Logs;
 /// </summary>
 /// <remarks><inheritdoc cref="Logger" path="/remarks"/></remarks>
 #if NET8_0_OR_GREATER
-[Experimental(DiagnosticDefinitions.LogBridgeApiExperimentalApi, UrlFormat = DiagnosticDefinitions.ExperimentalApiUrlFormat)]
+[Experimental(DiagnosticDefinitions.LogsBridgeExperimentalApi, UrlFormat = DiagnosticDefinitions.ExperimentalApiUrlFormat)]
 #endif
 public
 #else
diff --git a/src/OpenTelemetry.Api/Logs/LogRecordSeverity.cs b/src/OpenTelemetry.Api/Logs/LogRecordSeverity.cs
@@ -16,7 +16,7 @@ namespace OpenTelemetry.Logs;
 /// </summary>
 /// <remarks><inheritdoc cref="Logger" path="/remarks"/></remarks>
 #if NET8_0_OR_GREATER
-[Experimental(DiagnosticDefinitions.LogBridgeApiExperimentalApi, UrlFormat = DiagnosticDefinitions.ExperimentalApiUrlFormat)]
+[Experimental(DiagnosticDefinitions.LogsBridgeExperimentalApi, UrlFormat = DiagnosticDefinitions.ExperimentalApiUrlFormat)]
 #endif
 public
 #else
diff --git a/src/OpenTelemetry.Api/Logs/LogRecordSeverityExtensions.cs b/src/OpenTelemetry.Api/Logs/LogRecordSeverityExtensions.cs
@@ -16,7 +16,7 @@ namespace OpenTelemetry.Logs;
 /// </summary>
 /// <remarks><inheritdoc cref="Logger" path="/remarks"/></remarks>
 #if NET8_0_OR_GREATER
-[Experimental(DiagnosticDefinitions.LogBridgeApiExperimentalApi, UrlFormat = DiagnosticDefinitions.ExperimentalApiUrlFormat)]
+[Experimental(DiagnosticDefinitions.LogsBridgeExperimentalApi, UrlFormat = DiagnosticDefinitions.ExperimentalApiUrlFormat)]
 #endif
 public
 #else
diff --git a/src/OpenTelemetry.Api/Logs/Logger.cs b/src/OpenTelemetry.Api/Logs/Logger.cs
@@ -16,7 +16,7 @@ namespace OpenTelemetry.Logs;
 /// </summary>
 /// <remarks><b>WARNING</b>: This is an experimental API which might change or be removed in the future. Use at your own risk.</remarks>
 #if NET8_0_OR_GREATER
-[Experimental(DiagnosticDefinitions.LogBridgeApiExperimentalApi, UrlFormat = DiagnosticDefinitions.ExperimentalApiUrlFormat)]
+[Experimental(DiagnosticDefinitions.LogsBridgeExperimentalApi, UrlFormat = DiagnosticDefinitions.ExperimentalApiUrlFormat)]
 #endif
 public
 #else
diff --git a/src/OpenTelemetry.Api/Logs/LoggerProvider.cs b/src/OpenTelemetry.Api/Logs/LoggerProvider.cs
@@ -43,7 +43,7 @@ protected LoggerProvider()
     /// </summary>
     /// <returns><see cref="Logger"/> instance.</returns>
 #if NET8_0_OR_GREATER
-    [Experimental(DiagnosticDefinitions.LogBridgeApiExperimentalApi, UrlFormat = DiagnosticDefinitions.ExperimentalApiUrlFormat)]
+    [Experimental(DiagnosticDefinitions.LogsBridgeExperimentalApi, UrlFormat = DiagnosticDefinitions.ExperimentalApiUrlFormat)]
 #endif
     public Logger GetLogger()
         => this.GetLogger(name: null, version: null);
@@ -54,7 +54,7 @@ public Logger GetLogger()
     /// <param name="name">Optional name identifying the instrumentation library.</param>
     /// <returns><see cref="Logger"/> instance.</returns>
 #if NET8_0_OR_GREATER
-    [Experimental(DiagnosticDefinitions.LogBridgeApiExperimentalApi, UrlFormat = DiagnosticDefinitions.ExperimentalApiUrlFormat)]
+    [Experimental(DiagnosticDefinitions.LogsBridgeExperimentalApi, UrlFormat = DiagnosticDefinitions.ExperimentalApiUrlFormat)]
 #endif
     public Logger GetLogger(string? name)
         => this.GetLogger(name, version: null);
@@ -66,7 +66,7 @@ public Logger GetLogger(string? name)
     /// <param name="version">Optional version of the instrumentation library.</param>
     /// <returns><see cref="Logger"/> instance.</returns>
 #if NET8_0_OR_GREATER
-    [Experimental(DiagnosticDefinitions.LogBridgeApiExperimentalApi, UrlFormat = DiagnosticDefinitions.ExperimentalApiUrlFormat)]
+    [Experimental(DiagnosticDefinitions.LogsBridgeExperimentalApi, UrlFormat = DiagnosticDefinitions.ExperimentalApiUrlFormat)]
 #endif
     public Logger GetLogger(string? name, string? version)
     {
@@ -87,7 +87,7 @@ public Logger GetLogger(string? name, string? version)
     /// <param name="logger"><see cref="Logger"/>.</param>
     /// <returns><see langword="true"/> if the logger was created.</returns>
 #if NET8_0_OR_GREATER
-    [Experimental(DiagnosticDefinitions.LogBridgeApiExperimentalApi, UrlFormat = DiagnosticDefinitions.ExperimentalApiUrlFormat)]
+    [Experimental(DiagnosticDefinitions.LogsBridgeExperimentalApi, UrlFormat = DiagnosticDefinitions.ExperimentalApiUrlFormat)]
 #endif
     protected virtual bool TryCreateLogger(
         string? name,
diff --git a/src/OpenTelemetry/Logs/Builder/LoggerProviderBuilderExtensions.cs b/src/OpenTelemetry/Logs/Builder/LoggerProviderBuilderExtensions.cs
@@ -15,6 +15,9 @@ namespace OpenTelemetry.Logs;
 /// Contains extension methods for the <see cref="LoggerProviderBuilder"/> class.
 /// </summary>
 #if EXPOSE_EXPERIMENTAL_FEATURES
+#if NET8_0_OR_GREATER
+[Experimental(DiagnosticDefinitions.LoggerProviderExperimentalApi, UrlFormat = DiagnosticDefinitions.ExperimentalApiUrlFormat)]
+#endif
 public
 #else
 internal
diff --git a/src/OpenTelemetry/Logs/ILogger/OpenTelemetryLoggingExtensions.cs b/src/OpenTelemetry/Logs/ILogger/OpenTelemetryLoggingExtensions.cs
@@ -76,6 +76,9 @@ public static ILoggingBuilder AddOpenTelemetry(
     /// </remarks>
     /// <param name="builder">The <see cref="ILoggingBuilder"/> to use.</param>
     /// <returns>The supplied <see cref="ILoggingBuilder"/> for call chaining.</returns>
+#if NET8_0_OR_GREATER
+    [Experimental(DiagnosticDefinitions.LoggerProviderExperimentalApi, UrlFormat = DiagnosticDefinitions.ExperimentalApiUrlFormat)]
+#endif
     public
 #else
     /// <summary>
@@ -90,7 +93,7 @@ public static ILoggingBuilder AddOpenTelemetry(
     /// <returns>The supplied <see cref="ILoggingBuilder"/> for call chaining.</returns>
     internal
 #endif
-        static ILoggingBuilder UseOpenTelemetry(
+            static ILoggingBuilder UseOpenTelemetry(
         this ILoggingBuilder builder)
         => AddOpenTelemetryInternal(builder, configureBuilder: null, configureOptions: null);
 
@@ -102,6 +105,9 @@ static ILoggingBuilder UseOpenTelemetry(
     /// <param name="builder">The <see cref="ILoggingBuilder"/> to use.</param>
     /// <param name="configure">Optional <see cref="LoggerProviderBuilder"/> configuration action.</param>
     /// <returns>The supplied <see cref="ILoggingBuilder"/> for call chaining.</returns>
+#if NET8_0_OR_GREATER
+    [Experimental(DiagnosticDefinitions.LoggerProviderExperimentalApi, UrlFormat = DiagnosticDefinitions.ExperimentalApiUrlFormat)]
+#endif
     public
 #else
     /// <summary>
@@ -113,7 +119,7 @@ static ILoggingBuilder UseOpenTelemetry(
     /// <returns>The supplied <see cref="ILoggingBuilder"/> for call chaining.</returns>
     internal
 #endif
-        static ILoggingBuilder UseOpenTelemetry(
+            static ILoggingBuilder UseOpenTelemetry(
         this ILoggingBuilder builder,
         Action<LoggerProviderBuilder> configure)
     {
@@ -131,6 +137,9 @@ static ILoggingBuilder UseOpenTelemetry(
     /// <param name="configureBuilder">Optional <see cref="LoggerProviderBuilder"/> configuration action.</param>
     /// <param name="configureOptions">Optional <see cref="OpenTelemetryLoggerOptions"/> configuration action.</param>
     /// <returns>The supplied <see cref="ILoggingBuilder"/> for call chaining.</returns>
+#if NET8_0_OR_GREATER
+    [Experimental(DiagnosticDefinitions.LoggerProviderExperimentalApi, UrlFormat = DiagnosticDefinitions.ExperimentalApiUrlFormat)]
+#endif
     public
 #else
     /// <summary>
@@ -143,7 +152,7 @@ static ILoggingBuilder UseOpenTelemetry(
     /// <returns>The supplied <see cref="ILoggingBuilder"/> for call chaining.</returns>
     internal
 #endif
-        static ILoggingBuilder UseOpenTelemetry(
+            static ILoggingBuilder UseOpenTelemetry(
         this ILoggingBuilder builder,
         Action<LoggerProviderBuilder>? configureBuilder,
         Action<OpenTelemetryLoggerOptions>? configureOptions)
diff --git a/src/OpenTelemetry/Logs/LogRecord.cs b/src/OpenTelemetry/Logs/LogRecord.cs
@@ -2,6 +2,9 @@
 // SPDX-License-Identifier: Apache-2.0
 
 using System.Diagnostics;
+#if EXPOSE_EXPERIMENTAL_FEATURES && NET8_0_OR_GREATER
+using System.Diagnostics.CodeAnalysis;
+#endif
 using System.Runtime.CompilerServices;
 using Microsoft.Extensions.Logging;
 using OpenTelemetry.Internal;
@@ -277,6 +280,9 @@ public Exception? Exception
     /// known at the source.
     /// </summary>
     /// <remarks><inheritdoc cref="Sdk.CreateLoggerProviderBuilder" path="/remarks"/></remarks>
+#if NET8_0_OR_GREATER
+    [Experimental(DiagnosticDefinitions.LogsBridgeExperimentalApi, UrlFormat = DiagnosticDefinitions.ExperimentalApiUrlFormat)]
+#endif
     public
 #else
     /// <summary>
@@ -296,6 +302,9 @@ public Exception? Exception
     /// Gets or sets the log <see cref="LogRecordSeverity"/>.
     /// </summary>
     /// <remarks><inheritdoc cref="Sdk.CreateLoggerProviderBuilder" path="/remarks"/></remarks>
+#if NET8_0_OR_GREATER
+    [Experimental(DiagnosticDefinitions.LogsBridgeExperimentalApi, UrlFormat = DiagnosticDefinitions.ExperimentalApiUrlFormat)]
+#endif
     public
 #else
     /// <summary>
@@ -314,6 +323,9 @@ public Exception? Exception
     /// Gets the <see cref="Logs.Logger"/> which emitted the <see cref="LogRecord"/>.
     /// </summary>
     /// <remarks><inheritdoc cref="Sdk.CreateLoggerProviderBuilder" path="/remarks"/></remarks>
+#if NET8_0_OR_GREATER
+    [Experimental(DiagnosticDefinitions.LogsBridgeExperimentalApi, UrlFormat = DiagnosticDefinitions.ExperimentalApiUrlFormat)]
+#endif
     public Logger? Logger { get; internal set; }
 #else
     /// <summary>
diff --git a/src/OpenTelemetry/Logs/LoggerProviderExtensions.cs b/src/OpenTelemetry/Logs/LoggerProviderExtensions.cs
@@ -1,6 +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 OpenTelemetry.Internal;
 
 namespace OpenTelemetry.Logs;
@@ -9,6 +12,9 @@ namespace OpenTelemetry.Logs;
 /// Contains extension methods for the <see cref="LoggerProvider"/> class.
 /// </summary>
 #if EXPOSE_EXPERIMENTAL_FEATURES
+#if NET8_0_OR_GREATER
+[Experimental(DiagnosticDefinitions.LoggerProviderExperimentalApi, UrlFormat = DiagnosticDefinitions.ExperimentalApiUrlFormat)]
+#endif
 public
 #else
 internal
diff --git a/src/OpenTelemetry/Sdk.cs b/src/OpenTelemetry/Sdk.cs
@@ -2,6 +2,9 @@
 // SPDX-License-Identifier: Apache-2.0
 
 using System.Diagnostics;
+#if EXPOSE_EXPERIMENTAL_FEATURES && NET8_0_OR_GREATER
+using System.Diagnostics.CodeAnalysis;
+#endif
 using System.Reflection;
 using OpenTelemetry.Context.Propagation;
 using OpenTelemetry.Internal;
@@ -92,6 +95,9 @@ public static TracerProviderBuilder CreateTracerProviderBuilder()
     /// <remarks><b>WARNING</b>: This is an experimental API which might change or be removed in the future. Use at your own risk.</remarks>
     /// <returns><see cref="LoggerProviderBuilder"/> instance, which is used
     /// to build a <see cref="LoggerProvider"/>.</returns>
+#if NET8_0_OR_GREATER
+    [Experimental(DiagnosticDefinitions.LoggerProviderExperimentalApi, UrlFormat = DiagnosticDefinitions.ExperimentalApiUrlFormat)]
+#endif
     public
 #else
     /// <summary>
@@ -105,7 +111,7 @@ public static TracerProviderBuilder CreateTracerProviderBuilder()
     /// to build a <see cref="LoggerProvider"/>.</returns>
     internal
 #endif
-        static LoggerProviderBuilder CreateLoggerProviderBuilder()
+            static LoggerProviderBuilder CreateLoggerProviderBuilder()
     {
         return new LoggerProviderBuilderBase();
     }
diff --git a/src/Shared/DiagnosticDefinitions.cs b/src/Shared/DiagnosticDefinitions.cs
@@ -10,5 +10,5 @@ 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 LogBridgeApiExperimentalApi = "OTEL1001";
+    public const string LogsBridgeExperimentalApi = "OTEL1001";
 }
