[api-logs] Define OTEL1000 & OTEL1001 diagnostics and decorate APIs

OpenTelemetry.sln

@@ -90,8 +90,8 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "ISSUE_TEMPLATE", "ISSUE_TEM
 EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "workflows", "workflows", "{E69578EB-B456-4062-A645-877CD964528B}"
 	ProjectSection(SolutionItems) = preProject
-		.github\workflows\ci-aot.yml = .github\workflows\ci-aot.yml
 		.github\workflows\ci-aot-md.yml = .github\workflows\ci-aot-md.yml
+		.github\workflows\ci-aot.yml = .github\workflows\ci-aot.yml
 		.github\workflows\ci-instrumentation-libraries-md.yml = .github\workflows\ci-instrumentation-libraries-md.yml
 		.github\workflows\ci-instrumentation-libraries.yml = .github\workflows\ci-instrumentation-libraries.yml
 		.github\workflows\ci-md.yml = .github\workflows\ci-md.yml
@@ -315,6 +315,12 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Metrics", "Metrics", "{1C45
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "getting-started-aspnetcore", "docs\logs\getting-started-aspnetcore\getting-started-aspnetcore.csproj", "{99B4D965-8782-4694-8DFA-B7A3630CEF60}"
 EndProject
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "diagnostics", "diagnostics", "{52AF6D7D-9E66-4234-9A2C-5D16C6F22B40}"
+	ProjectSection(SolutionItems) = preProject
+		docs\diagnostics\OT1000.md = docs\diagnostics\OT1000.md
+		docs\diagnostics\OT1001.md = docs\diagnostics\OT1001.md
+	EndProjectSection
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -637,6 +643,7 @@ Global
 		{A0CB9A10-F22D-4E66-A449-74B3D0361A9C} = {A49299FB-C5CD-4E0E-B7E1-B7867BBD67CC}
 		{1C459B5B-C702-46FF-BF1A-EE795E420FFA} = {A49299FB-C5CD-4E0E-B7E1-B7867BBD67CC}
 		{99B4D965-8782-4694-8DFA-B7A3630CEF60} = {3862190B-E2C5-418E-AFDC-DB281FB5C705}
+		{52AF6D7D-9E66-4234-9A2C-5D16C6F22B40} = {7C87CAF9-79D7-4C26-9FFB-F3F1FB6911F1}
 	EndGlobalSection
 	GlobalSection(ExtensibilityGlobals) = postSolution
 		SolutionGuid = {55639B5C-0770-4A22-AB56-859604650521}

build/Common.props

@@ -9,6 +9,8 @@
     <GenerateDocumentationFile>true</GenerateDocumentationFile>
     <Nullable>enable</Nullable>
     <ImplicitUsings>enable</ImplicitUsings>
+    <!-- Suppress warnings for repo code using experimental features -->
+    <NoWarn>$(NoWarn);OT1000;OT1001</NoWarn>
     <!--temporarily disable. See 3958-->
     <!--<AnalysisLevel>latest-All</AnalysisLevel>-->
   </PropertyGroup>

docs/diagnostics/OT1000.md

@@ -0,0 +1,42 @@
+# OpenTelemetry .NET Diagnostic: OT1000
+
+## Overview
+
+This is an experimental feature diagnostic covering the following APIs:
+
+* `LoggerProviderBuilder`
+* `LoggerProvider`
+* `IDeferredLoggerProviderBuilder`
+
+Experimental features may be changed or removed in the future.
+
+## Details
+
+The OpenTelemetry Specification defines a `LoggerProvider` as part of its
+[API](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/bridge-api.md)
+&
+[SDK](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/sdk.md)
+components.
+
+The SDK allows calling `Shutdown` and `ForceFlush` on the `LoggerProvider` and
+also allows processors to be added dynamically to a pipeline after its creation.
+
+Today the OpenTelemetry .NET log pipeline is built on top of the
+Microsoft.Extensions.Logging `ILogger` \ `ILoggerProvider` \ `ILoggerFactory`
+APIs which do not expose such features.
+
+We also have an issue with the `ILoggingBuilder.AddOpenTelemetry` API in that it
+interacts with the `OpenTelemetryLoggerOptions` class. Options classes are NOT
+available until the `IServiceProvider` is available and services can no longer
+be registered at that point. This prevents the current logging pipeline from
+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 Bride API
+
+The OpenTelemetry Specification defines a log bridge API which is rooted off of
+the `LoggerProvider` (`GetLogger`) and exposes a `Logger` API to submit log
+records. See [OT1001](.\OT1001.md) for details about the log bridge
+implementation status.

docs/diagnostics/OT1001.md

@@ -0,0 +1,34 @@
+# OpenTelemetry .NET Diagnostic: OT1001
+
+## Overview
+
+This is an experimental feature diagnostic covering the following APIs:
+
+* `LoggerProvider.GetLogger`
+* `Logger`
+* `LogRecordAttributeList`
+* `LogRecordData`
+* `LogRecordSeverity`
+
+Experimental features may be changed or removed in the future.
+
+## Details
+
+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.
+
+Today the OpenTelemetry .NET log pipeline is built on top of the
+Microsoft.Extensions.Logging `ILogger` \ `ILoggerProvider` \ `ILoggerFactory`
+APIs.
+
+We are exposing these APIs gather feedback about their usefulness. An
+alternative approach may be taken which would be to append into `ILogger`
+instead of OpenTelemetry directly.
+
+## LoggerProvider API
+
+The OpenTelemetry Specification defines a `LoggerProvider` API. See
+[OT1000](.\OT1001.md) for details about the log implementation status.

docs/metrics/exemplars/docker-compose.yaml

@@ -48,4 +48,3 @@ services:
       - GF_FEATURE_TOGGLES_ENABLE=traceqlEditor
     ports:
       - "3000:3000"
-

src/OpenTelemetry.Api/Logs/IDeferredLoggerProviderBuilder.cs

@@ -16,6 +16,10 @@
 
 #nullable enable
 
+#if NET8_0_OR_GREATER
+using System.Diagnostics.CodeAnalysis;
+#endif
+
 namespace OpenTelemetry.Logs;
 
 #if EXPOSE_EXPERIMENTAL_FEATURES
@@ -25,6 +29,9 @@
 /// dependency injection.
 /// </summary>
 /// <remarks><inheritdoc cref="Logger" path="/remarks"/></remarks>
+#if NET8_0_OR_GREATER
+[Experimental("OT1000", UrlFormat = "https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/docs/diagnostics/{0}.md")]
+#endif
 public
 #else
 /// <summary>
@@ -34,7 +41,7 @@
 /// </summary>
 internal
 #endif
-    interface IDeferredLoggerProviderBuilder
+interface IDeferredLoggerProviderBuilder
 {
     /// <summary>
     /// Register a callback action to configure the <see

src/OpenTelemetry.Api/Logs/LogRecordAttributeList.cs

@@ -19,6 +19,9 @@
 using System.Collections;
 using System.ComponentModel;
 using System.Diagnostics;
+#if NET8_0_OR_GREATER
+using System.Diagnostics.CodeAnalysis;
+#endif
 using OpenTelemetry.Internal;
 using OpenTelemetry.Trace;
 
@@ -29,6 +32,9 @@
 /// Stores attributes to be added to a log message.
 /// </summary>
 /// <remarks><inheritdoc cref="Logger" path="/remarks"/></remarks>
+#if NET8_0_OR_GREATER
+[Experimental("OT1001", UrlFormat = "https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/docs/diagnostics/{0}.md")]
+#endif
 public
 #else
 /// <summary>

src/OpenTelemetry.Api/Logs/LogRecordData.cs

@@ -17,6 +17,9 @@
 #nullable enable
 
 using System.Diagnostics;
+#if NET8_0_OR_GREATER
+using System.Diagnostics.CodeAnalysis;
+#endif
 
 namespace OpenTelemetry.Logs;
 
@@ -25,6 +28,9 @@
 /// Stores details about a log message.
 /// </summary>
 /// <remarks><inheritdoc cref="Logger" path="/remarks"/></remarks>
+#if NET8_0_OR_GREATER
+[Experimental("OT1001", UrlFormat = "https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/docs/diagnostics/{0}.md")]
+#endif
 public
 #else
 /// <summary>

src/OpenTelemetry.Api/Logs/LogRecordSeverity.cs

@@ -16,13 +16,20 @@
 
 #nullable enable
 
+#if NET8_0_OR_GREATER
+using System.Diagnostics.CodeAnalysis;
+#endif
+
 namespace OpenTelemetry.Logs;
 
 #if EXPOSE_EXPERIMENTAL_FEATURES
 /// <summary>
 /// Describes the severity level of a log record.
 /// </summary>
 /// <remarks><inheritdoc cref="Logger" path="/remarks"/></remarks>
+#if NET8_0_OR_GREATER
+[Experimental("OT1001", UrlFormat = "https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/docs/diagnostics/{0}.md")]
+#endif
 public
 #else
 /// <summary>

src/OpenTelemetry.Api/Logs/LogRecordSeverityExtensions.cs

@@ -16,13 +16,20 @@
 
 #nullable enable
 
+#if NET8_0_OR_GREATER
+using System.Diagnostics.CodeAnalysis;
+#endif
+
 namespace OpenTelemetry.Logs;
 
 #if EXPOSE_EXPERIMENTAL_FEATURES
 /// <summary>
 /// Contains extension methods for the <see cref="LogRecordSeverity"/> enum.
 /// </summary>
 /// <remarks><inheritdoc cref="Logger" path="/remarks"/></remarks>
+#if NET8_0_OR_GREATER
+[Experimental("OT1001", UrlFormat = "https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/docs/diagnostics/{0}.md")]
+#endif
 public
 #else
 /// <summary>

src/OpenTelemetry.Api/Logs/Logger.cs

@@ -16,21 +16,28 @@
 
 #nullable enable
 
+#if NET8_0_OR_GREATER
+using System.Diagnostics.CodeAnalysis;
+#endif
+
 namespace OpenTelemetry.Logs;
 
 #if EXPOSE_EXPERIMENTAL_FEATURES
 /// <summary>
 /// Logger is the class responsible for creating log records.
 /// </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("OT1001", UrlFormat = "https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/docs/diagnostics/{0}.md")]
+#endif
 public
 #else
 /// <summary>
 /// Logger is the class responsible for creating log records.
 /// </summary>
 internal
 #endif
-    abstract class Logger
+abstract class Logger
 {
     /// <summary>
     /// Initializes a new instance of the <see cref="Logger"/> class.

src/OpenTelemetry.Api/Logs/LoggerProvider.cs

@@ -27,6 +27,9 @@ namespace OpenTelemetry.Logs;
 /// LoggerProvider is the entry point of the OpenTelemetry API. It provides access to <see cref="Logger"/>.
 /// </summary>
 /// <remarks><inheritdoc cref="Logger" path="/remarks"/></remarks>
+#if NET8_0_OR_GREATER
+[Experimental("OT1000", UrlFormat = "https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/docs/diagnostics/{0}.md")]
+#endif
 public
 #else
 /// <summary>
@@ -49,6 +52,9 @@ protected LoggerProvider()
     /// Gets a logger.
     /// </summary>
     /// <returns><see cref="Logger"/> instance.</returns>
+#if NET8_0_OR_GREATER
+    [Experimental("OT1001", UrlFormat = "https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/docs/diagnostics/{0}.md")]
+#endif
     public Logger GetLogger()
         => this.GetLogger(name: null, version: null);
 
@@ -57,6 +63,9 @@ public Logger GetLogger()
     /// </summary>
     /// <param name="name">Optional name identifying the instrumentation library.</param>
     /// <returns><see cref="Logger"/> instance.</returns>
+#if NET8_0_OR_GREATER
+    [Experimental("OT1001", UrlFormat = "https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/docs/diagnostics/{0}.md")]
+#endif
     public Logger GetLogger(string? name)
         => this.GetLogger(name, version: null);
 
@@ -66,6 +75,9 @@ public Logger GetLogger(string? name)
     /// <param name="name">Optional name identifying the instrumentation library.</param>
     /// <param name="version">Optional version of the instrumentation library.</param>
     /// <returns><see cref="Logger"/> instance.</returns>
+#if NET8_0_OR_GREATER
+    [Experimental("OT1001", UrlFormat = "https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/docs/diagnostics/{0}.md")]
+#endif
     public Logger GetLogger(string? name, string? version)
     {
         if (!this.TryCreateLogger(name, out var logger))
@@ -84,6 +96,9 @@ public Logger GetLogger(string? name, string? version)
     /// <param name="name">Optional name identifying the instrumentation library.</param>
     /// <param name="logger"><see cref="Logger"/>.</param>
     /// <returns><see langword="true"/> if the logger was created.</returns>
+#if NET8_0_OR_GREATER
+    [Experimental("OT1001", UrlFormat = "https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/docs/diagnostics/{0}.md")]
+#endif
     protected virtual bool TryCreateLogger(
         string? name,
 #if NETSTANDARD2_1_OR_GREATER || NET6_0_OR_GREATER

src/OpenTelemetry.Api/Logs/LoggerProviderBuilder.cs

@@ -16,13 +16,20 @@
 
 #nullable enable
 
+#if NET8_0_OR_GREATER
+using System.Diagnostics.CodeAnalysis;
+#endif
+
 namespace OpenTelemetry.Logs;
 
 #if EXPOSE_EXPERIMENTAL_FEATURES
 /// <summary>
 /// LoggerProviderBuilder base class.
 /// </summary>
 /// <remarks><inheritdoc cref="Logger" path="/remarks"/></remarks>
+#if NET8_0_OR_GREATER
+[Experimental("OT1000", UrlFormat = "https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/docs/diagnostics/{0}.md")]
+#endif
 public
 #else
 /// <summary>