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

OpenTelemetry.sln

@@ -34,7 +34,6 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "build", "build", "{7CB2F02E
 		build\docfx.cmd = build\docfx.cmd
 		build\docker-compose.net6.0.yml = build\docker-compose.net6.0.yml
 		build\docker-compose.net7.0.yml = build\docker-compose.net7.0.yml
-		build\docker-compose.net8.0.yml = build\docker-compose.net8.0.yml
 		build\finalize-publicapi.ps1 = build\finalize-publicapi.ps1
 		build\GlobalAttrExclusions.txt = build\GlobalAttrExclusions.txt
 		build\opentelemetry-icon-color.png = build\opentelemetry-icon-color.png
@@ -262,6 +261,7 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Shared", "Shared", "{A49299
 	ProjectSection(SolutionItems) = preProject
 		src\Shared\ActivityHelperExtensions.cs = src\Shared\ActivityHelperExtensions.cs
 		src\Shared\ActivityInstrumentationHelper.cs = src\Shared\ActivityInstrumentationHelper.cs
+		src\Shared\DiagnosticDefinitions.cs = src\Shared\DiagnosticDefinitions.cs
 		src\Shared\ExceptionExtensions.cs = src\Shared\ExceptionExtensions.cs
 		src\Shared\Guard.cs = src\Shared\Guard.cs
 		src\Shared\HttpSemanticConventionHelper.cs = src\Shared\HttpSemanticConventionHelper.cs
@@ -319,6 +319,13 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "getting-started-aspnetcore"
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "links-creation", "docs\trace\links-creation-with-new-activities\links-creation.csproj", "{B4856711-6D4C-4246-A686-49458D4C1301}"
 EndProject
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "diagnostics", "diagnostics", "{52AF6D7D-9E66-4234-9A2C-5D16C6F22B40}"
+	ProjectSection(SolutionItems) = preProject
+		docs\diagnostics\OTEL1000.md = docs\diagnostics\OTEL1000.md
+		docs\diagnostics\EXPERIMENTAL_APIS.md = docs\diagnostics\EXPERIMENTAL_APIS.md
+		docs\diagnostics\OTEL1001.md = docs\diagnostics\OTEL1001.md
+	EndProjectSection
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -646,6 +653,7 @@ Global
 		{1C459B5B-C702-46FF-BF1A-EE795E420FFA} = {A49299FB-C5CD-4E0E-B7E1-B7867BBD67CC}
 		{99B4D965-8782-4694-8DFA-B7A3630CEF60} = {3862190B-E2C5-418E-AFDC-DB281FB5C705}
 		{B4856711-6D4C-4246-A686-49458D4C1301} = {5B7FB835-3FFF-4BC2-99C5-A5B5FAE3C818}
+		{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);OTEL1000;OTEL1001</NoWarn>
     <!--temporarily disable. See 3958-->
     <!--<AnalysisLevel>latest-All</AnalysisLevel>-->
   </PropertyGroup>

docs/diagnostics/EXPERIMENTAL_APIS.md

@@ -0,0 +1,42 @@
+# OpenTelemetry .NET Experimental APIs
+
+This document describes experimental APIs exposed in OpenTelemetry .NET
+pre-relase builds. APIs are exposed experimentally when either the OpenTelemetry
+Specification has explicitly marked some feature as
+[experimental](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/document-status.md)
+or when the SIG members are still working through the design for a feature and
+want to solicit feedback from the community.
+
+> **Note**
+> Experimental APIs are exposed as `public` in pre-release builds and `internal`
+> in stable builds.
+
+## Active
+
+Experimental APIs available in the pre-release builds:
+
+### OTEL1000
+
+Description: `LoggerProvider` and `LoggerProviderBuilder`
+
+Details: [OTEL1000](./OTEL1000.md)
+
+### OTEL1001
+
+Description: Log Bridge API
+
+Details: [OTEL1000](./OTEL1001.md)
+
+## Inactive
+
+Experimental APIs which have been released stable or removed:
+
+<!-- When an experimental API is released or removed:
+ 1) Move the section from above down here.
+ 2) Delete the individual file from the repo and switch the link here to a
+    permalink to the last version.
+ 3) Add the version info for when the API was released stable or removed. If
+    removed add details for alternative solution or reasoning.
+-->
+
+None

docs/diagnostics/OTEL1000.md

@@ -0,0 +1,42 @@
+# OpenTelemetry .NET Diagnostic: OTEL1000
+
+## Overview
+
+This is an Experimental API diagnostic covering the following APIs:
+
+* `LoggerProviderBuilder`
+* `LoggerProvider`
+* `IDeferredLoggerProviderBuilder`
+
+Experimental APIs 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 Bridge 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 [OTEL1001](.\OTEL1001.md) for details about the Log Bridge API
+implementation status.

docs/diagnostics/OTEL1001.md

@@ -0,0 +1,35 @@
+# OpenTelemetry .NET Diagnostic: OTEL1001
+
+## Overview
+
+This is an Experimental API diagnostic covering the following APIs:
+
+* `LoggerProvider.GetLogger`
+* `Logger`
+* `LogRecordAttributeList`
+* `LogRecordData`
+* `LogRecordSeverity`
+
+Experimental APIs 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
+[OTEL1000](.\OTEL1001.md) for details about the `LoggerProvider` 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,11 @@
 
 #nullable enable
 
+#if NET8_0_OR_GREATER && EXPOSE_EXPERIMENTAL_FEATURES
+using System.Diagnostics.CodeAnalysis;
+using OpenTelemetry.Internal;
+#endif
+
 namespace OpenTelemetry.Logs;
 
 #if EXPOSE_EXPERIMENTAL_FEATURES
@@ -25,6 +30,9 @@ namespace OpenTelemetry.Logs;
 /// dependency injection.
 /// </summary>
 /// <remarks><inheritdoc cref="Logger" path="/remarks"/></remarks>
+#if NET8_0_OR_GREATER
+[Experimental(DiagnosticDefinitions.LoggerProviderExperimentalApi, UrlFormat = DiagnosticDefinitions.ExperimentalApiUrlFormat)]
+#endif
 public
 #else
 /// <summary>
@@ -34,7 +42,7 @@ namespace OpenTelemetry.Logs;
 /// </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 && EXPOSE_EXPERIMENTAL_FEATURES
+using System.Diagnostics.CodeAnalysis;
+#endif
 using OpenTelemetry.Internal;
 using OpenTelemetry.Trace;
 
@@ -29,6 +32,9 @@ namespace OpenTelemetry.Logs;
 /// Stores attributes to be added to a log message.
 /// </summary>
 /// <remarks><inheritdoc cref="Logger" path="/remarks"/></remarks>
+#if NET8_0_OR_GREATER
+[Experimental(DiagnosticDefinitions.LogBridgeApiExperimentalApi, UrlFormat = DiagnosticDefinitions.ExperimentalApiUrlFormat)]
+#endif
 public
 #else
 /// <summary>

src/OpenTelemetry.Api/Logs/LogRecordData.cs

@@ -17,6 +17,10 @@
 #nullable enable
 
 using System.Diagnostics;
+#if NET8_0_OR_GREATER && EXPOSE_EXPERIMENTAL_FEATURES
+using System.Diagnostics.CodeAnalysis;
+using OpenTelemetry.Internal;
+#endif
 
 namespace OpenTelemetry.Logs;
 
@@ -25,6 +29,9 @@ namespace OpenTelemetry.Logs;
 /// Stores details about a log message.
 /// </summary>
 /// <remarks><inheritdoc cref="Logger" path="/remarks"/></remarks>
+#if NET8_0_OR_GREATER
+[Experimental(DiagnosticDefinitions.LogBridgeApiExperimentalApi, UrlFormat = DiagnosticDefinitions.ExperimentalApiUrlFormat)]
+#endif
 public
 #else
 /// <summary>

src/OpenTelemetry.Api/Logs/LogRecordSeverity.cs

@@ -16,13 +16,21 @@
 
 #nullable enable
 
+#if NET8_0_OR_GREATER && EXPOSE_EXPERIMENTAL_FEATURES
+using System.Diagnostics.CodeAnalysis;
+using OpenTelemetry.Internal;
+#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(DiagnosticDefinitions.LogBridgeApiExperimentalApi, UrlFormat = DiagnosticDefinitions.ExperimentalApiUrlFormat)]
+#endif
 public
 #else
 /// <summary>

src/OpenTelemetry.Api/Logs/LogRecordSeverityExtensions.cs

@@ -16,13 +16,21 @@
 
 #nullable enable
 
+#if NET8_0_OR_GREATER && EXPOSE_EXPERIMENTAL_FEATURES
+using System.Diagnostics.CodeAnalysis;
+using OpenTelemetry.Internal;
+#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(DiagnosticDefinitions.LogBridgeApiExperimentalApi, UrlFormat = DiagnosticDefinitions.ExperimentalApiUrlFormat)]
+#endif
 public
 #else
 /// <summary>

src/OpenTelemetry.Api/Logs/Logger.cs

@@ -16,21 +16,29 @@
 
 #nullable enable
 
+#if NET8_0_OR_GREATER && EXPOSE_EXPERIMENTAL_FEATURES
+using System.Diagnostics.CodeAnalysis;
+using OpenTelemetry.Internal;
+#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(DiagnosticDefinitions.LogBridgeApiExperimentalApi, UrlFormat = DiagnosticDefinitions.ExperimentalApiUrlFormat)]
+#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

@@ -19,6 +19,9 @@
 #if NETSTANDARD2_1_OR_GREATER || NET6_0_OR_GREATER
 using System.Diagnostics.CodeAnalysis;
 #endif
+#if NET8_0_OR_GREATER
+using OpenTelemetry.Internal;
+#endif
 
 namespace OpenTelemetry.Logs;
 
@@ -27,6 +30,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(DiagnosticDefinitions.LoggerProviderExperimentalApi, UrlFormat = DiagnosticDefinitions.ExperimentalApiUrlFormat)]
+#endif
 public
 #else
 /// <summary>
@@ -49,6 +55,9 @@ protected LoggerProvider()
     /// Gets a logger.
     /// </summary>
     /// <returns><see cref="Logger"/> instance.</returns>
+#if NET8_0_OR_GREATER
+    [Experimental(DiagnosticDefinitions.LogBridgeApiExperimentalApi, UrlFormat = DiagnosticDefinitions.ExperimentalApiUrlFormat)]
+#endif
     public Logger GetLogger()
         => this.GetLogger(name: null, version: null);
 
@@ -57,6 +66,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(DiagnosticDefinitions.LogBridgeApiExperimentalApi, UrlFormat = DiagnosticDefinitions.ExperimentalApiUrlFormat)]
+#endif
     public Logger GetLogger(string? name)
         => this.GetLogger(name, version: null);
 
@@ -66,6 +78,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(DiagnosticDefinitions.LogBridgeApiExperimentalApi, UrlFormat = DiagnosticDefinitions.ExperimentalApiUrlFormat)]
+#endif
     public Logger GetLogger(string? name, string? version)
     {
         if (!this.TryCreateLogger(name, out var logger))
@@ -84,6 +99,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(DiagnosticDefinitions.LogBridgeApiExperimentalApi, UrlFormat = DiagnosticDefinitions.ExperimentalApiUrlFormat)]
+#endif
     protected virtual bool TryCreateLogger(
         string? name,
 #if NETSTANDARD2_1_OR_GREATER || NET6_0_OR_GREATER