[sdk-metrics] Expose Exemplars stable

OpenTelemetry.sln

@@ -310,7 +310,6 @@ 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\OTEL1003.md = docs\diagnostics\experimental-apis\OTEL1003.md
 		docs\diagnostics\experimental-apis\OTEL1004.md = docs\diagnostics\experimental-apis\OTEL1004.md
 		docs\diagnostics\experimental-apis\README.md = docs\diagnostics\experimental-apis\README.md

docs/diagnostics/experimental-apis/README.md

@@ -27,12 +27,6 @@ Description: Logs Bridge API
 
 Details: [OTEL1001](./OTEL1001.md)
 
-### OTEL1002
-
-Description: Metrics Exemplar Support
-
-Details: [OTEL1002](./OTEL1002.md)
-
 ### OTEL1003
 
 Description: MetricStreamConfiguration CardinalityLimit Support
@@ -57,4 +51,10 @@ Experimental APIs which have been released stable or removed:
     removed add details for alternative solution or reasoning.
 -->
 
-None
+### OTEL1002
+
+Description: Metrics Exemplar Support
+
+Details: [OTEL1002](https://github.com/open-telemetry/opentelemetry-dotnet/blob/b8ea807bae1a5d9b0f3d6d23b1e1e10f5e096a25/docs/diagnostics/experimental-apis/OTEL1002.md)
+
+Released stable: `1.9.0`

src/OpenTelemetry/.publicApi/Experimental/PublicAPI.Unshipped.txt

@@ -8,18 +8,6 @@ OpenTelemetry.Logs.LogRecord.Severity.get -> OpenTelemetry.Logs.LogRecordSeverit
 OpenTelemetry.Logs.LogRecord.Severity.set -> void
 OpenTelemetry.Logs.LogRecord.SeverityText.get -> string?
 OpenTelemetry.Logs.LogRecord.SeverityText.set -> void
-OpenTelemetry.Metrics.Exemplar
-OpenTelemetry.Metrics.Exemplar.DoubleValue.get -> double
-OpenTelemetry.Metrics.Exemplar.Exemplar() -> void
-OpenTelemetry.Metrics.Exemplar.FilteredTags.get -> OpenTelemetry.ReadOnlyFilteredTagCollection
-OpenTelemetry.Metrics.Exemplar.LongValue.get -> long
-OpenTelemetry.Metrics.Exemplar.SpanId.get -> System.Diagnostics.ActivitySpanId
-OpenTelemetry.Metrics.Exemplar.Timestamp.get -> System.DateTimeOffset
-OpenTelemetry.Metrics.Exemplar.TraceId.get -> System.Diagnostics.ActivityTraceId
-OpenTelemetry.Metrics.ExemplarFilterType
-OpenTelemetry.Metrics.ExemplarFilterType.AlwaysOff = 0 -> OpenTelemetry.Metrics.ExemplarFilterType
-OpenTelemetry.Metrics.ExemplarFilterType.AlwaysOn = 1 -> OpenTelemetry.Metrics.ExemplarFilterType
-OpenTelemetry.Metrics.ExemplarFilterType.TraceBased = 2 -> OpenTelemetry.Metrics.ExemplarFilterType
 OpenTelemetry.Metrics.ExemplarMeasurement<T>
 OpenTelemetry.Metrics.ExemplarMeasurement<T>.ExemplarMeasurement() -> void
 OpenTelemetry.Metrics.ExemplarMeasurement<T>.Tags.get -> System.ReadOnlySpan<System.Collections.Generic.KeyValuePair<string!, object?>>
@@ -31,25 +19,10 @@ OpenTelemetry.Metrics.FixedSizeExemplarReservoir.Capacity.get -> int
 OpenTelemetry.Metrics.FixedSizeExemplarReservoir.FixedSizeExemplarReservoir(int capacity) -> void
 OpenTelemetry.Metrics.FixedSizeExemplarReservoir.UpdateExemplar(int exemplarIndex, in OpenTelemetry.Metrics.ExemplarMeasurement<double> measurement) -> void
 OpenTelemetry.Metrics.FixedSizeExemplarReservoir.UpdateExemplar(int exemplarIndex, in OpenTelemetry.Metrics.ExemplarMeasurement<long> measurement) -> void
-OpenTelemetry.Metrics.MetricPoint.TryGetExemplars(out OpenTelemetry.Metrics.ReadOnlyExemplarCollection exemplars) -> bool
 OpenTelemetry.Metrics.MetricStreamConfiguration.CardinalityLimit.get -> int?
 OpenTelemetry.Metrics.MetricStreamConfiguration.CardinalityLimit.set -> void
 OpenTelemetry.Metrics.MetricStreamConfiguration.ExemplarReservoirFactory.get -> System.Func<OpenTelemetry.Metrics.ExemplarReservoir?>?
 OpenTelemetry.Metrics.MetricStreamConfiguration.ExemplarReservoirFactory.set -> void
-OpenTelemetry.Metrics.ReadOnlyExemplarCollection
-OpenTelemetry.Metrics.ReadOnlyExemplarCollection.Enumerator
-OpenTelemetry.Metrics.ReadOnlyExemplarCollection.Enumerator.Current.get -> OpenTelemetry.Metrics.Exemplar
-OpenTelemetry.Metrics.ReadOnlyExemplarCollection.Enumerator.Enumerator() -> void
-OpenTelemetry.Metrics.ReadOnlyExemplarCollection.Enumerator.MoveNext() -> bool
-OpenTelemetry.Metrics.ReadOnlyExemplarCollection.GetEnumerator() -> OpenTelemetry.Metrics.ReadOnlyExemplarCollection.Enumerator
-OpenTelemetry.Metrics.ReadOnlyExemplarCollection.ReadOnlyExemplarCollection() -> void
-OpenTelemetry.ReadOnlyFilteredTagCollection
-OpenTelemetry.ReadOnlyFilteredTagCollection.Enumerator
-OpenTelemetry.ReadOnlyFilteredTagCollection.Enumerator.Current.get -> System.Collections.Generic.KeyValuePair<string!, object?>
-OpenTelemetry.ReadOnlyFilteredTagCollection.Enumerator.Enumerator() -> void
-OpenTelemetry.ReadOnlyFilteredTagCollection.Enumerator.MoveNext() -> bool
-OpenTelemetry.ReadOnlyFilteredTagCollection.GetEnumerator() -> OpenTelemetry.ReadOnlyFilteredTagCollection.Enumerator
-OpenTelemetry.ReadOnlyFilteredTagCollection.ReadOnlyFilteredTagCollection() -> void
 override sealed OpenTelemetry.Metrics.FixedSizeExemplarReservoir.Collect() -> OpenTelemetry.Metrics.ReadOnlyExemplarCollection
 static OpenTelemetry.Logs.LoggerProviderBuilderExtensions.AddProcessor(this OpenTelemetry.Logs.LoggerProviderBuilder! loggerProviderBuilder, OpenTelemetry.BaseProcessor<OpenTelemetry.Logs.LogRecord!>! processor) -> OpenTelemetry.Logs.LoggerProviderBuilder!
 static OpenTelemetry.Logs.LoggerProviderBuilderExtensions.AddProcessor(this OpenTelemetry.Logs.LoggerProviderBuilder! loggerProviderBuilder, System.Func<System.IServiceProvider!, OpenTelemetry.BaseProcessor<OpenTelemetry.Logs.LogRecord!>!>! implementationFactory) -> OpenTelemetry.Logs.LoggerProviderBuilder!
@@ -60,7 +33,6 @@ static OpenTelemetry.Logs.LoggerProviderBuilderExtensions.SetResourceBuilder(thi
 static OpenTelemetry.Logs.LoggerProviderExtensions.AddProcessor(this OpenTelemetry.Logs.LoggerProvider! provider, OpenTelemetry.BaseProcessor<OpenTelemetry.Logs.LogRecord!>! processor) -> OpenTelemetry.Logs.LoggerProvider!
 static OpenTelemetry.Logs.LoggerProviderExtensions.ForceFlush(this OpenTelemetry.Logs.LoggerProvider! provider, int timeoutMilliseconds = -1) -> bool
 static OpenTelemetry.Logs.LoggerProviderExtensions.Shutdown(this OpenTelemetry.Logs.LoggerProvider! provider, int timeoutMilliseconds = -1) -> bool
-static OpenTelemetry.Metrics.MeterProviderBuilderExtensions.SetExemplarFilter(this OpenTelemetry.Metrics.MeterProviderBuilder! meterProviderBuilder, OpenTelemetry.Metrics.ExemplarFilterType exemplarFilter) -> OpenTelemetry.Metrics.MeterProviderBuilder!
 static OpenTelemetry.OpenTelemetryBuilderSdkExtensions.WithLogging(this OpenTelemetry.IOpenTelemetryBuilder! builder) -> OpenTelemetry.IOpenTelemetryBuilder!
 static OpenTelemetry.OpenTelemetryBuilderSdkExtensions.WithLogging(this OpenTelemetry.IOpenTelemetryBuilder! builder, System.Action<OpenTelemetry.Logs.LoggerProviderBuilder!>! configure) -> OpenTelemetry.IOpenTelemetryBuilder!
 static OpenTelemetry.OpenTelemetryBuilderSdkExtensions.WithLogging(this OpenTelemetry.IOpenTelemetryBuilder! builder, System.Action<OpenTelemetry.Logs.LoggerProviderBuilder!>? configureBuilder, System.Action<OpenTelemetry.Logs.OpenTelemetryLoggerOptions!>? configureOptions) -> OpenTelemetry.IOpenTelemetryBuilder!

src/OpenTelemetry/.publicApi/Stable/PublicAPI.Unshipped.txt

@@ -0,0 +1,28 @@
+OpenTelemetry.Metrics.Exemplar
+OpenTelemetry.Metrics.Exemplar.DoubleValue.get -> double
+OpenTelemetry.Metrics.Exemplar.Exemplar() -> void
+OpenTelemetry.Metrics.Exemplar.FilteredTags.get -> OpenTelemetry.ReadOnlyFilteredTagCollection
+OpenTelemetry.Metrics.Exemplar.LongValue.get -> long
+OpenTelemetry.Metrics.Exemplar.SpanId.get -> System.Diagnostics.ActivitySpanId
+OpenTelemetry.Metrics.Exemplar.Timestamp.get -> System.DateTimeOffset
+OpenTelemetry.Metrics.Exemplar.TraceId.get -> System.Diagnostics.ActivityTraceId
+OpenTelemetry.Metrics.ExemplarFilterType
+OpenTelemetry.Metrics.ExemplarFilterType.AlwaysOff = 0 -> OpenTelemetry.Metrics.ExemplarFilterType
+OpenTelemetry.Metrics.ExemplarFilterType.AlwaysOn = 1 -> OpenTelemetry.Metrics.ExemplarFilterType
+OpenTelemetry.Metrics.ExemplarFilterType.TraceBased = 2 -> OpenTelemetry.Metrics.ExemplarFilterType
+OpenTelemetry.Metrics.MetricPoint.TryGetExemplars(out OpenTelemetry.Metrics.ReadOnlyExemplarCollection exemplars) -> bool
+OpenTelemetry.Metrics.ReadOnlyExemplarCollection
+OpenTelemetry.Metrics.ReadOnlyExemplarCollection.Enumerator
+OpenTelemetry.Metrics.ReadOnlyExemplarCollection.Enumerator.Current.get -> OpenTelemetry.Metrics.Exemplar
+OpenTelemetry.Metrics.ReadOnlyExemplarCollection.Enumerator.Enumerator() -> void
+OpenTelemetry.Metrics.ReadOnlyExemplarCollection.Enumerator.MoveNext() -> bool
+OpenTelemetry.Metrics.ReadOnlyExemplarCollection.GetEnumerator() -> OpenTelemetry.Metrics.ReadOnlyExemplarCollection.Enumerator
+OpenTelemetry.Metrics.ReadOnlyExemplarCollection.ReadOnlyExemplarCollection() -> void
+OpenTelemetry.ReadOnlyFilteredTagCollection
+OpenTelemetry.ReadOnlyFilteredTagCollection.Enumerator
+OpenTelemetry.ReadOnlyFilteredTagCollection.Enumerator.Current.get -> System.Collections.Generic.KeyValuePair<string!, object?>
+OpenTelemetry.ReadOnlyFilteredTagCollection.Enumerator.Enumerator() -> void
+OpenTelemetry.ReadOnlyFilteredTagCollection.Enumerator.MoveNext() -> bool
+OpenTelemetry.ReadOnlyFilteredTagCollection.GetEnumerator() -> OpenTelemetry.ReadOnlyFilteredTagCollection.Enumerator
+OpenTelemetry.ReadOnlyFilteredTagCollection.ReadOnlyFilteredTagCollection() -> void
+static OpenTelemetry.Metrics.MeterProviderBuilderExtensions.SetExemplarFilter(this OpenTelemetry.Metrics.MeterProviderBuilder! meterProviderBuilder, OpenTelemetry.Metrics.ExemplarFilterType exemplarFilter) -> OpenTelemetry.Metrics.MeterProviderBuilder!

src/OpenTelemetry/CHANGELOG.md

@@ -18,6 +18,13 @@
   `ExemplarReservoirFactory` property on the View API.
   ([#5558](https://github.com/open-telemetry/opentelemetry-dotnet/pull/5558))
 
+* The experimental APIs previously covered by `OTEL1002` (`Exemplar`,
+  `ExemplarFilterType`, `MeterProviderBuilder.SetExemplarFilter`,
+  `ReadOnlyExemplarCollection`, `ReadOnlyFilteredTagCollection`, &
+  `MetricPoint.TryGetExemplars`) will now be part of the public API and
+  supported in stable builds.
+  ([#5607](https://github.com/open-telemetry/opentelemetry-dotnet/pull/5607))
+
 ## 1.8.1
 
 Released 2024-Apr-17

src/OpenTelemetry/Metrics/Builder/MeterProviderBuilderExtensions.cs

@@ -317,13 +317,10 @@ public static MeterProvider Build(this MeterProviderBuilder meterProviderBuilder
         throw new NotSupportedException($"Build is not supported on '{meterProviderBuilder?.GetType().FullName ?? "null"}' instances.");
     }
 
-#if EXPOSE_EXPERIMENTAL_FEATURES
     /// <summary>
     /// Sets the default <see cref="ExemplarFilterType"/> for the provider.
     /// </summary>
     /// <remarks>
-    /// <inheritdoc cref="Exemplar"
-    /// path="/remarks/para[@experimental-warning='true']"/>
     /// <para>Notes:
     /// <list type="bullet">
     /// <item>The configured <see cref="ExemplarFilterType"/> controls how
@@ -353,14 +350,7 @@ public static MeterProvider Build(this MeterProviderBuilder meterProviderBuilder
     /// 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
-    internal
-#endif
-        static MeterProviderBuilder SetExemplarFilter(
+    public static MeterProviderBuilder SetExemplarFilter(
         this MeterProviderBuilder meterProviderBuilder,
         ExemplarFilterType exemplarFilter)
     {

src/OpenTelemetry/Metrics/Exemplar/Exemplar.cs

@@ -5,30 +5,17 @@
 using System.Collections.Frozen;
 #endif
 using System.Diagnostics;
-#if EXPOSE_EXPERIMENTAL_FEATURES && NET8_0_OR_GREATER
-using System.Diagnostics.CodeAnalysis;
-using OpenTelemetry.Internal;
-#endif
 
 namespace OpenTelemetry.Metrics;
 
-#if EXPOSE_EXPERIMENTAL_FEATURES
 /// <summary>
 /// Exemplar implementation.
 /// </summary>
 /// <remarks>
-/// <para experimental-warning="true"><b>WARNING</b>: This is an experimental API which might change or be removed in the future. Use at your own risk.</para>
 /// Specification: <see
 /// href="https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/sdk.md#exemplar"/>.
 /// </remarks>
-#if NET8_0_OR_GREATER
-[Experimental(DiagnosticDefinitions.ExemplarExperimentalApi, UrlFormat = DiagnosticDefinitions.ExperimentalApiUrlFormat)]
-#endif
-public
-#else
-internal
-#endif
-    struct Exemplar
+public struct Exemplar
 {
 #if NET8_0_OR_GREATER
     internal FrozenSet<string>? ViewDefinedTagKeys;

src/OpenTelemetry/Metrics/Exemplar/ExemplarFilterType.cs

@@ -2,30 +2,17 @@
 // SPDX-License-Identifier: Apache-2.0
 
 using System.Diagnostics;
-#if EXPOSE_EXPERIMENTAL_FEATURES && NET8_0_OR_GREATER
-using System.Diagnostics.CodeAnalysis;
-using OpenTelemetry.Internal;
-#endif
 
 namespace OpenTelemetry.Metrics;
 
-#if EXPOSE_EXPERIMENTAL_FEATURES
 /// <summary>
 /// Defines the supported exemplar filters.
 /// </summary>
 /// <remarks>
-/// <inheritdoc cref="Exemplar" path="/remarks/para[@experimental-warning='true']"/>
 /// Specification: <see
 /// href="https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/sdk.md#exemplarfilter"/>.
 /// </remarks>
-#if NET8_0_OR_GREATER
-[Experimental(DiagnosticDefinitions.ExemplarExperimentalApi, UrlFormat = DiagnosticDefinitions.ExperimentalApiUrlFormat)]
-#endif
-public
-#else
-internal
-#endif
-    enum ExemplarFilterType
+public enum ExemplarFilterType
 {
     /// <summary>
     /// An exemplar filter which makes no measurements eligible for becoming an

src/OpenTelemetry/Metrics/Exemplar/ReadOnlyExemplarCollection.cs

@@ -2,26 +2,13 @@
 // SPDX-License-Identifier: Apache-2.0
 
 using System.Diagnostics;
-#if EXPOSE_EXPERIMENTAL_FEATURES && NET8_0_OR_GREATER
-using System.Diagnostics.CodeAnalysis;
-using OpenTelemetry.Internal;
-#endif
 
 namespace OpenTelemetry.Metrics;
 
-#if EXPOSE_EXPERIMENTAL_FEATURES
 /// <summary>
 /// A read-only collection of <see cref="Exemplar" />s.
 /// </summary>
-/// <remarks><inheritdoc cref="Exemplar" path="/remarks/para[@experimental-warning='true']"/></remarks>
-#if NET8_0_OR_GREATER
-[Experimental(DiagnosticDefinitions.ExemplarExperimentalApi, UrlFormat = DiagnosticDefinitions.ExperimentalApiUrlFormat)]
-#endif
-public
-#else
-internal
-#endif
-    readonly struct ReadOnlyExemplarCollection
+public readonly struct ReadOnlyExemplarCollection
 {
     internal static readonly ReadOnlyExemplarCollection Empty = new(Array.Empty<Exemplar>());
     private readonly Exemplar[] exemplars;

src/OpenTelemetry/Metrics/MetricPoint.cs

@@ -2,9 +2,6 @@
 // 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 OpenTelemetry.Internal;
 
@@ -365,23 +362,13 @@ public ExponentialHistogramData GetExponentialHistogramData()
         return false;
     }
 
-#if EXPOSE_EXPERIMENTAL_FEATURES
     /// <summary>
     /// Gets the exemplars associated with the metric point.
     /// </summary>
-    /// <remarks><inheritdoc cref="Exemplar" path="/remarks/para[@experimental-warning='true']"/></remarks>
     /// <param name="exemplars"><see cref="ReadOnlyExemplarCollection"/>.</param>
     /// <returns><see langword="true" /> if exemplars exist; <see langword="false" /> otherwise.</returns>
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
-#if NET8_0_OR_GREATER
-    [Experimental(DiagnosticDefinitions.ExemplarExperimentalApi, UrlFormat = DiagnosticDefinitions.ExperimentalApiUrlFormat)]
-#endif
-    public
-#else
-    [MethodImpl(MethodImplOptions.AggressiveInlining)]
-    internal
-#endif
-        readonly bool TryGetExemplars(out ReadOnlyExemplarCollection exemplars)
+    public readonly bool TryGetExemplars(out ReadOnlyExemplarCollection exemplars)
     {
         exemplars = this.mpComponents?.Exemplars ?? ReadOnlyExemplarCollection.Empty;
         return exemplars.MaximumCount > 0;

src/OpenTelemetry/ReadOnlyFilteredTagCollection.cs

@@ -5,28 +5,16 @@
 using System.Collections.Frozen;
 #endif
 using System.Diagnostics;
-#if EXPOSE_EXPERIMENTAL_FEATURES && NET8_0_OR_GREATER
-using System.Diagnostics.CodeAnalysis;
-using OpenTelemetry.Internal;
-#endif
 
 namespace OpenTelemetry;
 
-#if EXPOSE_EXPERIMENTAL_FEATURES
 /// <summary>
 /// A read-only collection of tag key/value pairs which returns a filtered
 /// subset of tags when enumerated.
 /// </summary>
 // Note: Does not implement IReadOnlyCollection<> or IEnumerable<> to
 // prevent accidental boxing.
-#if NET8_0_OR_GREATER
-[Experimental(DiagnosticDefinitions.ExemplarExperimentalApi, UrlFormat = DiagnosticDefinitions.ExperimentalApiUrlFormat)]
-#endif
-public
-#else
-internal
-#endif
-    readonly struct ReadOnlyFilteredTagCollection
+public readonly struct ReadOnlyFilteredTagCollection
 {
 #if NET8_0_OR_GREATER
     private readonly FrozenSet<string>? excludedKeys;

src/Shared/DiagnosticDefinitions.cs

@@ -11,7 +11,10 @@ internal static class DiagnosticDefinitions
 
     public const string LoggerProviderExperimentalApi = "OTEL1000";
     public const string LogsBridgeExperimentalApi = "OTEL1001";
-    public const string ExemplarExperimentalApi = "OTEL1002";
     public const string CardinalityLimitExperimentalApi = "OTEL1003";
     public const string ExemplarReservoirExperimentalApi = "OTEL1004";
+
+    /* Definitions which have been released stable:
+    public const string ExemplarExperimentalApi = "OTEL1002";
+     */
 }