[sdk-metrics] ExperimentalAttribute decorations for experimental exemplar APIs (#5153)

Co-authored-by: Utkarsh Umesan Pillai <66651184+utpilla@users.noreply.github.com>

OpenTelemetry.sln

@@ -332,6 +332,7 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "experimental-apis", "experi
 	ProjectSection(SolutionItems) = preProject
 		docs\diagnostics\experimental-apis\OTEL1000.md = docs\diagnostics\experimental-apis\OTEL1000.md
 		docs\diagnostics\experimental-apis\OTEL1001.md = docs\diagnostics\experimental-apis\OTEL1001.md
+		docs\diagnostics\experimental-apis\OTEL1002.md = docs\diagnostics\experimental-apis\OTEL1002.md
 		docs\diagnostics\experimental-apis\README.md = docs\diagnostics\experimental-apis\README.md
 	EndProjectSection
 EndProject

build/Common.props

@@ -10,7 +10,7 @@
     <Nullable>enable</Nullable>
     <ImplicitUsings>enable</ImplicitUsings>
     <!-- Suppress warnings for repo code using experimental features -->
-    <NoWarn>$(NoWarn);OTEL1000;OTEL1001</NoWarn>
+    <NoWarn>$(NoWarn);OTEL1000;OTEL1001;OTEL1002</NoWarn>
     <!--temporarily disable. See 3958-->
     <!--<AnalysisLevel>latest-All</AnalysisLevel>-->
   </PropertyGroup>

docs/diagnostics/experimental-apis/OTEL1002.md

@@ -0,0 +1,30 @@
+# OpenTelemetry .NET Diagnostic: OTEL1002
+
+## Overview
+
+This is an Experimental API diagnostic covering the following APIs:
+
+* `AlwaysOnExemplarFilter`
+* `AlwaysOffExemplarFilter`
+* `Exemplar`
+* `ExemplarFilter`
+* `MeterProviderBuilder.SetExemplarFilter` extension method
+* `TraceBasedExemplarFilter`
+
+Experimental APIs may be changed or removed in the future.
+
+## Details
+
+The OpenTelemetry Specification defines an [Exemplar
+API](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/sdk.md#exemplar)
+in the Metrics SDK.
+
+From the specification:
+
+> Exemplars are example data points for aggregated data. They provide specific
+> context to otherwise general aggregations. Exemplars allow correlation between
+> aggregated metric data and the original API calls where measurements are
+> recorded.
+
+We are exposing these APIs experimentally until the specification declares them
+stable.

docs/diagnostics/experimental-apis/README.md

@@ -27,6 +27,12 @@ Description: Logs Bridge API
 
 Details: [OTEL1001](./OTEL1001.md)
 
+### OTEL1002
+
+Description: Metrics Exemplar Support
+
+Details: [OTEL1002](./OTEL1002.md)
+
 ## Inactive
 
 Experimental APIs which have been released stable or removed:

src/OpenTelemetry/Metrics/Builder/MeterProviderBuilderExtensions.cs

@@ -323,6 +323,9 @@ public static class MeterProviderBuilderExtensions
     /// <param name="meterProviderBuilder"><see cref="MeterProviderBuilder"/>.</param>
     /// <param name="exemplarFilter"><see cref="ExemplarFilter"/> ExemplarFilter to use.</param>
     /// <returns>The supplied <see cref="MeterProviderBuilder"/> for chaining.</returns>
+#if NET8_0_OR_GREATER
+    [Experimental(DiagnosticDefinitions.ExemplarExperimentalApi, UrlFormat = DiagnosticDefinitions.ExperimentalApiUrlFormat)]
+#endif
     public
 #else
     /// <summary>
@@ -334,7 +337,7 @@ public static class MeterProviderBuilderExtensions
     /// <returns>The supplied <see cref="MeterProviderBuilder"/> for chaining.</returns>
     internal
 #endif
-        static MeterProviderBuilder SetExemplarFilter(this MeterProviderBuilder meterProviderBuilder, ExemplarFilter exemplarFilter)
+            static MeterProviderBuilder SetExemplarFilter(this MeterProviderBuilder meterProviderBuilder, ExemplarFilter exemplarFilter)
     {
         Guard.ThrowIfNull(exemplarFilter);
 

src/OpenTelemetry/Metrics/Exemplar/AlwaysOffExemplarFilter.cs

@@ -1,6 +1,11 @@
 // Copyright The OpenTelemetry Authors
 // SPDX-License-Identifier: Apache-2.0
 
+#if EXPOSE_EXPERIMENTAL_FEATURES && NET8_0_OR_GREATER
+using System.Diagnostics.CodeAnalysis;
+using OpenTelemetry.Internal;
+#endif
+
 namespace OpenTelemetry.Metrics;
 
 #if EXPOSE_EXPERIMENTAL_FEATURES
@@ -9,6 +14,9 @@ namespace OpenTelemetry.Metrics;
 /// Using this ExemplarFilter is as good as disabling Exemplar feature.
 /// </summary>
 /// <remarks><inheritdoc cref="Exemplar" path="/remarks"/></remarks>
+#if NET8_0_OR_GREATER
+[Experimental(DiagnosticDefinitions.ExemplarExperimentalApi, UrlFormat = DiagnosticDefinitions.ExperimentalApiUrlFormat)]
+#endif
 public
 #else
 /// <summary>
@@ -17,7 +25,7 @@ public
 /// </summary>
 internal
 #endif
-    sealed class AlwaysOffExemplarFilter : ExemplarFilter
+sealed class AlwaysOffExemplarFilter : ExemplarFilter
 {
     /// <inheritdoc/>
     public override bool ShouldSample(long value, ReadOnlySpan<KeyValuePair<string, object?>> tags)

src/OpenTelemetry/Metrics/Exemplar/AlwaysOnExemplarFilter.cs

@@ -1,6 +1,11 @@
 // Copyright The OpenTelemetry Authors
 // SPDX-License-Identifier: Apache-2.0
 
+#if EXPOSE_EXPERIMENTAL_FEATURES && NET8_0_OR_GREATER
+using System.Diagnostics.CodeAnalysis;
+using OpenTelemetry.Internal;
+#endif
+
 namespace OpenTelemetry.Metrics;
 
 #if EXPOSE_EXPERIMENTAL_FEATURES
@@ -8,6 +13,9 @@ namespace OpenTelemetry.Metrics;
 /// An ExemplarFilter which makes all measurements eligible for being an Exemplar.
 /// </summary>
 /// <remarks><inheritdoc cref="Exemplar" path="/remarks"/></remarks>
+#if NET8_0_OR_GREATER
+[Experimental(DiagnosticDefinitions.ExemplarExperimentalApi, UrlFormat = DiagnosticDefinitions.ExperimentalApiUrlFormat)]
+#endif
 public
 #else
 /// <summary>

src/OpenTelemetry/Metrics/Exemplar/Exemplar.cs

@@ -1,6 +1,11 @@
 // Copyright The OpenTelemetry Authors
 // SPDX-License-Identifier: Apache-2.0
 
+#if EXPOSE_EXPERIMENTAL_FEATURES && NET8_0_OR_GREATER
+using System.Diagnostics.CodeAnalysis;
+using OpenTelemetry.Internal;
+#endif
+
 using System.Diagnostics;
 
 namespace OpenTelemetry.Metrics;
@@ -10,6 +15,9 @@ namespace OpenTelemetry.Metrics;
 /// Represents an Exemplar data.
 /// </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.ExemplarExperimentalApi, UrlFormat = DiagnosticDefinitions.ExperimentalApiUrlFormat)]
+#endif
 public
 #else
 /// <summary>

src/OpenTelemetry/Metrics/Exemplar/ExemplarFilter.cs

@@ -1,6 +1,11 @@
 // Copyright The OpenTelemetry Authors
 // SPDX-License-Identifier: Apache-2.0
 
+#if EXPOSE_EXPERIMENTAL_FEATURES && NET8_0_OR_GREATER
+using System.Diagnostics.CodeAnalysis;
+using OpenTelemetry.Internal;
+#endif
+
 namespace OpenTelemetry.Metrics;
 
 #if EXPOSE_EXPERIMENTAL_FEATURES
@@ -8,6 +13,9 @@ namespace OpenTelemetry.Metrics;
 /// The base class for defining Exemplar Filter.
 /// </summary>
 /// <remarks><inheritdoc cref="Exemplar" path="/remarks"/></remarks>
+#if NET8_0_OR_GREATER
+[Experimental(DiagnosticDefinitions.ExemplarExperimentalApi, UrlFormat = DiagnosticDefinitions.ExperimentalApiUrlFormat)]
+#endif
 public
 #else
 /// <summary>

src/OpenTelemetry/Metrics/Exemplar/TraceBasedExemplarFilter.cs

@@ -1,6 +1,11 @@
 // Copyright The OpenTelemetry Authors
 // SPDX-License-Identifier: Apache-2.0
 
+#if EXPOSE_EXPERIMENTAL_FEATURES && NET8_0_OR_GREATER
+using System.Diagnostics.CodeAnalysis;
+using OpenTelemetry.Internal;
+#endif
+
 using System.Diagnostics;
 
 namespace OpenTelemetry.Metrics;
@@ -11,6 +16,9 @@ namespace OpenTelemetry.Metrics;
 /// which are recorded in the context of a sampled parent activity (span).
 /// </summary>
 /// <remarks><inheritdoc cref="Exemplar" path="/remarks"/></remarks>
+#if NET8_0_OR_GREATER
+[Experimental(DiagnosticDefinitions.ExemplarExperimentalApi, UrlFormat = DiagnosticDefinitions.ExperimentalApiUrlFormat)]
+#endif
 public
 #else
 /// <summary>

src/Shared/DiagnosticDefinitions.cs

@@ -11,4 +11,5 @@ internal static class DiagnosticDefinitions
 
     public const string LoggerProviderExperimentalApi = "OTEL1000";
     public const string LogsBridgeExperimentalApi = "OTEL1001";
+    public const string ExemplarExperimentalApi = "OTEL1002";
 }